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.
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:
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
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:
Alternatively, you can install it system-wide by running something like:
/usr/local/bin is in your
composer will be available system-wide.
If you’re using OS X, then you can install Composer using Homebrew:
Using Homebrew is highly recommended on OS X. This will also result in a system-wide
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:
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
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:
Or this command if you have a local
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>.
composer require without arguments will allow you to add packages interactively.
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!