Composer dependencies in WordPress plugins

Composer is a dependency management tool. It allows you to add libraries as a dependency, so you don’t have to solve every problem yourself. You can make use of the solutions provided by others to save yourself some time and likely account for edge-cases you hadn’t even thought of.

Why would you use dependencies?

For example, you want to create a WordPress plugin that messages comments to your posts directly to Slack. It may even have features that allow you to approve them and reply to them from there as well.

You could develop all of this yourself. This would undoubtedly be a useful exercise to better understand the Slack API. However, it’s also likely that this would be a significant time investment to create and maintain. If this is your first time building something for the Slack API you may also end up with something that’ll require at least some amount of refactoring down the line.

Alternatively, there’s a library called BotMan you could use to do all of this for you. You could install this library with Composer and make use of all of its features in your WordPress plugin. Composer will allow you to easily keep the library up to date. It will even generate autoload code for you, so you don’t have to take care of loading any files yourself.

Getting started with Composer

To get started on this the first thing you’d need to do, assuming you’ve installed Composer, is to initialize Composer for your project. You can do so by running the following in your terminal:

composer init --type=wordpress-plugin

You’ll be prompted with a series of questions on the name of your project, license, author, etc. If you’re unsure about any of them, you can simply press enter to go with the default value. You can always change everything later by editing your composer.json file directly.

The flag wordpress-plugin you’re passing tells Composer that your project is a WordPress plugin. So, if someone else were to add your plugin as a dependency of their project then Composer knows it should be installed into the WordPress plugins directory. This doesn’t just make it easy for you to use the code of others, it also becomes easier for others to use your code.

In order for your plugin to be installed correctly when used by others, the first dependency you’ll have to add is the Composer installers package. This contains all the code Composer needs to install your package in the right place. You can add it using the following command:

composer require composer/installers:~1.0

This tells Composer to install the Composer installers package and to do so at a version that’s compatible with 1.0. As such this could install it at version 1.0.1 or even 1.9 but will never install 2.0. This is because Composer packages are expected to keep to the semver standard which means that the first number, the major, is expected to change when backwards-incompatible changes are introduced.

Installing dependencies

Once you’ve got that set up you can start adding more dependencies. If you wanted to install BotMan you’d run the following command in your terminal:

composer require botman/botman botman/driver-slack

This would install both the main BotMan library as well as the Slack driver for it. In this case you’re telling Composer to install two dependencies. And, since you’re not passing any version numbers, Composer will automatically install the latest stable version.

Setting up the Composer autoloader

The next thing you have to do is to require the generated autoload.php file. This will set up autoloading for all classes in your dependencies:

if ( is_readable( __DIR__ . '/vendor/autoload.php' ) ) {
    require __DIR__ . '/vendor/autoload.php';
}

The reason you’re first checking if autoload.php is readable is that your plugin itself may be installed by Composer. In this case, the autoload.php would be located in the project that’s depending on your plugin. It would be loaded by that project and the autoloader would load both your code as well as all of your dependencies.

You can add this code at the top of your main plugin file. This will ensure that whenever you call a class from one of your dependencies Composer will take care of loading it for you.

Updating dependencies

During all of this, you might have noticed a new autoload.lock file appeared. This is where Composer stores the actual installed versions of your dependencies. This means that if you were to install them again it knows exactly which versions to install and won’t update without you noticing.

If a new update for a dependency is released, you’ll have to explicitly tell Composer to update. For example, if BotMan has had a new release you can upgrade by running the following command:

composer update botman/botman

This will update BotMan but will hold to the version constraints you specified when first installing the dependency. As such this usually won’t update to a new major version. If you wanted to update to the latest version ignoring any version constraints you’d simply install it again by running:

composer require botman/botman

Conclusion

Composer is a great tool that allows you to easily use libraries written by others and to share your own code. This can save you a ton of time developing plugins and allows you to focus on the unique features you provide rather than having to reinvent the wheel every time.

If you’re looking to use Composer dependencies in your plugin on a large scale be sure to read our post on how to isolate and ship your dependencies!

Herre Groen

I'm the Head of Technology at Yoast. I love making code easy to understand, fun to write and fast to run!