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.
allowed-tools: Read, Grep, Glob, Bash(php:*), Bash(composer:*), Bash(vendor/bin/*), Bash(bin/*), Bash(make:*), Bash(git:*)
---

# Composer Package Manager

<HARD-RULES>
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
</HARD-RULES>

## 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

```bash
# 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

```bash
composer remove package/name
composer remove --dev package/name
```

### Updating Dependencies

```bash
# 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

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

After modifying autoload rules:

```bash
composer dump-autoload
```

## Scripts Section

Use `composer.json` scripts for quality gate commands:

```json
{
    "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:

```bash
composer run test
composer run analyse
composer run cs-fix
```

## Platform Configuration

Pin the PHP version for consistent dependency resolution:

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

## Production Deployment

```bash
# 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

```bash
# 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
```