Composer Dependency Management

When to use

• The user wants to add, remove, or upgrade a third-party PHP package in a project managed by Composer.
• The user needs to pick or tighten a version constraint (caret, tilde, or exact) for a dependency.
• The user needs a reproducible, locked dependency set for CI or production deployment.

When NOT to use

• Do not use Composer to load optional feature modules or plugins that must be enabled or disabled at runtime.
• Do not use this skill to patch or hand-edit files under vendor/; that directory is regenerated on every install.

Core guidance

• Prefer caret constraints for semver libraries — Use a caret constraint (^2.3) for libraries that follow semantic versioning so Composer accepts compatible minor and patch releases but never a breaking major.
• Commit the lock file for applications — Commit composer.lock for applications so every developer and every environment installs identical versions; do not commit it for a reusable library you publish.
• Use install to reproduce, update to change versions — Run composer install to reproduce the exact versions in composer.lock, and run composer update only when you intend to resolve new versions and rewrite the lock.
• Split runtime and development dependencies — Put packages the application needs at runtime under require, and tools only used while developing or testing (PHPUnit, PHPStan, fixtures) under require-dev.

Quick recipe

1. Run composer require vendor/package:^2.3 to add the package and record a caret constraint in composer.json. (verify: composer.json lists vendor/package under require with a caret constraint)
2. Commit both composer.json and the regenerated composer.lock so the exact resolved versions are shared with the team. (verify: git status shows both composer.json and composer.lock staged together)
3. In CI and on deploy, run composer install --no-dev so the exact locked versions are restored without dev tooling. (verify: The CI install resolves the same versions as the committed lock and exits 0)

Best practices

• Run composer audit in CI to fail the build when a required package has a known security advisory, and keep constraints loose enough to absorb patch releases
• Declare the PHP version and required extensions in require (for example "php": ">=8.1" and "ext-json": "*") instead of relying on the developer's local environment

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Editing composer.json without updating the lock — Hand-editing a constraint in composer.json without running an update leaves the lock file out of sync. Fix: After changing a constraint, run composer update vendor/package to re-resolve just that package and refresh the lock.
2. Running composer update during deployment — Running composer update on the deploy host re-resolves versions and can ship untested code to production. Fix: Deploy with composer install --no-dev against the committed lock, and run update only in a reviewed pull request.
3. Using a wildcard or unbounded constraint — A wildcard constraint like "*" or ">=1.0" lets Composer pull a breaking major version without warning. Fix: Pin the major with a caret (^1.0) so patch and minor releases flow in but breaking majors are blocked.

Version notes

• Composer 2 tightens platform checks (PHP >=7.4) — Composer 2 enforces platform requirements more strictly and resolves dependencies faster than Composer 1; some Composer 1 plugins are incompatible.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/composer/dependency-management.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: composer/autoload-psr4, composer/scripts