Plugin loading

[weirdan]

Status

Ready for merge. Outstanding todo items can be added in subsequent PRs

Overview

Plugin installation/distribution system that piggy-backs on composer infrastructure. Follow-up to #849

Screenshot

Details

Available commands for psalm-plugin

• psalm-plugin list - lists available and enabled plugins
• psalm-plugin enable 'Plugin\Class\Name' - enables plugin (modifies psalm.xml)
• psalm-plugin disable 'Plugin\Class\Name' - disables plugin (modifies psalm.xml)

Discovering plugins

https://packagist.org/packages/list.json?type=psalm-plugin

Plugin installation

composer install plugin-vendor/plugin-package-name

Plugin authoring

• Skeleton plugin (usable with composer create-project ...): https://github.com/weirdan/psalm-plugin-skeleton
• Plugins are identified by package type field, which should contain psalm-plugin string.
• extra.psalm.pluginClass should refer to the name of the class implementing Psalm\PluginApi\PluginEntryPointInterface
• Plugins are enabled by adding <pluginClass class="Qualified\Class\Name"/> to config file
• Psalm\PluginApi namespace should be used to provide stable interfaces plugins can rely on

Sample plugin

Packagist: https://packagist.org/packages/weirdan/psalm-doctrine-collections
Git repo: https://github.com/weirdan/psalm-doctrine-collections

Todo

• tests
• better config file search (split and reuse)
• cli argument to specify config file name
• better output for psalm-plugin
• phar compatibility
• composer skeleton project for plugins
• ability to refer to plugins by package name (cli only)
• interface for plugin entry point
• Plugin configuration (allows arbitrary content for pluginClass)

Further development

• ~ migration path for legacy plugins~ Doesn't seem to be possible, because current plugins directly depend on Psalm internals (?)
• better formatting for modified xml file
• composer plugin to (optionally) enable plugin upon installation
• documentation on plugin installation and authoring
• interfaces for plugin dependencies

[weirdan]

@muglug here's the draft I promised. It's quite rough around the edges at the moment, but shows the general direction I had in mind.

[muglug]

It's quite rough around the edges at the moment

I'll refrain from digging to deep, but I'm very on-board with command-line tools.

psalm-plugin enable 'Plugin\Class\Name'

why not use the composer name here?

[weirdan]

why not use the composer name here?

It's in todo ("ability to refer to plugins by package name (cli only)"). But if this is going to be used to manage non-composer plugins, there's also got to be a way to refer to plugins that are not packages. Since I don't want file names there, it leaves class names as the only choice.

[muglug]

Ah sorry for missing that. I guess it's 100% fine to use either package name or classname there, as they can't overlap

This wouldn't work with a phar, right? Current plugins don't either, but I'm not massively bothered

[weirdan]

This wouldn't work with a phar, right?

I think it could be made to. Autoloading is functional in phar builds, so as long as interfaces used by plugin is not mangled by box rewriting it should just work.

Current plugins don't either, but I'm not massively bothered

Is it because their base class is prefixed?

[weirdan]

One point I'd like to decide before moving further is naming. How do we name this entire thing: "plugins", "extensions", "bundles", something else? "plugins" is currently ambiguous, as it refers both to old plugins as well to this new package based thing. My preference would be keep this named "plugins", add a LegacyPlugin adapter for old way of doing things and eventually deprecate it. But choosing a different name may also have its merits.

[muglug]

Yeah, "plugins" is fine, I think. I don't know how many, if any, have implemented their own plugins outside of Vimeo, but this would be part of a V3 change if it broke them.

[muglug]

Once your plugin is ready, it can go in https://github.com/psalm!

[weirdan]

@muglug Is it ok to promote symfony/console from indirect dev-dependency to direct dependency? Would help with output and a bit with testability.

[coveralls]

Coverage decreased (-0.02%) to 87.521% when pulling 903f5a4 on weirdan:plugin-loading into 6cf6d2c on vimeo:master.

[weirdan]

Skeleton plugin (usable with composer create-project ...): https://github.com/weirdan/psalm-plugin-skeleton

[weirdan]

@muglug I believe it's ready for merge.

[muglug]

@weirdan great! I don’t have my computer with me for the next 24 hours, but I’ll review once I’m back

[muglug]

Got back a little later than intended, I've left some suggestions for documentation.

On a first glance this looks good - would you be able to migrate the plugins in the examples directory to the new format?

[weirdan]

@muglug all done

[muglug]

Awesome, thanks. I'm going to make this part of a 3.0 release together with the Internal namespace changes. I'll change Psalm\Plugin to Psalm\LegacyPlugin or somesuch, with the API changes in the branch mentioned above. Should merge to master sometime this weekend. I'll create a 2.x branch to preserve that version so I can port select fixes where necessary.

[muglug]

Just created my first composer plugin: https://github.com/psalm/phpunit-psalm-plugin

It works! Thanks so much