Composer is PHP’s dependency manager: you say which packages your project needs, it downloads them and their dependencies into a vendor folder, and it generates one file that loads every class on demand. Every modern PHP framework and library is distributed this way, so learning Composer is not optional; it is the first thing after the language itself. This is what it does, the handful of commands you will use, and the two files it maintains.
The problem it solves#
Before Composer, using a library meant downloading a zip, unpacking it somewhere, and adding require lines for its files — and doing that again for each library the library needed, and again on every machine, and again when a version changed. Composer does all of that from one file, reproducibly.
Installing Composer#
Download the installer from the official site and follow its instructions; on Windows there is an installer executable, on macOS brew install composer works, and on Linux the PHP-based installer or the distribution package. Confirm with:
composer --version
Starting a project#
mkdir myapp && cd myapp
composer init # answers a few questions and writes composer.json
composer require guzzlehttp/guzzle
That second command finds the package on Packagist, the public registry, works out which version fits, downloads it and everything it depends on into vendor/, records it in composer.json, and writes the exact versions to composer.lock.
<?php
require __DIR__ . '/vendor/autoload.php'; // the only require you write
$client = new GuzzleHttp\Client();
$response = $client->get('https://example.com');
echo $response->getStatusCode();
One line loads the autoloader; after that, using any class from any installed package just works.
The two files#
composer.json is what you ask for. It lists packages with version ranges:
{
"require": {
"php": "^8.2",
"guzzlehttp/guzzle": "^7.8",
"monolog/monolog": "^3.5"
},
"require-dev": {
"phpunit/phpunit": "^11.0"
},
"autoload": {
"psr-4": { "App\\": "src/" }
}
}
composer.lock is what you got: the exact version of every package, including the ones your packages pulled in. It is generated; you do not edit it. Its job is to make composer install produce the same vendor folder on every machine and every deploy.
Version constraints#
| Constraint | Means |
|---|---|
^7.8 |
7.8 or any later 7.x; not 8.0. The usual choice. |
~7.8.0 |
7.8.0 or any later 7.8.x; not 7.9. |
7.8.2 |
Exactly that version. |
>=7.8 <8.0 |
A range, spelled out. |
* |
Anything. Avoid. |
The caret form follows semantic versioning: a library promises no breaking changes within a major version, so ^7.8 is safe to update within and blocked from crossing to 8.
The five commands#
composer require vendor/package # add a package, update json and lock
composer require --dev vendor/package # add a development-only tool
composer install # install exactly what the lock file says
composer update # move everything to the newest allowed versions and rewrite the lock
composer update vendor/package # update just one
composer remove vendor/package # take a package out
The distinction between install and update is the one that matters. install reads the lock file and reproduces it; use it after cloning and in deployment. update ignores the lock, resolves fresh, and changes it; use it deliberately, then commit the new lock file and test.
Autoloading your own code#
The autoload section maps a namespace prefix to a folder. With "App\\": "src/", the class App\Services\Mailer is expected at src/Services/Mailer.php, and Composer loads it when first used. No require statements for your own classes either.
// src/Services/Mailer.php
namespace App\Services;
class Mailer { ... }
composer dump-autoload # regenerate after adding the autoload section or new folders
What goes in git#
- Commit
composer.jsonandcomposer.lock. - Ignore
vendor/. It is large, it is regenerated from the lock file, and committing it causes merge conflicts on every update.
A colleague clones the repository, runs composer install, and has the identical vendor folder. That is the whole point of the lock file.
Scripts and tools#
{
"scripts": {
"test": "phpunit",
"lint": "php-cs-fixer fix --dry-run"
}
}
composer test
composer lint
vendor/bin/phpunit # dev tools install their commands here
Common problems#
- “Your requirements could not be resolved.” Two packages need incompatible versions of a third, or your PHP version is below a package’s minimum. The message names the conflict; usually one package needs updating, or the PHP constraint in your json is wrong.
- Class not found after adding a file. Namespace or folder does not match the autoload mapping, or you need
composer dump-autoload. - Memory exhausted during update. Run with
COMPOSER_MEMORY_LIMIT=-1 composer update. - Slow installs. Update Composer itself with
composer self-update; version 2 is much faster than 1.
Questions people ask#
Is Composer the same as npm for PHP?
The same role: a dependency manager with a manifest, a lock file and a registry. The commands differ slightly, the ideas do not.
Do I need Composer for a tiny script?
Not if it has no dependencies. The moment it needs one library, Composer is easier than the alternative.
What is Packagist?
The public registry Composer searches by default. Private packages can come from a private registry or directly from a git repository.
Should I commit the lock file for a library I am publishing?
Libraries often do not, since the consuming application resolves versions. Applications always do.
Where to go next#
- PHP frameworks — all installed with Composer.
- Building a complete PHP project — Composer in a real layout.
- PHP deployment and hosting — composer install on the server.