composer

name	composer
description	Manages PHP dependencies and environments with Composer: adds packages, syncs lockfiles, configures autoload. Activates when setting up projects, managing dependencies, or working with autoload.

Composer Package Manager

These rules are NON-NEGOTIABLE. Violating any of them is a bug.

• NEVER edit composer.lock manually — it is auto-generated by Composer
• ALWAYS use composer require <package> to add production dependencies
• ALWAYS use composer require --dev <package> to add development dependencies
• NEVER delete composer.lock — always commit it to version control
• ALWAYS run composer install (not composer update) in CI/CD and production
• NEVER run composer update without specifying a package name — use composer update <package> for targeted updates
• ALWAYS commit both composer.json and composer.lock after dependency changes
• NEVER add vendor/ to version control

When to Activate

• Adding, removing, or updating project dependencies
• Configuring autoload rules
• Setting up composer.json scripts for quality gates
• Resolving dependency conflicts

Dependency Management

Adding Dependencies

# Production dependency
composer require symfony/messenger

# Development dependency
composer require --dev phpstan/phpstan

# Specific version constraint
composer require doctrine/orm:^2.15

# Multiple packages at once
composer require symfony/uid symfony/messenger

Removing Dependencies

composer remove package/name
composer remove --dev package/name

Updating Dependencies

# Update a specific package (preferred)
composer update symfony/messenger

# Update with dry-run to preview changes
composer update symfony/messenger --dry-run

# Update all packages in a namespace
composer update symfony/*

Version Constraints

Constraint	Meaning	Example
^2.15	>=2.15.0, <3.0.0 (recommended)	Most packages
~2.15	>=2.15.0, <2.16.0	Patch-level pinning
>=2.15	Any version >=2.15.0	Broad compatibility
2.15.*	>=2.15.0, <2.16.0	Same as ~2.15
2.15.3	Exact version (avoid)	Only for critical pins

Prefer ^ (caret) constraints for most dependencies.

Autoload Configuration

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "App\\Tests\\": "tests/"
        }
    }
}

After modifying autoload rules:

composer dump-autoload

Scripts Section

Use composer.json scripts for quality gate commands:

{
    "scripts": {
        "test": [
            "Composer\\Config::disableProcessTimeout",
            "vendor/bin/phpunit"
        ],
        "analyse": [
            "vendor/bin/php-cs-fixer fix --diff --verbose --dry-run",
            "vendor/bin/phpstan analyse src"
        ],
        "cs-fix": "vendor/bin/php-cs-fixer fix --diff --verbose",
        "phpstan": "vendor/bin/phpstan analyse src",
        "architecture": "vendor/bin/deptrac --config-file=deptrac/deptrac.yaml"
    }
}

Run scripts via:

composer run test
composer run analyse
composer run cs-fix

Platform Configuration

Pin the PHP version for consistent dependency resolution:

{
    "config": {
        "platform": {
            "php": "8.3.0"
        }
    }
}

Production Deployment

# Install without dev dependencies, optimize autoloader
composer install --no-dev --optimize-autoloader --classmap-authoritative

# Clear cache if needed
composer clear-cache

Common Mistakes to Avoid

# BAD: Update all dependencies at once
composer update

# GOOD: Update specific package
composer update symfony/messenger

# BAD: Delete lock file to resolve conflicts
rm composer.lock && composer install

# GOOD: Update the conflicting package
composer update conflicting/package --with-dependencies

# BAD: Use require without constraint
composer require some/package

# GOOD: Composer defaults to ^latest — this is fine, but review the constraint
composer require some/package:^2.0