8

What is the advantage of explicitly including a composer.json file in my plugin if potential users of my plugin can already get it as a package through WPackagist?

8

TL;DR

If you want to support Composer, adding a composer.json is better then just let WPackagist create a package for you.

There are several reasons, no one is really important, but considering that to create a composer.json does not require much effort, it probably worth it.

composer.json Benefits

Below a non-exhaustive list of benefits of using composer.json.

Developer friendly

When you require a package, Composer looks into repositories to find that specific package. Packagist and WPackagist are 2 repositories.

The difference is that Packagist is always parsed by Composer, while WPackagist have to be manually added to the project composer.json.

To require a plugin on Packagist you need a single line in composer.json:

"require": {
    "your-name/your-plugin-name":"1.*",
}

To require a plugin on WPackagist you need to also configure repositories:

"repositories":[
    {
        "type":"composer",
        "url":"http://wpackagist.org"
    }
],
"require": {
    "your-name/your-plugin-name":"1.*",
}

This is also relevant when using command line, see

composer create-project your-name/your-plugin-name

VS

composer create-project wpackagist-plugin/your-plugin-name --repository-url=http://wpackagist.org

Performance

When a project contains more repositories, Composer pings all of them to find information about packages.

So adding WPackagist repository, slows down installation. Also consider that all the servers can be down, for any reson. It happen to much bigger companies than the one behind WPackagist, so every repository you add, it is an additional possible point of failure.

Configuration

On of the advantages of having a composer.json is that you can configure the way Composer will fetch your plugin.

For example, you can use configure the package name in the name property, instead of letting WPackagist create the package name for you.

Moreover there are a lot of configuration that can be done in composer.json, just some few examples:

  • you can use the branch-alias setting to improve the compatibility of development version of the plugin
  • even if you have no dependencies, you can use the require setting to set a minimum PHP version,
  • the conflict setting let you explicit inform about conflicting packages...

and so on.

Ownership awareness

When you require a plugin from WPackagist the "vendor" part of the package name is always wpackagist-plugin.

So people will require you plugin like:

"require": {
    "wpackagist-plugin/your-plugin-name":"1.*",
}

If you put the plugin on packagist, you can use your own vendor prefix, and I think is better for marketing:

"require": {
    "your-name/your-plugin-name":"1.*",
}

Autoload

Composer provide autoload for packages. If you decide to use Composer, you can benefit of it. However, considering that you are shipping your plugin to official repo you need to take into account that the majority of your user will probably install your plugin not using Composer. It means that you have to possibilities:

  • ship the "vendor" folder (that contains the autoload) insider your plugin folder in the official repo
  • make use of a custom autoloader or a manual loading mechanism in case the plugin is used without Composer.

The second possibility is mentioned only because your plugin has no dependencies handled by Composer, otherwise ship vendor folder is the only possibility to make your plugin work without Composer, but is not issue-free: when different plugins are installed with embedded vendor folder there is the possibility of version conflicts if different plugins ships different version of same package.

Explicit Composer support

By adding composer.json you make people know that you explicitly support Composer. For example, when I search for a plugin, to find a composer.json in the plugin folder is a big plus for me, as I tend to don't use plugins that don't do that.

Moreover, there are tools that target plugin explictly supporting Composer.

For example, I have a script that prevents automatic updates for plugin / themes that have a composer.json.

1

The composer.json file usually contains extra information that are not available in the readme.txt file. So it could simply serve as a readme file for the dependencies of your plugin.

Since Composer is in the toolbox of many developers, it could help them to better understand how your plugin is bolted together.

For e.g. abondoned .org plugins, it would be handy to have that file available for someone that would like to fork it, update it and extend it.

If we want to register our plugin on packagist.org, then we would of course need it.

  • Thanks @birgire. In my particular case, my plugin has no dependencies so there's less of a need to provide a composer.json file as a "readme" for developers. I was thinking more along the lines of using composer.json purely for the autoloading capabilities. Is this a common thing to do? I'm wondering if you have any thoughts on that? Thanks again. – henrywright Jan 2 '16 at 15:00
  • I think that could still give us information on how you autoload and that your plugin has no explicit 3rd party dependencies for Composer. I tried to search (google) the .org plugin directory with composer.json site:plugins.svn.wordpress.org but that didn't work. @henrywright – birgire Jan 2 '16 at 21:11
  • If I use the psr-4 key in composer.json, Composer generates a vendor/autoload.php file, which I suppose I could commit to the wp.org repo. spl_autoload_register() is used instead of __autoload() so if anyone else authoring a plugin does the same there shouldn't be conflicts. – henrywright Jan 2 '16 at 22:47
  • You're welcome, JetPack ships with a very simple composer.json file and the Yoast SEO plugin ships with a vendor directory @henrywright - just noticed this nice summary by gmazzap +1 – birgire Jan 6 '16 at 15:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.