Getting Started

Composer is package manager for PHP. Explaining purpose of package manager is beyond scope of this article.

This article, actually section, will describe how to use Composer within WordPress ecosystem.  We believe this will benefit developers as well as system-admins.

Assumptions

1. You are comfortable with git.
2. You are comfortable with command-line interface.

Scope

As composer is a big topic, it’s better to define scope first. We will cover following:

1. Using composer to manage entire WordPress project including theme/plugin dependencies
   • Managing WordPress themes and plugins hosted on wordpress.org repo
   • Managing WordPress themes and plugins and any other dependency hosted elsewhere as git/svn repo or as a zip file
   • Custom composer commands
2. Adding composer support to your own WordPress theme/plugin project

We will also cover some composer concepts for newbies.

Installing Composer

You may follow official instructions present here.

We follow and recommend slightly different installation as below:

On Ubuntu (Linux)

curl -sS https://getcomposer.org/installer | php -- --filename=composer --install-dir=/usr/local/bin

This will install composer binary in /usr/local/bin path. This will make it easy to run composer commands from anywhere in system.

On Mac

We recommend using brew:

brew install composer

How Composer Works?

Composer has a really good documentation which can explain this in much better way.

Everything in project revolves around composer.json

To understand concept in quickly, lets divide entire workflow between: development and deployment.

Developer Workflow

1. A project is started with a composer.json file. It can be created from scratch, copy/pasted from existing sample or can be generated using composer commands like composer init/composer create-project.
2. Project dependencies are added to composer.json file.  Again dependencies can be added by directly editing composer.json file in text-editor or using composer command composer require.
3. Dependencies can in turn have their own composer.json file for their sub-dependencies.
4. Dependencies are often downloaded from packagist.org which is default repo for composer packages. We can add other composer package repos and can even install dependency from any git/svn repo or simply a zip file.
5. After we are done with defining dependency, we run composer update command. This downloads all dependencies locally and generates a composer.lock file.
6. By convention, we commit both – composer.json and composer.lock files to git repo. And git push our project/package to something like Github.

Steps 5 and 6 need to followed everytime we need to update dependencies.

Note: Please note that sometime a dependency update may not require making changes to composer.json file. Only running composer update command would suffice.

Deployment Workflow

1. git clone a composer-powered project.
2. Run composer install commands which will download dependencies based on composer.lock content.
3. If composer.lock file is not present, composer install will refer to composer.json. But we strongly recommend using composer.lock in production setup.

As you can see, deployment process is very streamline. You may add composer install to your webhooks or deploy scripts.

How Composer Works for entire WordPress Project

Use Case: If you want to deploy a WordPress project across multiple-servers or may be using a cloud-hosting platform like Amazon ElasticBeanstalk, you need to put entire WordPress project under version control.

Usually this involves using git submodules, which we find tedious. Here is a simpler and better way to achieve same with composer.

Developer Workflow

1. Create a WordPress project with composer.json in root folder (htdocs typically).
2. composer.json will contain required WordPress version, theme and plugin dependencies.
3. Technically plugin and theme repos can also have their own dependencies, if they are packaged as composer project. Remember, in composer world your dependency no need to be a composer package itself!
4. For themes and plugins hosted on wordpress.org, there is a composer repo at wpackagist.org. This composer repo syncs with wordpress.org and makes each theme and plugin’s available as composer package.
5. After we are done with defining dependency, we run composer update command. This downloads wordpress core, themes and plugins locally and generates a composer.lock file.
6. By convention, we commit both – composer.json and composer.lock files to git repo. And git push our project/package to something like Github.

Steps 5 and 6 need to followed everytime we add or remove themes/plugins or change WordPress core version.

Deployment Workflow

1. git clone a composer-powered project.
2. Run composer install commands which will download WordPress core, themes, plugins and any other dependencies  based on composer.lock content.
3. If composer.lock file is not present, composer install will refer to composer.json. But we strongly recommend using composer.lock in production setup.

We also use some custom composer scripts as part of deployment flow. More about it will be explained later.

Composer Commands

Following are commands we use quite often:

1. composer init – to generate composer.json interactively. We really don’t use this but copy/paste existing files.
2. composer update – download dependencies based on composer.json and generate/update composer.lock file.
3. composer install –  download dependencies based on composer.lock file. If composer.lock doesn’t exists, download dependencies based on composer.json
4. composer diagnose – check if composer.json is correct. This does much more than validating JSON.
5. composer require – add one or more dependencies without editing composer.json manually.
6. composer remove – remove one or more dependencies without editing composer.json manually.