Installing Packages with Composer

Installing available packages with the Composer dependency manager

In the previous article in this series, we looked at installing Composer. In this one, we'll discuss some of the finer points of installing packages with Composer.

MODX logo

Installing Packages with Composer

Installing a program with Composer is often as easy as typing "composer require vendor_name/package_name". Composer will perform the following steps:

  1. Get the current version of the package (unless you specify a specific version) at the default Composer repository (
  2. Update the composer.json file in the current directory to include that package as a requirement
  3. Download the package to the vendor directory. If there is no composer.json file in the current directory, one will be created there
  4. Update the composer.lock file, which records the currently installed packages
  5. Check the downloaded package for dependencies
  6. Repeat the steps above recursively for all dependent packages

Although the composer.json file is updated automatically, it's common for developers to edit it manually. Most often, this is to specify version information. Here are some examples that use the logging package, Monolog. The form for a package name in composer.json is vendor_name/package_name, though often the vendor and the package name are the same. Here are some examples:

"require": {
    "codeception/codeception": "2.4.5", // exactly 2.4.5 (will never update)

    /*    // >, <, >=, <= | specify upper and/or lower bounds */

    "codeception/codeception": ">=2.4.5", // the latest version above or equal to 2.4.5

    "codeception/codeception": "<2.4.5", // the latest version up to 2.4.5

    /* explicit range */
    "codeception/codeception": ">=2.4.5" < 3.0.2, // above 2.4.5 and below 3.0.2

    /*  * (wildcard) */
    "monolog/monolog": "3.0.*", // >=3.0 but less than 4.0.0

    /* ~ (allows only the last digit to go up) */
    "monolog/monolog": "~2.4.5", // means >=2.4.5 but less than 2.5.0
    "monolog/monolog": "~2.4", // >=2.4.0 but less than 3.0.0

    /* ^ (avoids breaking changes using semantic versioning) */
    "monolog/monolog": "^2.4.5", // >=2.4.5 but less than 3.0.0
    "monolog/monolog": "^0.3.2", // >=0.3.2  but less than 0.4.0 // except when major version is 0

You can also specify which build of the version you get by adding -stable or -dev to end of the version specification. Using -dev may get you the latest development build. With -stable, you should get only stable versions. You can also use -beta, -alpha, and -RC, but that's seldom done unless you're looking for a particular pre-release version.

"monolog/monolog: >=2.4.5-stable"
"monolog/monolog" >=2.4.5-dev <3.0.0-dev"

You can also ask for a stable version when requiring or updating from the command line like this:

composer require monolog/monolog --prefer-stable
composer update monolog/monolog --prefer-stable

A more complete discussion of Composer version constraints can be found here.

Basic Composer Commands

Composer has many commands, which you can see by typing composer with no parameters, but let's take a look at the most commonly used ones.

We talked about composer require above. It creates or updates the composer.json file and installs the specified package and any dependent packages to your project's vendor directory. It creates or updates the composer.lock file as well.

The composer update command is usually used later when you know or suspect that new versions of one or more of the packages in your composer.json file have been released. It's also used when you've updated your composer.json file manually. If there are no updates, update won't change anything. It there are updates, though, it will update the packages based on the constraints you've put in the composer.json file. If new releases have been installed, the composer.lock file and the autoloader will also be updated.

Once the composer.lock file exists, you can use composer install to install the versions listed there. The composer.json file is ignored and the exact packages listed in composer.lock are installed. If composer.lock doesn't exist, install will use composer.json. It will install the latest versions of all packages listed in composer.json (subject to their constraints), then it will create composer.lock with the installed versions listed.

If you want to install a new package, you can use require, or you can edit your composer.json file, then run composer install. The latter is usually easier if you have version constraints to specify.

You could edit composer.json to add your new package, then run composer update, but this is more dangerous because it will update *all* packages listed in composer.json that have available updates.

The best practice is either to use install for new packages, or to specify the specific package when running update: e.g., composer update monolog/monolog.

The composer remove command does just what you'd think it does. It removes the specified package and any packages it depends on (unless they are also dependencies of some other package). It also removes the dependency from composer.json and updates the composer.lock file.

The composer self-update command updates Composer itself to the latest version. Usually, you'll want to ask for a stable version:

composer self-update --stable

For a full list of Composer commands and how to use them, look at this page.


While composer.json contains "suggestions" about which versions to install, the composer.lock file contains a record of the exact versions installed for all the packages. If, for example, you accidentally delete your vendor directory, running composer install will restore it completely based on the contents of the composer.lock file, as long as you haven't deleted the composer.lock file.

This has a bearing on the commands you use with Composer. Running composer install will set all packages to the versions recorded in composer.lock. Running composer update, on the other hand, will update all packages to their latest versions (subject to the version constraints in composer.json) *and* it will update the composer.lock file with any new versions. This could break your package, so it's best to only run composer update in your development environment and test carefully to make sure nothing is broken when packages get updated. It's also best to run update on specific packages rather than the whole vendor directory. In other words, do this:

composer update monolog/monolog

not this:

composer update

Note also that using composer require monolog/monolog at the command line is the equivalent of manually adding monolog/monolog to the dependencies section of composer.json and then running composer install monolog/monolog, or if that's the only new package in composer.json, composer install.

Coming Up

In the next article in this series, we'll see how to install Codeception and PhpUnit using Composer.

For more information on how to use MODX to create a web site, see my web site Bob's Guides, or better yet, buy my book: MODX: The Official Guide.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.