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/"
},
}
}
In the example above, we're simply registering an autoloader, based on the PSR-4 standards, to autoload classes within the src directory.
We won't go too deep into autoloaders or the various options available within Composer, but if you'd like to read more about it, take a look at Composer's autoload documentation.
Using Composer to Manage Custom WordPress Plugins and Themes
If you have a custom WordPress plugin or theme that needs to be updated, Composer is a great way to do it. Since Composer is already installed on all Pagely VPS and Enterprise accounts, it's generally as simple as a putting a bit of configuration in place. Here's how to do it.
Preparing Your WordPress Plugin/Theme For Composer Installs
Before the WordPress plugin or theme can be easily installed with Composer, you'll need to define a few things inside the plugin itself. To do so, open up your plugin and perform the following steps:
- If you don't already have a composer.json file inside the root of your plugin, begin by running composer init on the plugin's root directory.
- If you're using composer init, you'll be prompted to provide the Package Type. Enter wordpress-plugin or wordpress-theme to tell the installer that it's a WordPress plugin or theme.
- If you're already using Composer within the plugin or theme, open your package.json file and ensure that that the type property is set to wordpress-plugin or wordpress-theme.
- Next, you'll want to use composer require to add the "composer/installers" dependency like this:
composer require composer/installers - Finally, push the plugin/theme to your preferred version control system.
Installing Custom WordPress Plugins and Themes With Composer
Composer already comes pre-installed on all Pagely VPS and Enterprise managed WordPress hosting accounts. Once you've prepared your custom plugin or theme to use Composer with the steps previously outlined in this article, you're ready to install it.
Note: As with any new changes to your site, we always recommend testing things on a development environment first to ensure that it doesn't impact your live site if something were to go wrong.
- Begin by accessing your Pagely VPS over SSH.
- Once logged in, navigate to your site that you want to install the plugin on.
cd ~/sites/example.com
- Next, create your site's composer.json file by running composer init and following the prompts:
composer init
- After the file has been created, we'll need to make a few changes to point to the custom repository. To do so, open your composer.json file using your preferred text editor.
nano composer.json
- Inside the Composer configuration file, add the repositories property to point at your plugin/theme's version control repository. It should looks something like this:
{
"repositories": [
{
"type": "vcs",
"url": "git@github.com:JeffMatsonPagely/composer-example-plugin.git"
}
} - Next, you'll want to add your plugin to the require property so that Composer knows to install and maintain your package. This should reflect the name that you defined in inside your plugin/theme's composer.json file, as well as the branch that it should pull from (prefixed by "dev-").
It should look something like this:{
"require": {
"jeffmatson/composer-example-plugin": "dev-master"
}
} - Your final composer.json should look something like this:
Once your changes have been made, save your file and exit the editor.{
"name": "jeffmatson/composer-wp-example",
"type": "project",
"repositories": [
{
"type": "vcs",
"url": "git@github.com:JeffMatsonPagely/composer-example-plugin.git"
}
],
"require": {
"jeffmatson/composer-example-plugin": "dev-master"
},
"authors": [
{
"name": "Jeff Matson",
"email": "jeff@example.com"
}
]
} - Finally, run composer install to install your dependencies.
composer install
Composer will now install all of your dependencies. Since you've configured your dependency as a WordPress plugin or theme, it'll be correctly installed into the theme or plugin directory for you.