PHP Dependency Management

There are a ton of PHP libraries, frameworks, and components to choose from. Your project will likely use several of them — these are project dependencies. Until recently, PHP did not have a good way to manage these project dependencies. Even if you managed them manually, you still had to worry about autoloaders. That is no longer an issue.

Currently there are two major package management systems for PHP - Composer and PEAR. Composer is currently the most popular package manager for PHP, however for a long time PEAR was the primary package manager in use. Knowing PEAR’s history is a good idea, since you may still find references to it even if you never use it.

Composer and Packagist

Composer is the recommended dependency manager for PHP. List your project’s dependencies in a composer.json file and, with a few simple commands, Composer will automatically download your project’s dependencies and setup autoloading for you. Composer is analogous to NPM in the node.js world, or Bundler in the Ruby world.

There is a plethora of PHP libraries that are compatible with Composer and ready to be used in your project. These “packages” are listed on Packagist, the official repository for Composer-compatible PHP libraries.

How to Install Composer

The safest way to download composer is by following the official instructions. This will verify the installer is not corrupt or tampered with. The installer installs a composer.phar binary in your current working directory.

We recommend installing Composer globally (e.g. a single copy in /usr/local/bin). To do so, run this command next:

mv composer.phar /usr/local/bin/composer

Note: If the above fails due to permissions, prefix with sudo.

To run a locally installed Composer you’d use php composer.phar, globally it’s simply composer.

Installing on Windows

For Windows users the easiest way to get up and running is to use the ComposerSetup installer, which performs a global install and sets up your $PATH so that you can just call composer from any directory in your command line.

How to Define and Install Dependencies

Composer keeps track of your project’s dependencies in a file called composer.json. You can manage it by hand if you like, or use Composer itself. The composer require command adds a project dependency and if you don’t have a composer.json file, one will be created. Here’s an example that adds Twig as a dependency of your project.

composer require twig/twig:^2.0

Alternatively, the composer init command will guide you through creating a full composer.json file for your project. Either way, once you’ve created your composer.json file you can tell Composer to download and install your dependencies into the vendor/ directory. This also applies to projects you’ve downloaded that already provide a composer.json file:

composer install

Next, add this line to your application’s primary PHP file; this will tell PHP to use Composer’s autoloader for your project dependencies.

<?php
require 'vendor/autoload.php';

Now you can use your project dependencies, and they’ll be autoloaded on demand.

Updating your dependencies

Composer creates a file called composer.lock which stores the exact version of each package it downloaded when you first ran composer install. If you share your project with others, ensure the composer.lock file is included, so that when they run composer install they’ll get the same versions as you. To update your dependencies, run composer update. Don’t use composer update when deploying, only composer install, otherwise you may end up with different package versions on production.

This is most useful when you define your version requirements flexibly. For instance, a version requirement of ~1.8 means “anything newer than 1.8.0, but less than 2.0.x-dev”. You can also use the * wildcard as in 1.8.*. Now Composer’s composer update command will upgrade all your dependencies to the newest version that fits the restrictions you define.

Update Notifications

To receive notifications about new version releases you can sign up for libraries.io, a web service that can monitor dependencies and send you alerts on updates.

Checking your dependencies for security issues

The Local PHP Security Checker is a command-line tool, which will examine your composer.lock file and tell you if you need to update any of your dependencies.

Handling global dependencies with Composer

Composer can also handle global dependencies and their binaries. Usage is straight-forward, all you need to do is prefix your command with global. If for example you wanted to install PHPUnit and have it available globally, you’d run the following command:

composer global require phpunit/phpunit

This will create a ~/.composer folder where your global dependencies reside. To have the installed packages’ binaries available everywhere, you’d then add the ~/.composer/vendor/bin folder to your $PATH variable.

• Learn about Composer

PEAR

A veteran package manager that some PHP developers enjoy is PEAR. It behaves similarly to Composer, but has some notable differences.

PEAR requires each package to have a specific structure, which means that the author of the package must prepare it for usage with PEAR. Using a project which was not prepared to work with PEAR is not possible.

PEAR installs packages globally, which means after installing them once they are available to all projects on that server. This can be good if many projects rely on the same package with the same version but might lead to problems if version conflicts between two projects arise.

How to install PEAR

You can install PEAR by downloading the .phar installer and executing it. The PEAR documentation has detailed install instructions for every operating system.

If you are using Linux, you can also have a look at your distribution package manager. Debian and Ubuntu, for example, have an apt php-pear package.

How to install a package

If the package is listed on the PEAR packages list, you can install it by specifying the official name:

pear install foo

If the package is hosted on another channel, you need to discover the channel first and also specify it when installing. See the Using channel docs for more information on this topic.

• Learn about PEAR

Handling PEAR dependencies with Composer

If you are already using Composer and you would like to install some PEAR code too, you can use Composer to handle your PEAR dependencies. PEAR repositories are no longer directly supported by Composer version 2, so you must manually add a repository to install PEAR packages:

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "pear2/pear2-http-request",
                "version": "2.5.1",
                "dist": {
                    "url": "https://github.com/pear2/HTTP_Request/archive/refs/heads/master.zip",
                    "type": "zip"
                }
            }
        }
    ],
    "require": {
        "pear2/pear2-http-request": "*"
    },
    "autoload": {
        "psr-4": {"PEAR2\\HTTP\\": "vendor/pear2/pear2-http-request/src/HTTP/"}
    }
}

The first section "repositories" will be used to let Composer know it should “initialize” (or “discover” in PEAR terminology) the pear repo. Then the require section will prefix the package name like this:

pear-channel/package

The “pear” prefix is hardcoded to avoid any conflicts, as a pear channel could be the same as another packages vendor name for example, then the channel short name (or full URL) can be used to reference which channel the package is in.

When this code is installed it will be available in your vendor directory and automatically available through the Composer autoloader:

vendor/pear2/pear2-http-request/pear2/HTTP/Request.php

To use this PEAR package simply reference it like so:

<?php
require __DIR__ . '/vendor/autoload.php';

use PEAR2\HTTP\Request;

$request = new Request();

• Learn more about using repositories with Composer