Laravel upgrades and refactoring

Laravel Upgrade & Refactoring

Version-aware changes and upgrades

• Never upgrade the Laravel major version, PHP constraint or unrelated Composer packages outside the scope of the task.
• When working in an upgraded Laravel 11 or 12 application that retains the Laravel 10 directory structure (app/Http/Kernel.php, app/Console/Kernel.php, app/Exceptions/Handler.php), preserve that structure unless migrating to bootstrap/app.php was explicitly requested.
• When an upgrade IS requested, inspect composer.json, first-party package compatibility (Sanctum, Horizon, Cashier, Telescope, Livewire, Inertia, Filament), deprecated helpers/methods, cast declarations and middleware aliases step by step.

Incremental refactoring of existing Laravel code

• Before refactoring a fat controller, god model or tangled observer, lock down current observable behavior (HTTP responses, database writes, dispatched jobs/events, authorization edge cases) with feature tests.
• Refactor in small, independently verifiable steps:
  1. Extract request validation into a FormRequest and authorization into a Policy without changing response shapes.
  2. Replace N+1 loops, hidden accessor queries or duplicated query constraints with eager loading and local scopes.
  3. Extract complex multi-step business logic into a focused Action or Service class only where it clarifies responsibilities, keeping the existing route, controller signature and API Resource output stable.
• Make hidden side effects explicit: move external calls, notifications or cascade writes out of model saving/updated observers when they surprise callers or complicate testing, while ensuring every caller preserves the required behavior.
• Document any required post-deploy steps (php artisan migrate, config:clear, route:clear, queue:restart) in the handoff.