Composer

repository·main·Indexed 12 days ago

https://github.com/composer/composer

The standard dependency management tool for PHP. It allows developers to declare, manage, and install project dependencies by resolving version constraints and downloading packages from repositories like Packagist. Supports PHP 7.2.5+ for the latest version and PHP 5.3.2 through 8.1 for Composer 2.2 LTS.

Tokens
78.5K
Snippets
281
Records
375
Agent score
97%

What's inside Composer

  1. Implement Plugin Capabilities (e.g., CommandProvider)

    main

    Composer uses a Capability system to provide explicit extension points, reducing the need to manipulate internal state. To use capabilities, your plugin must implement Composer\Plugin\Capable and define them in the getCapabilities() method.

    One common capability is Composer\Plugin\Capability\CommandProvider, which allows you to register new CLI commands. This requires a separate class that implements CommandProvider and returns an array of command instances (based on the Symfony Console component).

    <?php
    
    namespace My\Composer;
    
    use Composer\Plugin\Capable;
    use Composer\Plugin\PluginInterface;
    use Composer\Plugin\Capability\CommandProvider as CommandProviderCapability;
    
    class Plugin implements PluginInterface, Capable
    {
        public function activate(\Composer\Composer $composer, \Composer\IO\IOInterface $io)
        {
        }
    
        public function getCapabilities()
        {
            return [
                'Composer\Plugin\Capability\CommandProvider' => 'My\Composer\CommandProvider',
            ];
        }
    }
  2. Configure global settings via COMPOSER_HOME/config.json

    main

    The COMPOSER_HOME directory is a global, per-user directory shared between all projects. You can place a config.json file in this directory to set global repositories and config settings.

    When running install or update, Composer will partially merge this file with your project's composer.json.

    Precedence Rule: If a configuration key exists in both the global config.json and the local composer.json, the local configuration always wins.

  3. Understand package names and version constraints

    main

    Package Names

    Package names follow a vendor/project format (e.g., monolog/monolog). The vendor name prevents naming clashes between different authors.

    Version Constraints

    Version constraints define which versions of a package are acceptable. For example, 2.0.* matches any version in the 2.0 development branch (equivalent to >=2.0 <2.1).

    Package Resolution

    1. Composer searches registered repositories (defined via the repositories key).
    2. If no custom repositories are found, it falls back to Packagist.org, the default central repository.
    3. Composer uses VCS features (branches and tags) to find the best match for your constraint.
  4. Use the `composer` platform package for version constraints

    main

    Introduced in Composer 2.2.0, the composer platform package represents the exact version of the Composer executable being used.

    Best Practices:

    • Use composer-plugin-api or composer-runtime-api whenever possible, as they are the recommended way to depend on Composer capabilities.
    • Use the composer package only to cover edge cases where specific Composer versions are required that aren't covered by the API packages.
    • Recommendation: If you depend on the composer package, it is recommended to also add a dependency on composer-plugin-api: >=2.2.0 to ensure users on older Composer versions receive meaningful error messages.
  5. Handle the composer.lock file in libraries

    main

    When developing a library, you may choose to commit the composer.lock file. This ensures that your own development team always tests against the same dependency versions.

    Important: The composer.lock file in a library has no effect on other projects that depend on it; it only affects the library's own local installation. If you do not want to commit it, add it to your .gitignore.

  6. Manage package stability and minimum-stability

    main

    Composer recognizes several stability levels in order from least to most stable: dev, alpha, beta, RC (Release Candidate), and stable.

    To control which versions are installed, you can use two methods:

    1. Project-wide minimum-stability: Set a global stability requirement in your composer.json.
    2. Stability flags: Apply a specific stability requirement to a single package using the @<stability> syntax (e.g., @dev).

    If a version suffix is missing (e.g., 1.1), Composer treats it as stable. If a branch is imported from a VCS, Composer automatically assigns it dev stability.

  7. Handle dependencies on the root package

    main

    Issues occur when the root package depends on a package that eventually depends back on the root package.

    Development (Branch Aliases)

    If you are working on a branch (e.g., dev-main) that lacks a branch-alias, dependencies requiring a version like ^2.0 will not be satisfied. Define a branch-alias to resolve this.

    CI/CD (Root Version Detection)

    In CI environments using shallow clones, Composer may fail to detect the root package version. You can explicitly define the version using the COMPOSER_ROOT_VERSION environment variable.

    Example:

    COMPOSER_ROOT_VERSION=dev-main composer install
  8. Supported autoloading standards

    main

    Composer supports several autoloading mechanisms:

    • PSR-4: The modern standard for mapping namespaces to directories.
    • PSR-0: An older autoloading standard.
    • classmap: A faster lookup method that maps specific class names to file paths.
    • files: Allows loading specific files on every request.

    If you prefer not to use Composer's built-in autoloader, you can include the individual files located in vendor/composer/autoload_*.php, which return associative arrays that you can use to configure your own custom autoloader.

  9. Root-only configuration fields

    main

    Certain fields in composer.json are designated as root-only. This means they are only processed when they appear in the composer.json of the root package. If these fields appear in the composer.json of a dependency, they are ignored.

    An example of a root-only field is config.

  10. Understand and configure Platform Check

    main

    Composer automatically includes a vendor/composer/platform_check.php file in the autoloader. This script verifies that the current PHP process meets the platform requirements (PHP version and extensions) defined in composer.json.

    If requirements are not met, the script prints a warning and exits with code 104.

    Configuration Options

    • platform-check: false: Disables the safety check entirely.
    • platform-check: true: Verifies the presence of PHP extensions (but not their exact versions). The default behavior is php-only (verifying only the PHP version).

    Best Practices

    To avoid runtime failures in production, run composer check-platform-reqs as part of your deployment or build pipeline. If it returns a non-zero exit code, abort the deployment.