Blogs

Basic usage – Composer

Posted on by admin
  • Introduction
  • composer.json: Project settings
    • Key requires

      • Package

    • names Package

      • version

    • restrictions

    • Installing dependencies Confirm the composer.lock

    • file in version control
    • Installing from composer.lock
  • Updating dependencies to their latest versions
  • Packagist
  • Platform Packages Automatic loading

Introduction#

For our basic usage introduction, we will install monolog/monolog, a log library. If you have not yet installed Composer, refer to the Getting Started chapter.

Note: For the sake of simplicity, this introduction will assume that you have performed a local installation of Composer.

composer.json: Project Settings#

To start using Composer in your project, all you need is a composer.json file. This file describes the dependencies of the project and can also contain other metadata. Usually, it should go in the top directory of your VCS project/repository. Technically, you can run Composer anywhere, but if you want to publish a package to Packagist.org, you’ll need to be able to find the file at the top of your VCS repository.

The require# key

The first thing you specify in composer.json is the require key. You’re telling Composer which packages your project depends on.

{ “require”: { “monolog/monolog”: “2.0.*” } }

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

Composer uses this information to find the correct set of files in the “repositories” package that is checked in using the repository key or, in Packagist.org, the default package repository. In the example above, because no other repository has been registered in the composer.json file, it is assumed that the monolog/monolog package is registered in Packagist.org. (Read more about Packagist and repositories.)

Package Names

#

The package name consists of a provider name and the project name’s. Often, these will be identical: the provider name only exists to avoid name conflicts. For example, it would allow two different people to create a library called json. One could be called igorw/json, while the other could be seldaek/json.

Learn more about package publishing and package naming. (Note that you can also specify “platform packages” as dependencies, allowing you to require certain versions of the server software. See platform packages below.)

Package Version Restrictions

#

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

Read the versions for more detailed information about versions, how versions relate to each other, and version restrictions.

How does Composer download the correct files? When you specify a dependency in composer.json, Composer first takes the name of the package you requested and looks for it in any repository you have registered with the repository key. If you haven’t registered any additional repositories, or can’t find a package with that name in the repositories you’ve specified, go to Packagist.org (below).

When Composer finds the correct package, either in Packagist.org or in a repository that you specified, it uses the versioning functions of the package’s VCS (that is, branches and tags) to try to find the best match for the version constraint that you specified. Be sure to read about package versions and resolution in the versions article.

Note: If you are trying to require a package but Composer fails with respect to package stability, the specified version may not meet the default minimum stability requirements. By default, only stable versions are considered when searching for valid package versions in the VCS.

You might run into this if you’re trying to require development, alpha, beta, or RC versions of a package. Learn more about stability indicators and the minimum stability key on the schema page.

Installing dependencies#

To initially install the dependencies defined for your project, you must run the update command

. php composer.phar update

This will cause Composer to do two things:

  • It resolves all dependencies listed in the composer.json file and writes all packages and their exact versions to the composer.lock file, locking the project into those specific versions. You must commit the composer.lock file to the project repository so that everyone working on the project is locked into the same dependency versions (below). This is the main function of the update command.
  • It then implicitly executes the install command. This will download the dependencies’ files to the project’s vendor directory. (The vendor directory is the conventional location for all third-party code in a project.) In our example above, you would end up with the Monolog source files in vendor/monolog/monolog/. Because Monolog has a dependency on psr/log, files for that package can also be found inside vendor/.

Tip: If you’re using git for your project, you probably want to add provider in your .gitignore. You don’t really want to add all that third-party code to your versioned repository.

Commit your composer.lock

file to version control#

Committing this file to version control is important because it will cause anyone setting up the project to use exactly the same versions of the dependencies you are using. Your CI server, production machines, other developers on your team, everything and everyone runs on the same dependencies, mitigating the possibility of errors that affect only some parts of deployments. Even if you develop alone, in six months, when reinstalling the project, you can be sure that the installed dependencies are still working, even if your dependencies released many new versions since then. (See the following note about using the update command.)

Note: For libraries it is not necessary to confirm the lock file, see also: Libraries – Lock file.

Installing from

composer.lock# If there is already a composer.lock file in the project folder, it means that you ran the update command

before or that someone else

