Composer Dependencies Update

Dependency updates are maintenance, not features. Do them regularly in small batches rather than rarely in large ones. Every update follows the same cycle: audit, update, verify, commit.

Core Principles

Principle	Meaning
Changelog first	Before any major dependency update, search the web for the package's changelog/UPGRADE file or ask the user to provide it -- never guess what changed
Security first	Run `composer audit` before and after every update -- vulnerabilities take priority over everything
Small batches	Update one package or one logical group at a time -- never update everything at once
Lock file is truth	Always commit `composer.lock` -- production uses `composer install`, never `composer update`
Verify before merging	Every update must pass the full test suite and static analysis before merging
Caret by default	Use `^` constraints for most dependencies -- it balances stability with receiving fixes

Critical First Step: Read the Changelog

Before updating any dependency to a new major version, you MUST obtain the actual changelog:

Search the web for {package-name} CHANGELOG or {package-name} UPGRADE guide (e.g., doctrine/orm UPGRADE.md github)
Or ask the user to provide the changelog / release notes
Check the package's GitHub repository for CHANGELOG.md, UPGRADE.md, or release notes

This is non-negotiable for major updates. Each package has unique breaking changes that static skill knowledge cannot capture. For patch and minor updates, changelogs are recommended but not blocking.

Update Strategies by Risk Level

Strategy	Scope	Risk	Frequency	Command
Patch only	Bug fixes (1.2.3 -> 1.2.4)	Lowest	Weekly	`composer update --patch-only`
Minor	New features, backward-compatible (1.2 -> 1.3)	Low	Biweekly	`composer update --minor-only`
Major	Breaking changes possible (1.x -> 2.0)	Highest	Planned, one at a time	`composer update vendor/package --with-all-dependencies`
Security	Vulnerability fixes	Urgent	Immediately	`composer audit` then targeted update

Essential Commands

Command	Purpose
`composer outdated --direct`	Show outdated direct dependencies (skip transitive)
`composer outdated --major-only`	Show only packages with major updates available
`composer outdated --minor-only`	Show only packages with minor updates available
`composer audit`	Check locked versions against known security advisories
`composer why vendor/package`	Show which packages depend on a given dependency
`composer why-not vendor/package 2.0`	Show what prevents upgrading to a specific version
`composer update vendor/package --with-all-dependencies`	Update a package and all its dependents
`composer bump`	Raise lower bounds in `composer.json` to currently installed versions (apps only)
`composer validate --strict`	Validate `composer.json` structure and constraints

Security Auditing

composer audit

Built into Composer since 2.4. Compares locked versions against GitHub Security Advisories and FriendsOfPHP databases.

# Check for known vulnerabilities
composer audit

# JSON output for CI parsing
composer audit --format=json

Returns non-zero exit code when vulnerabilities are found -- use as a CI gate.

Since Composer 2.9 (November 2025), composer update and composer require automatically block installation of packages with known security advisories by default.

roave/security-advisories

Preventive complement to composer audit. Declares conflict rules against all known vulnerable versions, preventing them from being installed.

composer require --dev roave/security-advisories:dev-latest

Must always be pinned to dev-latest (never a tagged version).

Quick check: composer update --dry-run roave/security-advisories

See Update Workflow Reference for the complete step-by-step update process.

Version Constraints

Operator	Example	Range	Use Case
`^` (caret)	`^1.2.3`	`>=1.2.3 <2.0.0`	Default for most dependencies
`~` (tilde)	`~1.2.3`	`>=1.2.3 <1.3.0`	Conservative -- patch updates only
`~` (minor)	`~1.2`	`>=1.2.0 <2.0.0`	Same as `^1.2` in practice
Exact	`1.2.3`	Only `1.2.3`	Avoid except for known regressions
`*` (wildcard)	`1.2.*`	`>=1.2.0 <1.3.0`	Avoid in production

Pre-1.0 packages: The caret respects semver for unstable packages: ^0.3 means >=0.3.0 <0.4.0, and ^0.0.3 means >=0.0.3 <0.0.4.

Lock File Management

Rule	Reason
Always commit `composer.lock` for applications	Ensures identical versions across all environments
Use `composer install` in CI and production	Reads from lock file, guarantees reproducible builds
Use `composer update` only intentionally	Resolves constraints anew, writes new lock file
Never edit `composer.lock` manually	Let Composer manage it
Use `--no-dev` in production	Exclude development dependencies
Use `--optimize-autoloader` in production	Generate optimized class map

Production install command:

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

Abandoned Packages

Composer warns about abandoned packages during install/update. Handle them proactively:

Check the warning -- some suggest a replacement package directly
Search Packagist for maintained alternatives
Use composer why vendor/package to understand who depends on it
Wrap risky dependencies behind interfaces (adapter pattern) to make future replacement easier
Use composer-unused to find packages in composer.json that are not actually used in code

Quick Reference: Update Checklist

Reference Files

Reference	Contents
Update Workflow	Step-by-step update process, CI integration with Dependabot/Renovate, major update handling, and troubleshooting
Dependency Strategies	Versioning strategies, constraint selection, automated update tools configuration, and abandoned package handling

Integration with Other Skills

Situation	Recommended Skill
Upgrading PHP version (may require dependency updates)	Use the `php-upgrade` playbook skill
Upgrading Symfony framework	Use the `symfony-upgrade` skill in `frameworks/symfony/`
Detecting N+1 query issues after ORM updates	Use the `detect-n-plus-one` skill

composer-dependencies