Using Composer for Magento

This is a guide to using Composer to manage Magento extensions. If you find managing extensions difficult, or if you’ve heard of Composer but don’t know where to start, then this is the guide for you!

What Composer Does

Composer is a package manager for PHP. This means that it manages many different PHP packages, not just those intended for Magento. Composer was created in 2011 as an alternative to the aging PEAR, and has a more modern architecture and featureset—similar to NPM for Node.js or Bundler for Ruby. Composer packages are project specific and installed under vendor, unless explicitly installed system-wide.

The Packagist website shows which packages can be installed through Composer. There is also a repository of Magento specific packages available on the Firegento website.

Packagist is used as a default repository for Composer, but you can add Firegento’s repository by editing your Composer configuration file. First, however, you’ll need to install Composer itself.

Let’s Get Composing

There are three ways to install Composer.

The first method is the one recommended by the Composer developers:

curl -s http://getcomposer.org/installer | php

Just run this at the command line, and Composer will magically appear on your system. You could also save the output and review it before piping it into PHP, of course, if you are concerned (legitimately so) about executing unsandboxed code straight from the internet.

Another way of installing Composer is by downloading composer.phar:

wget http://getcomposer.org/composer.phar

Put this in the top-level root of your project directory structure.

Later, when you want to actually run Composer, you’ll have to execute this script in PHP rather than running it as an installed command like so:

php ./path/to/composer.phar

Alternatively, you can install it system-wide by running something like:

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

Assuming /usr/local/bin is in your PATH, then composer will be available system-wide.

If you’re using OS X, then you can install Composer using Homebrew:

brew update
brew install homebrew/php/composer

Using Homebrew is highly recommended on OS X. This will also result in a system-wide composer command.

Configuring Composer

Composer is configured on a per-project basis. So for every PHP project that you create, you’ll need to write a Composer configuration file for it. This file is called composer.json, and it lives in the top-level root of your project directory structure.

Rather than explaining every possible field and what each one means, for which you can consult the documentation, it’s easier to learn by example. Here’s a very simple example that you can copy, paste, and modify to your own requirements:

{
  "name": "yournickname/your_project_name",
  "license": "Apache-2.0",
  "type": "magento-module",
  "description": "Description of your project",
  "homepage": "http://example.com/your/project/homepage",
  "require": {
    "magento-hackathon/magento-composer-installer": "*",
    "phpunit/phpunit": "3.7.*"
  },
  "require-dev": {
    "ecomdev/mage-ci": "dev-master"
  },
  "authors":[{
    "name": "Your Name"
  }],
  "extra": {
    "magento-root-dir": "magento/"
  }
}

In this example your project is called yournickname/your_project_name, and it depends on the standard version of phpunit and the development version of mage-ci as examples.

Obviously you should change these details. The require values, for example, are just real world representatives of common Magento module dependencies. But you may also have noticed that magento-composer-installer is listed there. As should be evident from the name, this is an essential part of the Composer machinery itself in the context of the Magento ecosystem.

In Magento projects, packages are not isolated to a specific subdirectory. Instead they’re spread out amongst template, theme, locale, and other directories. So we need a tool to manage this “spreading out” of the data; and that tool is magento-composer-installer. By listing mageno-composer-installer as a requirement, Composer will automatically resolve and download it for us, and then use it to handle our Magento package dependencies in the proper Magento way.

You may want to make sure that some parts of your setup aren’t visible to the outside world. If so, then you’ll want to encapsulate the public section into a subdirectory. You should use the magento-root-dir property to indicate this, under extra. In the example above, the value is set to the subdirectory magento/. If you don’t want to use a subdirectory, you can set the value to ./ instead.

Using Composer

To resolve all the dependencies in your project, change directory to the top-level root, and then issue the following command if you installed system-wide:

composer update

Or this command if you have a local composer.phar:

php composer.phar install

This will install the latest version of all the specified packages (that meet the version criteria specified). It will also create a composer.lock file. You should commit this file to your repository, and then you can use composer install to re-install those exact same versions — for example, when another developer works on the project, or you deploy to production. This ensures that everybody is on the same version.

If you want to update the packages run composer update again, and re-commit the composer.lock for others to composer install from.

To update only a specific package, use composer update <package/name>.

Adding and deleting requirements is easy too. Using the composer require <package/name>:<version> and to remove a package simply update your composer.json and run composer update <package/name>.

Running composer require without arguments will allow you to add packages interactively.

Conclusion

We went through the basics of setting up Composer especially to work with Magento. Now you can easily add and remove dependencies to and from your Magento extension. There’s a lot more to Composer than this, and the official documentation details all the intricacies that you may need to become acquainted with.

Did you find this guide helpful? Are you using Composer in your own projects? How do you think it compares with PEAR and package managers for other languages? We’d love to hear from you, and we’re actively reading and participating in comment threads, so please leave us a note below!