Composer works by reading the composer.json file found in the root of your project, which will contain all the requirements and dependencies:

composer.json

{
  "require": {
    "twig/twig": "1.16.*"
  }
}

The preceding snippet is quite clear: it's defining a dependency of our project on Twig (http://twig.sensiolabs.org/). This is a template engine with a clear and compact syntax. It's also defining a specific dependency on any version of Twig starting with 1.16.

Modifying the composer.json file by hand can be prone to human errors, and sometimes it might be necessary, as we will see later on, to add the packages to your require or require-dev section via the command line using the following command:

$ composer require "twig/twig:1.16.*"

This way the composer.json file will be automatically created if it does not already exist, and the package with its dependencies will be installed for you. Alternatively, if you've created the file yourself or if you've received the file as part of a project, you can invoke the install command as follows:

$ composer install
Loading composer repositories with package information
Installing dependencies (including require-dev)
  - Installing twig/twig (1.6.5)
    Downloading: 100%         

Writing lock file
Generating autoload files

The normal behavior of the preceding command is to fetch the required packages as archives (called dist in composer jargon) for stable sources, or via repository if either the dist is not available or if the package is in some stage that is not stable (for example, beta or dev).

You can change this behavior by using the --prefer-dist option to force searching for the dist even for development packages, or --prefer-source to force the checkout from repository rather than dist for stable packages.

As you will see by listing the content of the directory, Composer will install all libraries into your project folder under the /vendor directory and create a composer.lock file in the root folder that will hold a snapshot of the current state of the installation, locking the installed libraries to the specific version defined in the lock file, as shown in the following:

$ tree -L 2
.
├── composer.json
├── composer.lock
└── vendor
    ├── autoload.php
    ├── composer
    └── twig

When sharing your code, you need to commit the composer.lock file, so everyone in your team and any other environment you will deploy to will run exactly the same version of the dependencies you have, mitigating the risk of bugs affecting only some environments. Composer will look for the lock file first before deciding to use the JSON file to download a more up-to-date version based on the definitions.

On the other hand, it is not recommended to commit the /vendor directory to your VCS as it can cause several problems, such as the following:

This heavily depends on your deployment policy, but, in general, it will be better to have your environments and team mates run the composer install command on their own.

If you ever need to update the dependencies, you can simply issue the following command:

$ composer update

Or to update a specific package, the command will be the following:

$ composer update twig/twig [...]

The [...] means you can add as many packages to be updated with a single command.

By creating the composer.json file, you are also defining your project as a package. This is a package that depends on other packages. The only difference is that your project is without a name, yet.

Composer can help you here in defining your project/package in a more consistent and clear way. Consider the following command:

$ composer init

This will start by asking you for some basic information regarding your project, including the requirements that you want for your project, and then create (or overwrite) the composer.json file, as shown in the following:

Package name (<vendor>/<name>) [peach/yii2composer]:
Description []: Installing Yii 2 from scratch with composer
Author [Matteo 'Peach' Pescarin <[email protected]>]:
Minimum Stability []: dev
License []: GPL-3.0

Among these, the one worth noticing is the Minimum Stability option: it provides a way to control the stability of the packages. By omitting it, it defaults to stable. This option combined with "prefer-stable": true (or false if you want to have the dev versions of your dependencies) will give you enough power to decide the policy of stability of the dependencies where this is not explicitly defined.

It will then move into setting the dependencies interactively, as shown in the following:

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]?
Search for a package []: twig

Found 15 packages matching twig

   [0] twig/twig
   ...

Enter package # to add, or the complete package name if it is not listed []: 0
Enter the version constraint to require []: @dev

The search can be anything, and it works the same way as you would by searching on the website (https://packagist.org). If you want to have a more clear idea of what you're going to install, you probably want to have a look at the website: you need to be aware of the dependencies and browse the code to check it does what it says on the tin.

Knowing how to use the version constraints can be quite important in any project with just a few dependencies. According to https://getcomposer.org/doc/01-basic-usage.md#package-versions, the following are the possible keywords you need to be aware of:

Composer provides further granularity when selecting specific packages, specifically you can filter by stability by adding @dev (or alpha, beta, RC or stable).

Sometimes, you are forced to use an unstable version, either because of the lack of a stable version or because the stable version ships with a bug that has been fixed in the master (dev)!

Together with require, which defines the list of fundamental packages that are a direct dependency, require-dev defines instead the secondary packages used for development, such as libraries for running tests, performing debugging, and so on. However, these are not fundamental for the application to work, as shown in the following:

Would you like to define your dev dependencies (require-dev) interactively [yes]?

You can also skip adding packages for require, and then add them later using the following command:

$ composer require

While for require-dev, at least with the version I've got installed at the time of writing this book, you need to add them manually as seen at the beginning.

At this point of the process, you'll be able to review the JSON that will be written before confirming it, as shown in the following:

{
    "name": "peach/composer",
    "description": "A Composer project",
    "require": {
        "twig/twig": "@dev"
    },
    "license": "GPL-3.0",
    "authors": [
        {
            "name": "Matteo 'Peach' Pescarin",
            "email": "[email protected]"
        }
    ],
    "minimum-stability": "dev"
}

Do you confirm generation [yes]?
Would you like the vendor directory added to your .gitignore [yes]?
$

Once you've got your composer.json file created, you can edit it and tweak it to your liking. There are many other options that can be specified. Refer to https://getcomposer.org/doc/04-schema.md.

By compiling your composer.json file, you are actually creating a package yourself that could be shared on Packagist with other developers.

The process itself is not particularly difficult, as you just need to add a few additional options, as defined in the JSON schema documentation (https://getcomposer.org/doc/04-schema.md#the-composer-json-schema), and publish your code using a Git, subversion or mercurial repository. You can also decide to publish just a dist package. Refer to the documentation at https://getcomposer.org/doc/ for more information if you want to take a step in this direction.

Once you've created your composer.json file, you can start installing all the dependencies as follows:

$ composer install --prefer-dist

Composer lets you decide how to fetch all the requirements and, in this particular case, we gave preference to dist files when available. The result is the following:

Loading composer repositories with package information
Installing dependencies (including require-dev)
  - Installing twig/twig (dev-master 72aa82b)
    Downloading: 100%         

Writing lock file
Generating autoload files
$