Plugin registration: named arguments

[distantnative]

This PR …

Background: #5764

Enhancement

• Plugin registration with named arguments
• Allow passing plugin info, e.g. version, as argument that gets merged with the info from composer.json

Kirby::plugin(
    name: 'my/plugin',
    extends: [],
    info: [
        'homepage' => 'https://my-plugin.example.com'
    ],
    version: '1.0.0'
);

Deprecated

• Plugin registration: Passing info or root in plugin extends array. Instead pass these as standalone named arguments.

Docs

• Update examples of how to register a plugin throughout getkirby.com to use named arguments

Ready?

• In-code documentation (wherever needed)
• Unit tests for fixed bug/feature
• Tests and checks all pass

For review team

• Add changes & docs to release notes draft in Notion

[bastianallgeier]

A couple first thoughts and steps:

• I think we should not trigger deprecation warnings in v4.2 This would feel a lot like a breaking change. I already removed them. It would be better to keep track of this properly and remove it in v5 as a breaking change
• I've refactored the plugin tests and also fixed an issue after the new order how to recognise the version
• I have no idea so far why the assets test fails and how this could be related.

[distantnative]

@bastianallgeier we should keep the deprecation messages, but we can silence them first via https://github.com/getkirby/kirby/blob/main/src/Cms/Helpers.php#L31

[bastianallgeier]

@distantnative that's clever. I have to say that I never fully explored the options of the Helpers class. I just brought them back.

[distantnative]

@bastianallgeier I moved the version from its own named argument into the new info named argument. Felt more consistent as otherwise we might would want to add all info entries as their own named arguments. Which could be an option as well.

[lukasbestle]

One argument for a separate version: named argument could be that is easier to match with a regex like /^(\s*version:\s*["'])([^"']+)(["'])/m.

Inside an array, it could use " or ' as keys, value indentation etc., which makes it more complex. But it wouldn't be impossible either. So fine with both.

[distantnative]

Yea I really get that. I opted against it in the PR because I think it makes the whole setup a bit easier/consistent if not one of the info parts get it's extra treatment than others. But open to change this.

[lukasbestle]

Yeah, makes sense. If we want to make it possible to register plugins without a composer.json at all, that definitely fits better.

[bastianallgeier]

TBH, I would vote for separate named arguments if they are really relevant. In addition to that there could still be a meta or info pool. But the arrays of schema-less info have gotten us into so many difficult situations, so I would avoid them wherever possible.

[distantnative]

So all info values from composer json also as named arguments?

[bastianallgeier]

I would really keep it simple for now and solve the version problem with this PR and then maybe add more later or think some more about an optional info array

[distantnative]

Ok. The optional info array we need anyways as this has been supported so far already, just as subentry of the extends array. So it's more about whether to have all the info in that array or have version (and/or others) also as another additional named argument on their own (but still with necessary support to also allow it in the info array).

[distantnative]

@lukasbestle @bastianallgeier now with additional version arg

[afbora]

I'm thinking loud. Why don't we use the Plugin class constructor like other model class:

class Plugin
{
  public function __construct(array $props) {
    // check and set props
  }
}

This covers props to be added later/future and ensures consistency with other models.

[lukasbestle]

@afbora The array $props pattern is pretty old and we used it before named arguments were a thing. Those are much more solid because of their type guarantees and also because they allow IDE hints, which a plain array can't without a lot of boilerplate comment blocks.