Skip to content
Happy Programming Guide
Start learning
PHP

Composer for Beginners: What It Is and How to Use It

Composer installs PHP packages and loads their classes automatically. What it does, the five commands you need, what composer.json and the lock file are for, and the mistakes that break projects.

Keys of a mechanical keyboard seen up close

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:

Terminal
composer --version

Starting a project#

Terminal
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
<?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:

JSON
{
  "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#

Terminal
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.

PHP
// src/Services/Mailer.php
namespace App\Services;

class Mailer { ... }
Terminal
composer dump-autoload      # regenerate after adding the autoload section or new folders

What goes in git#

  • Commit composer.json and composer.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#

JSON
{
  "scripts": {
    "test": "phpunit",
    "lint": "php-cs-fixer fix --dry-run"
  }
}
Terminal
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#

Building a complete PHP project with Composer and autoloadingRead next

Keep reading

PHP

Building a Complete PHP Project

Take PHP from loose files in a web root to a real project: Composer, autoloading, a front controller, routing, PDO, templates and…

5 min read

PHP

PHP Performance Optimization

Where PHP applications actually spend their time, how to measure before you optimise, and the fixes that matter: OPcache, N+1 queries, indexes…

5 min read

Keep going — pick your next guide

The fastest way to improve is to read one guide, then build the thing it describes. Start with the basics, or jump straight to a project.

Ask a question or share what worked

Your email address will not be published. Required fields are marked *