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

• Run composer audit to check for security vulnerabilities

• Run composer outdated --direct to see what needs updating

• Create a dedicated branch for the update

• Update one package or logical group at a time

• Run full test suite after each update

• Run static analysis (PHPStan/Psalm)

• Run composer audit again post-update

• Commit both composer.json and composer.lock

• Optionally run composer bump to raise lower bounds (apps only)

• Deploy via composer install --no-dev --optimize-autoloader

• Monitor application behavior after deployment

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