Using Composer Within Your WordPress Site

WordPress plugins can add a lot of additional functionality, but even custom plugins can require dependencies that are not available to WordPress out of the box. Because of this, many developers have turned to Composer - a dependency manager for PHP applications.

Inside this article, we'll show you how to use and configure Composer on your WordPress site.

Composer Dependencies vs. Managed Hosting

Before we begin, we want to note that while Composer is excellent for the many legitimate use-cases, you will want to ensure that you're not limiting the power of managed WordPress hosting.

By introducing additional dependencies that are not managed by Pagely, you may be limiting some of the great features that managed WordPress hosting has to offer, such as automatic plugin and theme updates.

When using Composer to manage dependencies, please keep in mind that those dependencies can no longer be tracked and monitored by Pagely when ensuring the stability of your site. If a Composer dependency were to cause breaking changes to your site, you may need to rely on your developer to resolve the issue and support may be limited.

Tips When Using Composer on Managed WordPress Sites

Narrow Your Scope

Does Composer need to be used on the WordPress application level or could it be narrowed to the plugin directory or even contained within the plugin itself?

By narrowing your scope, you can dramatically lower the impact if something were to go wrong, while keeping other dependencies managed by Pagely.

For example, if you have a custom plugin with Composer dependencies, the best practice would be to perform any build scripts or dependency management before the plugin is updated on uploaded. By doing this, only the plugin itself would need to be manually managed, while the rest of your plugins will be safely managed by Pagely's managed update mechanisms.

Avoid Things That Managed WordPress Hosting Already Does For You

WordPress Packagist is a great tool for keeping all of your plugins maintained within Composer, but can come at a cost when using a managed WordPress host. Since updates are already managed for you, an additional update mechanism isn't usually needed.

Of course, Pagely's automatic plugin update system will only be able to update plugins that can be updated from within the WordPress admin dashboard. If it's a custom plugin that you're managing, WordPress Packagist may still be a good option.

Composer CLI Basics

Before we get into setting up common use-cases for using Composer on your WordPress sites, here's a quick rundown of the basics. Of course, if you're already experienced with Composer, feel free to skip over this section and head down to the next one.

Initializing Composer

The following command will initialize Composer in the current directory and create a composer.json file:

composer init

From here, you can define the various settings for your project as well interactively define your dependencies.

Requiring a Dependency

To require a dependency and save it to your composer.json file, you can use the following command from within your project's root directory:

composer require my_example_package_name

Installing Dependencies

Once you have a composer.json file and have defined your dependencies, you can issue the following command to install them:

composer install

Upon running this command, Composer will download any of your dependencies defined in your composer.json file and install them to the vendor directory for you to use, as well as generate any autoloaders defined by your packages or in your own configuration.

Composer Configuration Basics (composer.json)

Most of your regular interaction with Composer will likely be inside the CLI, but there's also several other things that can be done to further customize how dependencies are installed. Here's a few useful things that might come in handy.

Defining Production Dependencies

This is the most basic usage of composer. Each time you require a new package in the CLI, a new requirement will be set inside the composer.json file. These requirements look like this:

{
  "require": {
    "namespace/package-name": "^2.6"
  }
}

Defining Development Dependencies

If you have packages such as PHPCS that are used only in development and wouldn't normally exist on a production environment, the require-dev property can be used to define them. This is similar to a normal dependency and would look like this:

{
  "require-dev": {
    "namespace/package-name": "^2.6"
  }
}

Custom Repository Locations

Need to require a package that's not in the public Composer repository? You can define additional sources from where packages can be pulled like this:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/pagely/composer-example"
    }
  ],
  "require": {
    "pagely/composer-example": "dev-mybranchname"
  }
}

As you can see from the above, we've defined a custom repository for a source on GitHub, then required it using the name of the branch as the version.

For custom package locations, Composer supports the following version control systems:

• Git
• Subversion
• Mercurial
• Fossil

Autoloading PHP Classes

When running a Composer installation on your WordPress project, Composer will automatically generate an autoload.php file for autoloading your PHP classes. If you're already using Composer for dependencies inside a WordPress plugin, this is a great way to register your autoloaders all in one file.

Configuring an autoloader inside your composer.json file looks like this:

{
  "autoload": {
    "psr-4": {
      "Pagely\\Example\\": "src/"
    },
  }
}