Nexcess
Nexcess Blog Logo
January 20, 2021

Using Composer with WordPress

WordPress has been around since 2003 and has become the default tool for most people looking to start a website. While it’s come a long way from its roots as a blog engine, the underlying technology hasn’t made the same leaps that the user experience has.

WordPress development still revolves around many of the standards that were present in 2003. While this can make it more accessible to people due to the lower technical understanding required, it also means that many new development resources are not compatible with WordPress out of the box.

Today, we’re going to take a look at one of those newer tools called Composer. Let’s see how it can fit into your WordPress workflow and discuss why you may want to try it out.

What is Composer?

Every bit of code you write has dependencies. If you’re writing a WordPress plugin your biggest dependency is WordPress itself. Without the core functions that WordPress provides, it’s likely that your plugin isn’t useful at all. Outside of WordPress itself, you could need a modern SOAP client like nusoap to interface with SOAP-based APIs.

In the past, most people would simply copy the repository for nusoap into a directory in their plugin and then include the files needed to use the library. This is where Composer can step in and simplify some of the management of your dependencies.

Composer is a dependency manager. It’s specifically designed to make it easy to install and manage dependencies. This can become especially crucial if you’re working in a team and want to make sure that every member of the team is using the same libraries as they do their development work.

At its base, Composer is a JSON file that details the dependencies you have installed and which versions of the dependencies you want to use. You can see a basic example below that includes the nusoap dependency.

{

    “require”: {

        “econea/nusoap”: “^0.9.10”

    }

}

When I run composer require econea/nusoap in my plugin it will install nusoap for me and lock it to the version specified. In this case, I’m using 0.9.10 and will continue to use that unless I tell Composer to upgrade the dependency.

This has the advantage over simply downloading and including nusoap because I can use composer update to update all my dependencies without needing to go see if there are updates and manually download them into my project. Composer takes over the management of resources at this level.

Getting Started with Composer

Installing composer is fairly straightforward.

On Windows

If you’re on Windows then there is an installer provided to simplify the process. It will install the latest version of Composer and make it accessible globally for your projects.

Linux/Unix/macOS

On any of these platforms, you have a few more steps to get Composer setup. To start, run the commands needed to download Composer and get it setup.

php -r “copy(‘https://getcomposer.org/installer’, ‘composer-setup.php’);”

php -r “if (hash_file(‘sha384’, ‘composer-setup.php’) === ‘756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3’) { echo ‘Installer verified’; } else { echo ‘Installer corrupt’; unlink(‘composer-setup.php’); } echo PHP_EOL;”

php composer-setup.php

php -r “unlink(‘composer-setup.php’);”

Next, you’ll want to run Composer globally for local development so we’ll need to adjust the default install to ensure that it’s available any time we want to use Composer. You can move Composer to be globally available with the following command executed from the same directory you just downloaded Composer from.

mv composer.phar /usr/local/bin/composer

Upgrading Composer

On Windows and macOS all you need to do to upgrade to the latest version of Composer is run composer self-update. If you’re on Linux/Unix then you’ll need to run sudo apt update && upgrade so that your system checks for the latest versions then you can run composer self-update to get the latest version.

Now that you’re set up, let’s take a look at using Composer to install WordPress.

Install WordPress with Composer

What about if you want to manage an entire site with Composer? First, you need to decide if WordPress is the dependency of the project or the core of the project? Yup, a little brain-twisting.

WordPress can be considered a dependency of the project because the end goal for your customers isn’t to have WordPress installed. They want a store or a blog and that depends on you installing WordPress. This is the stance that a project like Roots takes with its Composer based Bedrock WordPress setup called Bedrock.

Using Bedrock means that you don’t have to tell Composer about WPackagist because it’s already set up. It’s where I recommend you start if you’re looking to manage an entire site with Composer.

To install Bedrock run the following command.

composer create-project roots/bedrock

This will give you the following file structure.

├── composer.json

├── .env

├── config

│   ├── application.php

│   └── environments

│       ├── development.php

│       ├── staging.php

│       └── production.php

├── vendor

└── web

    ├── app

    │   ├── mu-plugins

    │   ├── plugins

    │   ├── themes

    │   └── uploads

    ├── wp-config.php

    ├── index.php

    └── wp

This is very different than the standard WordPress setup. To start you have your composer.json file at the root of the install. This is where you’ll see your Composer configuration. 

Your .env file is where you can store the different database configurations. This is needed because your local site and your live site will have different database passwords and usernames. The default wp-config.php file will understand the variables you put in your .env file because Bedrock uses those variables instead of hard coding in the database connection information.

You’re .env file should be ignored in your Git repository. When you configure a new site you add a new .envfile to it with the required database configuration information.

There are a few other variables that you need to set up here to get Bedrock started, which are all detailed in their documentation.

Under the config folder areis different default configurations for the environments you’ll be using. In development, this turns on error reporting, and in your production environments, it makes sure that error logging won’t interfere with the smooth operation of your site.

With Bedrock as a base, you can now use Composer to install your WordPress plugins via WPackagist.

WPackagist is a mirror of the WordPress theme and plugin repository. This is needed because by default most plugins and themes are not available for Composer to install. The mirror adds the required files for each plugin so that Composer can be used to manage the plugins.

If you wanted to install WooCommerce in your Bedrock based WordPress install you need to require WooCommerce first, composer require wpackagist-plugin/woocommerce, then you need to tell Composer to install the dependencies, composer install.

Now you can go to the admin area of your WordPress install and activate WooCommerce and get building out your site. To update WooCommerce when a new version comes out, or to update WordPress, you need to run composer update.

This is where a Composer based project can get into a bit of trouble. If you run your updates through the WordPress admin then you’ll have a mismatch between what Composer expects and what WordPress has installed. If you’re going to go with Composer, then stick with using it as your updating tool and don’t work via the WordPress admin.

When Should You Use Composer?

I’m sure that many of you are asking why Composer is such a great tool for WordPress development. WordPress wasn’t built with Composer in mind, so to work with it you have to jump through some hoops to make it work well.

For plugin and theme developers there is a clear case that Composer can make it easier to deal with dependencies you need to bring in from the wider PHP ecosystem. For WordPress developers, the argument is less clear. Some like to use Composer to manage their whole site as Roots does. This can let you have fewer files managed by Git, but that has never seemed like a compelling case to me. 

The case I like is that Composer can make it easy to have different dependencies for different environments. You can then use your deployment process to deploy those dependencies in your environments and not have to manually manage them.

As a developer, you also need to take your client’s needs into account. If they don’t have a development team around to manage the site long term, then they may run into issues with a non-standard WordPress install. In some cases, their hosts may tell them that support isn’t available because they’re not using the normal way of installing and using WordPress. When you serve clients you always need to balance the cool technology you use with what the client can handle long term.

For this reason alone, I don’t use Composer in my full site projects. My clients are going to be managing them day to day for years and I don’t want to put up any extra barriers. We both want their sites to run smoothly for years to come.

If you’re looking to upgrade your PHP skills with modern technologies, then you should certainly take a look at how Composer can fit into your WordPress workflows.

Avatar for Curtis McHale
Curtis McHale
Curtis is a husband, father, developer and business coach. He specializes in helping people build a business that lets them spend time with their family instead of working all the time.