---
name: laravel-12-local-upgrade
description: Use when upgrading this local Laravel project from Laravel 8 to Laravel 12 while preserving every existing page, route, model, controller, Blade view, admin workflow, listing workflow, API, PDF, auth, queue, broadcast, asset, and database behavior. Applies only to local workspace work and requires explicit user approval before application code or dependency changes.
---

# Laravel 12 Local Upgrade

## Hard Rules

- Work only inside the current local workspace.
- Never connect to, deploy to, or modify any live server.
- Do not change application code, dependencies, database schema, assets, or environment files without explicit user approval.
- Treat the current Laravel 8 behavior as the source of truth until a verified Laravel 12 replacement behaves the same.
- Preserve user edits and dirty worktree changes. Do not revert unrelated changes.
- Separate analysis, implementation, review, and manager approval.

## Required Agent Roles

Use three roles for this upgrade:

- Implementer: prepares or applies approved code changes in a bounded file set.
- Reviewer: independently checks compatibility risks, regressions, missing tests, and unsafe assumptions.
- Manager: performs a deeper end-to-end readiness review across routes, pages, workflows, packages, and rollback safety.

If the user has not approved implementation yet, all three roles must stay read-only and produce findings only.

## Local Baseline

Before any upgrade edit:

1. Record `git status --short`.
2. Record PHP, Composer, Laravel, Node, and npm versions.
3. Record installed direct Composer packages and blockers with `composer why-not laravel/framework ^12.0`.
4. Record route inventory with `php artisan route:list`.
5. Clear and rebuild safe caches locally when needed: `php artisan config:clear`, `php artisan route:clear`, `php artisan view:clear`.
6. Inventory Blade entry points, controllers, models, middleware, policies, events, jobs, commands, factories, seeders, and config files.

## End-to-End Coverage Map

Build a coverage map before implementation:

- Public pages: home, property/listing detail, search, contact, about, policy pages, sitemap.
- Auth pages: login, register, password reset, verification, account activation.
- User pages: profile, tenders, favorites, SMS activation, bidding flows.
- Admin pages: dashboard, banks, properties, property images, archive files, users, logs, PDF downloads, custom mail.
- API: JWT authenticate and protected realty endpoints.
- Realtime: broadcast events, private channels, Echo/Pusher/WebSocket behavior.
- Documents: DOMPDF contracts and tender reports.
- Background work: scheduler commands, queue jobs, mail, SMS helper, notifications.
- Data layer: migrations, factories, seeders, model casts, relationships, scopes, slugs, soft deletes.
- Frontend assets: Laravel Mix, compiled public assets, Echo/Pusher bootstrap, jQuery plugins, uploaded/static assets.

## Upgrade Strategy

Prefer staged framework upgrades:

1. Laravel 8 to 9.
2. Laravel 9 to 10.
3. Laravel 10 to 11.
4. Laravel 11 to 12.

At each stage:

- Update only the minimum necessary dependency set.
- Resolve abandoned or incompatible packages with behavior-preserving replacements.
- Run Composer with `--with-all-dependencies`.
- Run route, view, config, and targeted workflow checks.
- Stop and report if a page or workflow cannot be verified.

## Known High-Risk Packages

Audit these before changing versions:

- `beyondcode/laravel-websockets`: abandoned; replacement must preserve Echo/Pusher-compatible live bidding.
- `fruitcake/laravel-cors`: replace with framework CORS middleware when required.
- `tymon/jwt-auth`: verify Laravel 12 compatibility or choose a compatible JWT/API auth plan.
- `laravel/ui`: preserve current Blade/bootstrap auth scaffolding behavior.
- `laravel/sanctum`: update only if its token behavior remains compatible.
- `barryvdh/laravel-dompdf`: verify facade name, config, PDF output, remote assets, and paper settings.
- `cviebrock/eloquent-sluggable`: verify slug generation and update behavior for users/properties.
- `intervention/image`: verify image upload/resizing APIs before moving major versions.
- `rap2hpoutre/laravel-log-viewer`: verify admin log route and published vendor view.
- `spatie/laravel-sitemap`: verify sitemap generation route output.

## Verification Gates

Do not call the upgrade ready until these pass locally:

- `composer validate`
- `composer why-not laravel/framework ^12.0` has no relevant blockers after approved dependency changes.
- `php artisan --version` reports Laravel 12.
- `php artisan route:list` succeeds and expected named routes remain present.
- `php artisan view:cache` succeeds or every failing Blade file is fixed and rechecked.
- Existing tests pass or test failures are explained with file-level causes.
- Critical pages return successful local responses under a local server.
- Login, admin access, listing detail, bid flow, PDF generation, image upload, API auth, and realtime updates are manually or automatically checked.
- Manager review lists residual risks and explicitly separates local-ready from production-ready.

## Reporting Format

Use this structure for analysis and readiness reports:

1. Current baseline.
2. Route and page coverage.
3. Package compatibility blockers.
4. Code compatibility blockers.
5. Data and migration risks.
6. Frontend and asset risks.
7. Verification plan.
8. Required approvals before implementation.
9. Residual risks and rollback plan.