Laravel 13 Course – Lesson 36: Controlled Laravel Upgrades and Dependency Management

Lesson 36 — Dependencies and Laravel upgrades: An upgrade changes a constraint graph and application behavior, not merely a version string. TaskFlow needs reproducible installs, an understood dependency diff and regression evidence before release.

1. Record a baseline

This checkpoint uses Laravel13.32.0, PHP8.4.25, Pest4.7.8 and PHPUnit12.5.33. The locked graph, including development tools, may require a different runtime from Laravel's own minimum. Check the actual packages and do not assume local CLI, production FPM and CI share the same runtime.

Work on an isolated branch/release and record the reason, runtimes, lockfile hashes and current worktree. Preserve unrelated uncommitted changes. The following checks do not require changing the lockfile:

composer validate --strict
composer check-platform-reqs
composer show --locked laravel/framework
composer audit --locked
npm audit --audit-level=high
composer update laravel/framework --with-dependencies --dry-run

# Inspect a concrete dependency constraint:
composer why guzzlehttp/guzzle
composer why-not guzzlehttp/guzzle 8.2.0

2. Interpret actual output

Composer reported no advisories and npm reported zero vulnerabilities. The scoped framework dry-run proposed no lockfile changes, so this lesson applies no package upgrade. Results depend on time, repositories and constraints; they do not prove every dependency is latest or free of undisclosed defects.

why explains dependency relationships. why-not inspects blockers for a concrete target; the current Guzzle8.2.0 diagnostic identifies promises/psr7 locked on different branches. A blocker diagnostic's nonzero exit is not an instruction to force installation. Inspect a full dry-run resolution before deciding.

3. Installs, updates and lockfiles

Releases use composer install from a reviewed lock rather than resolving arbitrary updates on the server. Intentional updates should be scoped and their manifest/lock diffs reviewed. npm ci consumes the frontend lockfile. Keep both lockfiles; deleting them to hide conflicts sacrifices reproducibility.

The -w and -W options differ in how far dependencies may move; -W permits changes to additional root requirements. Review installs, removals, downgrades, transitive changes and plugin/script execution instead of reflexively widening every update. Do not bypass runtime requirements with --ignore-platform-reqs.

4. Lessons from this project's history

Adding Reverb required adjusting the locked HTTP dependency graph. Adding Pest4 changed PHPUnit from12.5.35 to12.5.33 to satisfy constraints. Those deliberate changes were preceded by dry-runs and followed by regression runs: adding one package need not affect only one line.

Do not jump a Pest major merely because default documentation describes it. Check the matching documentation branch, PHP, PHPUnit and Laravel plugin together. For framework-major upgrades, read the target upgrade guide and inspect middleware, auth, serialization, queued payloads, migrations and extension packages. Never overwrite customized bootstrap/config files with a new skeleton blindly.

5. Post-change gates

vendor/bin/pint --test
php artisan test
npm run build
node tests/reverb-smoke.mjs
php artisan test --filter=HealthCheckTest
php artisan test --filter=BackupRestoreDrillTest

The existing102-test/465-assertion result is a baseline, not evidence that an unapplied upgrade passed. Recheck staging journeys: login/logout, owner access, token abilities/revocation, private files, queues, schedules and realtime. Different database engines, operating systems, browsers, mail providers and Redis need their own verification.

A clean audit does not replace tests, and passing tests do not replace advisory review. Investigate affected versions, reachable behavior and patches before remediation; avoid blindly accepting major changes from npm audit fix --force. Temporary exceptions need an owner, rationale and deadline.

6. Release and rollback

Build from the reviewed commit/lock, run hosted CI when available and retain its URL with staging evidence. Keep a previous artifact compatible with the current schema. Restoring an older lockfile does not reverse migrations, delivered mail or executed jobs. Plan expand/contract schema changes and compatibility with queued payloads.

The operator procedure is taskflow/deploy/dependency-upgrades.md. Exercise: choose a dependency, explain its origin, identify target blockers and specify missing regression coverage before requesting an update. Lesson37 reviews Laravel13 features against the project before the course hub.

References: Composer CLI, Laravel13 upgrade guide. Navigation: Lesson35 · Roadmap.

Laravel 13 course navigation

Previous lesson (35) · Next lesson (37) · All 37 lessons