PHP Composer: Install Packages and Autoload Classes

Composer is the package manager for PHP. Run composer require vendor/package in your project folder: Composer downloads the library into vendor/, records it in composer.json, and you load it, along with everything else you installed, with one line, require __DIR__ . '/vendor/autoload.php';.

composer require monolog/monolog

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

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Level;

$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__ . '/app.log', Level::Warning));
$log->warning('Disk almost full', ['free' => '2%']);

No include for each file: the autoloader loads Logger, StreamHandler and everything they use the first time each class is needed. Packages come from Packagist, the public registry Composer searches by default.

Install Composer

Composer needs PHP on your machine first (see installing PHP).

Windows: download and run Composer-Setup.exe from getcomposer.org. It finds your php.exe and adds composer to the PATH. Open a new terminal afterwards.

macOS with Homebrew:

brew install composer

Linux: your distribution's package (sudo apt install composer on Debian and Ubuntu) works but is often an older release. The official installer gives the current one:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

The download page on getcomposer.org also shows a line that checks the installer's hash before running it; copy the commands from there to get the current hash. Then check that it works:

composer --version

composer.json and composer.lock

composer init asks a few questions and writes composer.json, or composer require creates it on the first package. A typical one:

{
    "name": "acme/shop",
    "require": {
        "php": ">=8.2",
        "monolog/monolog": "^3.0",
        "vlucas/phpdotenv": "^5.6"
    },
    "require-dev": {
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

• require lists what the project needs to run, including the PHP version.
• require-dev lists tools for development only (tests, static analysis). composer require --dev phpunit/phpunit adds to it, and composer install --no-dev skips it on production servers.
• autoload tells Composer where your own classes live (below).

Next to it, Composer writes composer.lock with the exact version of every package it installed, including the packages your packages depend on. Commit both files. Do not commit vendor/: add it to .gitignore, because composer install rebuilds it from the lock file.

composer install vs composer update

composer install          # install exactly what composer.lock says
composer update           # pick the newest allowed versions, rewrite composer.lock
composer update monolog/monolog   # update one package only
composer remove monolog/monolog   # uninstall and remove from composer.json
composer outdated         # list packages with newer versions available

Run composer install after cloning a project and on every deploy: everyone gets the same versions that were tested. Run composer update only when you intend to upgrade, then test and commit the new composer.lock. Running update on a production server installs versions nobody tested.

Version constraints: ^ and ~

composer require vendor/package without a version picks the newest stable release and writes a ^ constraint for it, which is usually what you want.

Autoload your own classes with PSR-4

PSR-4 is the convention that maps a namespace to a folder: with "App\\": "src/", the class App\Text\Slug lives in src/Text/Slug.php. After adding the autoload section, run:

composer dump-autoload

Composer's autoloader is a function registered with spl_autoload_register(), which PHP calls whenever code uses a class that is not loaded yet. This block writes two class files and registers a small PSR-4 autoloader of its own, so you can watch the mapping work. Add a third class file and use it.

<?php
// Two class files, laid out the PSR-4 way
is_dir('src/Text') || mkdir('src/Text', 0777, true);

file_put_contents('src/Greeter.php', <<<'PHP'
<?php
namespace App;

class Greeter
{
    public function hello(string $name): string
    {
        return "Hello, $name";
    }
}
PHP);

file_put_contents('src/Text/Slug.php', <<<'PHP'
<?php
namespace App\Text;

class Slug
{
    public static function from(string $title): string
    {
        return trim(preg_replace('/[^a-z0-9]+/', '-', strtolower($title)), '-');
    }
}
PHP);

// What vendor/autoload.php does for "App\\": "src/"
spl_autoload_register(function (string $class): void {
    $prefix = 'App\\';
    if (!str_starts_with($class, $prefix)) {
        return;
    }
    $file = __DIR__ . '/src/' . str_replace('\\', '/', substr($class, strlen($prefix))) . '.php';
    echo "autoload: $class => ", substr($file, strlen(__DIR__) + 1), "\n";
    if (is_file($file)) {
        require $file;
    }
});

echo (new App\Greeter())->hello('Ada'), "\n";
echo App\Text\Slug::from('Composer & PSR-4, Explained'), "\n";
echo App\Text\Slug::from('Loaded once, used twice'), "\n";

The autoloader runs once per class: the second Slug::from() call prints no autoload: line, because the class is already loaded. In a real project you never write this function yourself; vendor/autoload.php registers Composer's version, which also handles the packages in vendor/. Namespaces are covered on the namespaces page.

Common errors

• Class "Monolog\Logger" not found. The script did not require 'vendor/autoload.php', or the path is wrong. Use __DIR__ . '/vendor/autoload.php' so the path does not depend on the current directory.
• Your own class is not found after adding it to autoload. Run composer dump-autoload, and check that the file path matches the namespace exactly, including upper and lower case: App\Text\Slug must be src/Text/Slug.php, and Linux servers treat src/text/slug.php as a different file.
• Your requirements could not be resolved to an installable set of packages. Two packages need incompatible versions of something, often PHP itself. The message lists the conflict; composer why-not vendor/package 2.0 explains what blocks a version.
• composer is not recognized. The terminal was opened before installing, or the folder is not in your PATH. Open a new terminal, or call php composer.phar directly.