Introducing WP Plugin Composer

I’ve been doing custom WordPress plugin development for a long time now. At this point, anyone who’s worked with me, attended one of my WordCamp presentations, or spoken with me at any length about modern development knows just how much love I have for Composer. It’s the de-facto tool for PHP dependency management, and for a great reason: it provides great out-of-the-box benefits, such as class autoloading, dependency suggestions, minimum requirements definitions, events-driven scripts, and more.

Over time, Composer has been seeing more and more use by the WordPress community. I’ve personally worked with it frequently with my agency clients, but something I haven’t really considered is how to leverage its benefits while minimizing its trade-offs when the plugin I’m writing is distributed. You see, some engineers may want to continue to install plugins as part of an automated process, while others might still prefer the manual process of uploading a ZIP file and activating a plugin using the WordPress dashboard.

The challenge is to account for both of these scenarios while also keeping plugin repositories bereft of third-party code. I woke up this morning with my wheels spinning on this issue, and have spent the last few years working on a potential approach: WP Plugin Composer.

The idea here is simple: WP Plugin Composer is essentially a starter kit for Composer-based plugin development. It ships with a composer.phar file, a composer.json file, a light functions.php containing a callback to the WordPress register_activation_hook method and a “maybe” autoloader, and a single, empty Plugin class file in the src directory. The rest? Well, that’s up to the developer the decide.

When developing plugins with this library, engineers should be able to work as they usually would: pulling in useful third-party packages, building out application logic, leveraging Composer’s class autoloading, and committing only the code they write.

When publishing plugins, however, typically need to do one of two things:

1. Ship that plugin with all of its third-party dependencies
2. Include a detailed set of instructions aimed at developers about the myriad steps necessary to install and activate the plugin

In theory, by including the composer.phar file and a well-defined composer.json file, we should be able to let WP-CLI or the web server do the work for us.

Using WP Plugin Composer, when the plugin is activated, it checks one thing: can it find its own class file? If it can’t, it locates the packaged composer.phar file, extracts it to a directory within the plugin, then runs composer install on the main plugin directory. This pulls down all of the dependencies into the plugin’s vendor directory, and then the plugin subsequently locates and loads the Composer class autoloader.

If the class file does exist at runtime? Well, we assume that the Composer autoload file has been required further upstream, and that the plugin was also installed using Composer. No need to generate an autoloader, and no need to perform the composer.phar extraction process.

At this point, this idea is primarily a proof-of-concept for me, but something I’m pretty excited to try out in my personal projects in the coming weeks. If you’d like to give it a try and see how it works for you, too, you can do so in one of two ways:

1. Run git clone https://github.com/jmichaelward/wp-plugin-composer [your-plugin-name] inside the plugins directory of your WordPress installation, then follow the steps in the README.
2. Run composer create-project jmichaelward/wp-plugin-composer [your-plugin-name] -s dev inside the plugins directory of your WordPress installation, then follow the steps in the README.

I’m interested in hearing how this works for folks, and whether it provides the kind of utility I think it does! If you try it out and want to leave me some feedback, feel free to drop me line. I’d love to hear from you.