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.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- gritqlSkill
- laravel-advanced-conceptsSkill
- npm-upgradeSkill
- packagistSkill
- phpstan-developerSkill
- php-type-safetySkill
- rector-developerSkill
- remotion-3d-background-developerSkill
- serpapiSkill
- slidewire-developerSkill
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
- Distinctive: line 10
Follow this sequence when upgrading a PHP project:
- Very specific: line 28
When composer.lock has a merge conflict, use scripts/diff_lock.py to compare both sides and generate the commands needed to reconcile them.
- Distinctive: line 94
Read the output to find which package constrains it, then check if that constraining package itself can be updated.
- Very specific: line 106
Prefer updating direct dependencies one at a time with --dry-run first:
- Very specific: line 113
If blocked, use composer why-not to identify the specific packages preventing the update, then include only those in the update command:
- Very specific: line 123
Prefer composer require over hand-editing composer.json — it updates the constraint and resolves the lock in one step:
- Very specific: line 148
Before: "symfony/console": "^6.0" → After: "symfony/console": "^6.4.3" (the ^ is preserved, so future minor/patch upgrades still work).
≈ “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.
Files
Composer Upgrade
Upgrade Workflow
Follow this sequence when upgrading a PHP project:
- Check for security issues →
composer audit— fixes here are highest priority - Identify what's outdated →
composer outdated --format=json - Prioritize — packages with CVEs AND outdated go first; see references/audit.md
- Diagnose blockers →
composer why-not vendor/package version— note any sub-packages blocking the update - Trace dependencies →
composer why vendor/package - Update packages →
composer update vendor/package— if blocked, include identified blockers:composer update vendor/package blocker/one blocker/two - Test
- Harden constraints →
composer bump(applications only) - Re-audit →
composer auditto 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=summaryCompare 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.lockThe 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 depsRed = 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 bumpOutput shows the dependency chain: which packages require conflicting versions.
composer why
composer why vendor/package # which installed packages depend on this onecomposer 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-ansiCommon Patterns
"Why can't I update X?"
composer why-not vendor/package 3.0Read 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.2Lists 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-ansiIf 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-ansiBumping 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-ansiFor 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-ansiSee 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.
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
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.