in the project ran the update command and confirmed the composer.lock file in the project (which is good).

Either way, running install when there is a composer.lock file resolves and installs all the dependencies you listed in composer.json, but Composer uses the exact versions listed in composer.lock to make sure that the package versions are consistent for everyone working on the project. As a result, you will have all the dependencies requested by your composer.json file, but they may not all be in the latest versions available (some of the dependencies listed in the composer.lock file may have published newer versions since the file was created). This is by design, it ensures that your project does not break due to unexpected changes in dependencies.

Therefore, after getting new changes from your VCS repository, we recommend that you run a Composer installation to ensure that the provider directory is synchronized with your composer.lock file.

php composer.phar install Updating dependencies

to their latest versions#

As mentioned earlier, the composer.lock file prevents you from automatically getting the latest versions of your dependencies. To upgrade to the latest versions, use the update command. This will look for the latest matching versions (according to your composer.json file) and update the lock file with the new versions.

Updating php composer.phar

Note: Composer will display a warning when running an installation command if composer.lock has not been updated since changes were made to composer.json that could affect dependency resolution.

If you just want to install, update, or remove a dependency, you can explicitly list it as an argument:

php composer.phar update monolog/monolog […]

Packagist#

Packagist.org is the primary repository for Composer. A Composer repository is basically a package source: a place where you can get packages from. Packagist aims to be the central repository that everyone uses. This means that you can automatically require any package that is available there, without specifying where Composer should look for the package.

If you go to the Packagist.org website, you can browse and search for packages.

It is recommended that any open source project using Composer publish its packages to Packagist. A library does not need to be in Packagist to be used by Composer, but it allows discovery and adoption by other developers more quickly.

Platform

packages# Composer

has platform packages, which are virtual packages for things that are installed on the system but that Composer cannot actually install. This includes PHP itself, PHP extensions, and some system libraries.

  • php represents the user’s PHP version, allowing them to apply constraints, for example, ^7.1. To require a 64-bit version of php, you can require the php-64bit package.

  • hhvm represents the version of the HHVM runtime and allows you to apply a constraint, for example, ^2.3.

  • ext-<name> allows you to require PHP extensions (includes core extensions). Version control can be quite inconsistent here, so it’s often a good idea to set the restriction to *. An example of an extension pack name is ext-gd.

  • lib-<name> allows you to make restrictions on the versions of the libraries used by PHP. The following are available: curl, iconv, icu, libxml, openssl, pcre, uuid, xsl.

You can use show -platform to get a list of locally available platform packages

.

Autoload#

For libraries that specify autoload information, Composer generates a provider/autoload .php file. You can include this file and start using the classes that those libraries provide without any additional work:

they require __DIR__. ‘/vendor/autoload.php’; $log = new Monolog\Logger(‘name’); $log->pushHandler(new Monolog\Handler\StreamHandler(‘app.log’, Monolog\Logger::WARNING)); $log->warning(‘Foo’);

You can even add your own code to the autoloader by adding an autoload field to composer.json.

{ “autoload”: { “psr-4”: {“Acme\\”: “src/”} } }

Composer will register a PSR-4 autoloader for the Acme namespace.

Define a namespace mapping to directories. The src directory would be at the root of the project, at the same level as the vendor directory. An example file name would be src/Foo.php which contains an Acme\Foo class.

After adding the autoload

field, you need to run this command again:

php composer.phar dump-autoload

This command will regenerate the vendor/autoload.php file. See the Auto-Dump-Load section for more information.

Including that file will also return the autoloader instance, so you can store the return value of the include call in a variable and add more namespaces. This can be useful for automatically loading classes into a test suite, for example.

$loader = require __DIR__ . ‘/vendor/autoload.php’; $loader->addPsr4(‘Acme\\Test\\\’, __DIR__); In addition to PSR-4 autoloading,

Composer also supports PSR-0, class maps, and automatic file upload. See the autoload reference for more information.

See also the documents on autoloader optimization.

Note: Composer provides its own autoloader. If you don’t want to use that one, you can include vendor/composer/autoload_*.php files, which return associative arrays that allow you to set up your own autoloader.

← Introduction | Libraries →

Have you found a typo? Are there any problems with this documentation? Fork and edit it!

admin