Create a gist now

Instantly share code, notes, and snippets.

What would you like to do?

Introduction

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project
depends on and it will manage (install/update) them for you.

Dependency management

Composer is not a package manager in the same sense as Yum or Apt are. Yes, it deals with "packages" or
libraries, but it manages them on a per-project basis, installing them in a directory (e.g. vendor) inside your
project. By default it does not install anything globally. Thus, it is a dependency manager. It does however
support a "global" project for convenience via the global command.

This idea is not new and Composer is strongly inspired by node's npm and ruby's bundler.

Suppose:

  1. You have a project that depends on a number of libraries.
  2. Some of those libraries depend on other libraries.

Composer:

  1. Enables you to declare the libraries you depend on.
  2. Finds out which versions of which packages can and need to be installed, and installs them (meaning it downloads them into your project).

System requirements

Composer requires PHP 5.3.2+ to run. A few sensitive php settings and compile flags are also required, but
when using the installer you will be warned about any incompatibilities.

To install packages from sources instead of simple zip archives, you will need git, svn, fossil or hg depending on
how the package is version-controlled.

Composer is multi-platform and we strive to make it run equally well on Windows, Linux and OSX.

Basic usage

Introduction

For our basic usage introduction, we will be installing monolog/monolog, a logging library. If you have not yet
installed Composer, refer to the Intro chapter.

composer.json: Project Setup

To start using Composer in your project, all you need is a composer.json file. This file describes the
dependencies of your project and may contain other metadata as well.

The require Key

The first (and often only) thing you specify in composer.json is the require key. You are simply telling
Composer which packages your project depends on.

{
   "require": {
       "monolog/monolog": "1.0.*"
   }
}

As you can see, require takes an object that maps package names (e.g. monolog/monolog) to version
constraints
(e.g. 1.0.*).

Composer uses this information to search for the right set of files in package "repositories" that you register using
the repositories key, or in Packagist, the default package repository. In the above example, since no other
repository has been registered in the composer.json file, it is assumed that the monolog/monolog package
is registered on Packagist.

Package Names

The package name consists of a vendor name and the project's name. Often these will be identical - the vendor
name just exists to prevent naming clashes. For example, it would allow two different people to create a library
named json. One might be named igorw/json while the other might be seldaek/json.

Read more about publishing packages and package naming here.

Package Version Constraints

In our example, we are requesting the Monolog package with the version constraint 1.0.*. This means any
version in the 1.0 development branch, or any version that is greater than or equal to 1.0 and less than 1.1 (
>=1.0 <1.1).

Please read versions for more in-depth information on versions, how versions relate to each other, and on
version constraints.

How does Composer download the right files ?

When you specify a dependency in composer.json, Composer first takes the name of the package that you have requested and
searches for it in any repositories that you have registered using the repositores key. If you have
not registered any extra repositories, or it does not find a package with that name in the repositories you
have specified, it falls back to Packagist.
When Composer finds the right package, either in Packagist or in a repo you have specified, it then
uses the versioning features of the package's VCS (e.i., branches and tags) to attempt to find the best
match for the version constraint you have specified.
Note: If you are trying to require a package but Composer throws an error regarding package stability,
the version you have specified may not meet your default minimum stability requirements. By default
only stable releases are taken into consideration when searching for valid package versions in your
VCS.
You might run into this if you are trying to require dev, alpha, beta, or RC versions of a package. Read
more about stability flags and the minimum-stability key on the schema page.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment