How to Use Composer: The PHP Dependency Manager

Composer has become the de‑facto standard for handling PHP dependencies. Whether you’re building a tiny script or a massive Laravel application, Composer ensures that you can declare, install, and update the libraries your project needs with a single, reproducible command.

1. Installing Composer

Composer can be installed globally or per‑project. The most common method for Linux/macOS is the official installer script:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'INSERT_HASH_HERE') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"

On Windows, download Composer‑Setup.exe and follow the wizard. After installation, verify the version:

composer --version

2. Initialising a Project

Navigate to your project folder and run:

composer init

This interactive wizard creates a composer.json file where you declare your project’s metadata and dependencies. Example of a minimal composer.json:

{
    "name": "vendor/project",
    "description": "A short description of the project.",
    "require": {}
}

Key Sections of composer.json

• name: vendor/package format required for Packagist.
• description: SEO‑friendly text used by search engines.
• require: List of packages and version constraints.
• autoload: PSR‑4 mapping for automatic class loading.
• scripts: Hook commands (e.g., post-install-cmd).

3. Adding Packages with require

To add a library, use the require command. Composer resolves the latest compatible version based on your constraint:

composer require monolog/monolog:^2.9

Resulting composer.json snippet:

"require": {
    "monolog/monolog": "^2.9"
}

Composer creates a vendor/ directory, downloads the package, and updates composer.lock, which locks the exact versions for reproducible builds.

Version Constraints Cheat Sheet

Constraint	Meaning
^1.2	≥ 1.2.0 < 2.0.0 (default for libraries)
~1.2.3	≥ 1.2.3 < 1.3.0
1.2.*	Any patch version in 1.2
dev-master	Latest commit on master branch (use with caution)

4. Updating Dependencies

When new versions are released, update with:

composer update

To update a single package:

composer update monolog/monolog

Always commit the updated composer.lock to version control; this guarantees that teammates and CI pipelines install the exact same versions.

5. Autoloading Classes

Composer’s autoloader follows the PSR‑4 standard. Define a namespace mapping in composer.json:

"autoload": {
    "psr-4": {
        "App\\": "src/"
    }
}

After editing, regenerate the autoloader:

composer dump-autoload -o

Then include the generated file in your entry script:

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

6. Composer Scripts

Composer can run custom commands at specific lifecycle events. Example:

"scripts": {
    "post-install-cmd": [
        "php artisan migrate --force"
    ],
    "test": "phpunit"
}

Run a script with:

composer test

7. Advanced Tips & Best Practices

7.1 Use composer.lock in Production

Never run composer install without the lock file in production. It ensures deterministic builds and prevents accidental upgrades that could break your site.

7.2 Optimize Autoloader for Production

Deploy with the optimized autoloader to improve performance:

composer install --optimize-autoloader --no-dev

7.3 Separate Development Dependencies

Packages needed only for testing, debugging, or code generation belong in require-dev:

composer require --dev phpunit/phpunit:^10

7.4 Use Private Repositories

If you host proprietary packages, add them to repositories:

"repositories": [
    {
        "type": "vcs",
        "url": "git@github.com:your-company/private-lib.git"
    }
]

7.5 Leverage config.platform for PHP Version Consistency

Force Composer to resolve dependencies as if a specific PHP version is installed:

"config": {
    "platform": {
        "php": "8.2.0"
    }
}

8. Common Issues & Troubleshooting

8.1 “Could not find a matching version”

Check your version constraints and ensure the package exists on Packagist. Use composer why-not vendor/package version to diagnose.

8.2 “Class not found” after installing a package

Make sure you included vendor/autoload.php and that the package’s autoload section follows PSR‑4 or PSR‑0.

8.3 Memory Exhaustion

Large dependency trees may exceed PHP’s memory limit. Increase it temporarily:

COMPOSER_MEMORY_LIMIT=-1 composer update

8.4 SSL/TLS Errors

Outdated CA certificates cause download failures. Update your system’s CA bundle or use the --disable-tls flag as a last resort.

Conclusion

Composer streamlines PHP development by handling dependency resolution, version constraints, and autoloading—all from a single composer.json file. By mastering the commands, configuration options, and best practices outlined above, you’ll be able to build reliable, maintainable PHP applications that scale from local prototypes to production‑grade services.

Ready to dive deeper? Explore the official Composer documentation, contribute to open‑source packages on Packagist, and keep your composer.lock under version control for rock‑solid deployments.