agentleFS
peterfoxpeterfox/agent-skills/composer-upgrade/SKILL.md

composer-upgrade

Skill25 starsChanged 9 months agoMITView on GitHub

Guides PHP project upgrades using Composer commands. Use when helping users upgrade PHP packages, check for security vulnerabilities with `composer audit`, prioritize which packages to upgrade first, understand dependency conflicts, interpret `composer outdated` output, use `composer why-not` to diagnose version constraints, use `composer why` to trace dependencies, use `composer bump` to harden version constraints after upgrading, plan safe upgrade paths, resolve package version conflicts in composer.json, or resolve merge conflicts in composer.lock. Trigger this skill whenever the user mentions composer packages, PHP dependencies, outdated packages, CVEs in PHP projects, or security advisories.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow this sequence when upgrading a PHP project:

    line 10
  2. Very specific:

    When composer.lock has a merge conflict, use scripts/diff_lock.py to compare both sides and generate the commands needed to reconcile them.

    line 28
  3. Distinctive:

    Read the output to find which package constrains it, then check if that constraining package itself can be updated.

    line 94
  4. Very specific:

    Prefer updating direct dependencies one at a time with --dry-run first:

    line 106
  5. Very specific:

    If blocked, use composer why-not to identify the specific packages preventing the update, then include only those in the update command:

    line 113
  6. Very specific:

    Prefer composer require over hand-editing composer.json — it updates the constraint and resolves the lock in one step:

    line 123
  7. Very specific:

    Before: "symfony/console": "^6.0" → After: "symfony/console": "^6.4.3" (the ^ is preserved, so future minor/patch upgrades still work).

    line 148

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Composer Upgrade

Upgrade Workflow

Follow this sequence when upgrading a PHP project:

  1. Check for security issues → composer audit — fixes here are highest priority
  2. Identify what's outdated → composer outdated --format=json
  3. Prioritize — packages with CVEs AND outdated go first; see references/audit.md
  4. Diagnose blockers → composer why-not vendor/package version — note any sub-packages blocking the update
  5. Trace dependencies → composer why vendor/package
  6. Update packages → composer update vendor/package — if blocked, include identified blockers: composer update vendor/package blocker/one blocker/two
  7. Test
  8. Harden constraints → composer bump (applications only)
  9. Re-audit → composer audit to confirm all advisories are resolved

See references/commands.md for full flag reference, including global flags for non-interactive use (--no-interaction --no-progress --no-ansi). See references/upgrade-workflow.md for detailed strategies, including merge conflict resolution. See references/audit.md for security audit details, severity tiers, and how to build a prioritized package list.

Resolving composer.lock Merge Conflicts

When composer.lock has a merge conflict, use scripts/diff_lock.py to compare both sides and generate the commands needed to reconcile them.

During an active merge conflict:

# Compare HEAD vs MERGE_HEAD automatically and output composer commands
python3 scripts/diff_lock.py --conflict

# Human-readable summary of what changed
python3 scripts/diff_lock.py --conflict --format=summary

Compare any two branches or files:

python3 scripts/diff_lock.py main:composer.lock feature-branch:composer.lock
python3 scripts/diff_lock.py HEAD:composer.lock MERGE_HEAD:composer.lock
python3 scripts/diff_lock.py old.lock new.lock

The script outputs composer require / composer remove commands that move packages from the source state to the target state. Run the generated commands, then commit the result.

See references/upgrade-workflow.md — "Workflow: Merge Conflict in composer.lock" — for the full step-by-step process.

Core Commands

See references/commands.md for full flag reference and version constraint quick reference.

composer outdated

composer outdated --format=json           # preferred when parsing output (fewer tokens)
composer outdated --direct --format=json  # only direct deps

Red = major bump (breaking changes likely). Yellow = minor/patch (safe). ! = not semver-safe.

composer why-not

composer why-not vendor/package 2.0      # what prevents this upgrade
composer why-not php 8.2                 # what blocks a PHP version bump

Output shows the dependency chain: which packages require conflicting versions.

composer why

composer why vendor/package              # which installed packages depend on this one

composer update

composer update vendor/package --no-interaction --no-progress --no-ansi
composer update vendor/package --dry-run --no-interaction --no-ansi   # preview first

# If blocked, first identify which sub-dependencies are preventing the update:
composer why-not vendor/package 2.0
# Then include only those specific blockers in the update command:
composer update vendor/package blocker/one blocker/two --no-interaction --no-progress --no-ansi

Common Patterns

"Why can't I update X?"

composer why-not vendor/package 3.0

Read the output to find which package constrains it, then check if that constraining package itself can be updated.

"What's blocking my PHP version upgrade?"

composer why-not php 8.2

Lists every package that lacks a php: ^8.2 constraint, sorted by most blocking.

"Safe incremental upgrade"

Prefer updating direct dependencies one at a time with --dry-run first:

composer update vendor/package --dry-run --no-interaction --no-ansi
composer update vendor/package --no-interaction --no-progress --no-ansi

If blocked, use composer why-not to identify the specific packages preventing the update, then include only those in the update command:

composer why-not vendor/package 2.0
# → reveals blocker/one and blocker/two are preventing the update
composer update vendor/package blocker/one blocker/two --no-interaction --no-progress --no-ansi

Bumping a major version constraint

Prefer composer require over hand-editing composer.json — it updates the constraint and resolves the lock in one step:

composer require vendor/package:"^3.0" --dry-run --no-interaction --no-ansi
composer require vendor/package:"^3.0" --no-interaction --no-progress --no-ansi

For risky upgrades (auth, permissions, database layers), use a dual constraint to test before committing:

# Allow both old and new major versions while testing
composer require vendor/package:"^2.5.0|^3.0" --no-interaction --no-progress --no-ansi
# If tests pass, lock in the new version:
composer require vendor/package:"^3.0" --no-interaction --no-progress --no-ansi

See references/upgrade-workflow.md — "Techniques for Major Version Upgrades" — for more detail.

Hardening constraints after upgrading (applications)

composer bump                  # raise lower bounds in composer.json to installed versions
composer bump --dev-only       # only require-dev (safe for libraries too)

Before: "symfony/console": "^6.0" → After: "symfony/console": "^6.4.3" (the ^ is preserved, so future minor/patch upgrades still work).

See references/commands.md for auto-bump config and full flag reference.

Applications only: Do not run composer bump (without --dev-only) on libraries — it narrows constraints in ways that break downstream consumers.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.