PHP and Composer upgrades

Composer & PHP Upgrades

When to Use

Use when upgrading PHP libraries, frameworks (Laravel, Symfony, Doctrine, Filament, Livewire, Pest/PHPUnit, PHPStan/Psalm), or PHP runtime targets via composer.json and composer.lock.

Platform & Constraint Discovery

1. Inspect PHP Runtime vs. config.platform

• Check both require.php (e.g., "^8.2", "~8.3.0") and config.platform.php in composer.json, alongside Dockerfile / docker-compose.yml / CI matrix PHP versions and required PHP extensions (ext-intl, ext-gd, ext-redis, ext-imagick, ext-pcntl, ext-bcmath, ext-sodium).
• Warning: config.platform.php tells Composer to emulate a specific PHP version when resolving composer.lock even if the local CLI runs a newer PHP version. Always keep config.platform aligned with the lowest production PHP runtime, and never use --ignore-platform-reqs (--ignore-platform-req=php) to force an incompatible package into composer.lock.

2. Trace Dependency Blockers Before Updating

Use Composer's built-in solver diagnostics before changing constraints:

• composer why <vendor/package> (depends): Shows which direct or transitive packages require the installed package.
• composer why-not <vendor/package> <target-version> (prohibits): Shows the exact version constraint chain (PHP version, sibling package, or root composer.json) blocking the upgrade.
• composer outdated --direct: Lists outdated direct dependencies and indicates semver-safe vs. major updates.

Controlled Update Execution

1. Scoped composer update Commands

• Never run a bare composer update across the whole project when upgrading a specific library—that recalculates and bumps every unlocked package in composer.lock.
• Always scope updates to the target package and its coupled dependents:
  • composer update vendor/package --with-all-dependencies (-W)
  • For coupled framework families (e.g., symfony/*, illuminate/*, spatie/*), pass all related packages together: composer update "symfony/*" --with-all-dependencies.
• Validate manifest integrity with composer validate --strict.

2. Framework & Ecosystem Upgrade Nuances

• Laravel (laravel/framework):
  • Upgrade coupled first-party packages in lockstep (laravel/sanctum, laravel/horizon, laravel/passport, laravel/cashier, laravel/octane, laravel/pint, nunomaduro/collision, pestphp/pest / phpunit/phpunit).
  • Check composer.json scripts (@php artisan package:discover --ansi, @php artisan vendor:publish), middleware registration (bootstrap/app.php in Laravel 11+ vs app/Http/Kernel.php), Eloquent cast/model signature changes, and published config files (config/*.php).
• Symfony (symfony/*):
  • Check extra.symfony.require in composer.json (which restricts Symfony Flex recipes and symfony/* component versions!). Updating require without updating extra.symfony.require causes solver failures.
  • Check Symfony Flex recipe diffs (composer recipes, composer recipes:update) for updated bundle configs (config/packages/*.yaml) and DI container deprecations (bin/console debug:container --deprecations).
• Static Analysis & Tests (phpstan/phpstan, larastan/larastan, vimeo/psalm, phpunit/phpunit, pestphp/pest):
  • PHPUnit major upgrades (e.g., PHPUnit 9 $\rightarrow$ 10 $\rightarrow$ 11) replace docblock annotations (@test, @dataProvider) with PHP 8 attributes (#[Test], #[DataProvider]), tighten phpunit.xml schemas (phpunit --migrate-configuration), and make data provider methods static.
  • When upgrading PHPStan/Larastan, fix newly surfaced type errors in application code rather than bloating phpstan-baseline.neon.

3. Composer Plugins, Patches & Autoloading

• Check config.allow-plugins when a new plugin package is introduced.
• If cweagans/composer-patches is used, verify whether each .patch file still applies cleanly or was merged upstream.
• Always run composer dump-autoload --strict-psr (or --optimize) and verify zero PSR-4 autoloading warnings.