Laravel Upgrade Playbook (2026): Risk-Based Migration to Laravel 12

Enterprise upgrades fail for predictable reasons: dependency drift, weak tests, production-only behavior (queues, schedules, file paths), and “big bang” releases. This playbook shows how to upgrade to Laravel 12 with controlled risk, staged rollout, and a tested rollback plan.

Laravel 13 is now the current version. It was released on March 17, 2026, and supports PHP 8.3 to 8.5. This playbook covers the move to Laravel 12, whose bug fixes ended on August 13, 2026, and whose security fixes end on February 24, 2027, so treat 12 as a stepping stone and plan the next move to 13. The audit, CI, rollout and rollback steps below do not depend on the target version. For the 12 to 13 step, use the official Laravel 13 upgrade guide.

If you want the full enterprise context first, read: Laravel Development (2026): The Complete Guide to Building & Scaling Enterprise Applications.

If you want a team to execute the upgrade end-to-end: Laravel Upgrade Service.

---

Quick navigation

• 1) Low-risk upgrade principles (enterprise rules)
• 2) Pre-upgrade audit (what to inventory)
• 3) CI gates: the safety net most teams don’t have
• 4) Choose your path: 11 → 12 vs 10/9/8 → 12
• 5) Execution plan: branch strategy + dependency mapping
• 6) Migrations & data safety (the real downtime risk)
• 7) Queues, Horizon, and background jobs during upgrade
• 8) Staged rollout: canary, feature flags, and rollback
• 9) Copy/paste enterprise checklist

---

1) Low-risk upgrade principles (enterprise rules)

• Separate upgrade from feature work (upgrade branch only).
• Backwards-compatible DB changes first (deploy schema changes before code that uses them).
• Two-phase deploys: expand (add new) → migrate (switch) → contract (remove old).
• Canary releases beat big-bang releases.
• Rollback is a plan, not a hope: you must know exactly how to revert safely.

Enterprise truth: Laravel upgrades don’t cause downtime by themselves. Poor release process and unsafe database changes do.

---

2) Pre-upgrade audit (what to inventory)

Before you touch Composer, you need a clear picture of what’s in production.

1. Runtime: PHP version (web + workers), OS/container images, Node tooling (if applicable).
2. Laravel: current version, installed first-party packages, custom macros/providers.
3. Dependencies: the top packages that can block upgrades (auth stacks, tenancy, Spatie, payment libs).
4. Infrastructure: DB version, Redis, queue drivers, Horizon config, cron/scheduler behavior.
5. Risk surfaces: auth, payments, billing, scheduled jobs, file uploads, reporting, integrations.
6. Observability: error tracking, logs, APM, queue metrics.

Upgrade time is decided here. A clean Laravel 11 app with tests can be quick. A legacy app with dependency drift often needs a planned modernization path.

---

3) CI gates: the safety net most teams don’t have

Enterprises upgrade safely because they have automated gates. At minimum, your upgrade branch should run:

• Test suite: unit + feature tests
• Static analysis: PHPStan/Psalm (or at least strict linting)
• Code style: enforce consistency (prevents “fix chaos”)
• Security scan: dependency vulnerability scanning
• Smoke tests: critical endpoints + queue health

If you don’t have CI gates, the upgrade will still happen—but your risk moves from “controlled” to “hope-based.” That’s exactly why upgrade projects often include CI hardening.

---

4) Choose your path: 11 → 12 vs 10/9/8 → 12

Your upgrade plan depends on what version you’re on today.

Current version	Recommended approach	Why
Laravel 11	Direct 11 → 12 upgrade	Typically low friction; focus on dependencies + regression tests.
Laravel 10	10 → 11 → 12 (controlled)	Reduces unknowns; easier to isolate breaking changes.
Laravel 9/8	Modernization upgrade plan	Higher dependency drift; more edge-case behavior; requires staged remediation.

Enterprise advice: If the app is revenue-critical and old, do not jump versions blindly. Move step-by-step so you can isolate failures.

---

5) Execution plan: branch strategy + dependency mapping

5.1 Upgrade branch strategy

• Create a dedicated upgrade branch.
• Freeze feature merges into the upgrade branch (merge only critical fixes).
• Keep commits small and scoped: “bump framework”, “fix package A”, “fix tests”, etc.

5.2 Dependency mapping (the real work)

The most common upgrade blockers are third-party packages. Build a dependency map:

• List top packages by impact: auth/SSO, tenancy, payments, media/storage, queues, admin panels.
• Check compatibility with Laravel 12 + your PHP target.
• Replace abandoned packages early (avoid time sinks).

Enterprise rule: upgrade “outer layer” dependencies first (tooling), then the core framework, then feature-adjacent packages.

---

6) Migrations & data safety (the real downtime risk)

Framework upgrades rarely cause downtime. Database migrations do—especially on large tables.

6.1 Use the expand → migrate → contract pattern

1. Expand: add new columns/tables (backwards compatible).
2. Migrate: deploy code that writes both old + new, backfill in background.
3. Contract: remove old columns only after you verify stability.

6.2 Avoid table locks during peak hours

• Break big migrations into safe steps.
• Avoid index creation on huge tables during peak traffic without planning.
• Prefer online schema change approaches when needed.

---

7) Queues, Horizon, and background jobs during upgrade

Queues are where upgrade regressions hide: serialization changes, timeouts, retry policies, and long-running jobs.

• Pin worker runtimes (same PHP version, same env vars).
• Review timeouts + retry_after so jobs don’t double-process.
• Ensure idempotency in critical jobs (emails, webhooks, billing).
• Staging replay: run production-like jobs in staging using sampled data.

If queues are central to your product, this is often where maintenance and upgrade scopes overlap. See: Laravel Maintenance.

---

8) Staged rollout: canary, feature flags, and rollback

8.1 Canary release (enterprise default)

Deploy the upgraded version to a small slice of traffic first (or one tenant/region). Monitor stability before expanding rollout.

8.2 Feature flags for risky areas

• Wrap risky changes behind a flag (auth flows, pricing, billing, integrations).
• Flags allow fast rollback without redeploying.

8.3 Rollback plan (define it before release day)

• Rollback steps for code deployment
• Rollback steps for DB migrations (if any irreversible changes exist, stop and redesign)
• Queue draining strategy (avoid replaying jobs incorrectly)
• Who approves rollback decisions (owner + escalation contact)

Enterprise rule: If you can’t roll it back safely, it’s not ready to deploy.

---

9) Copy/paste enterprise upgrade checklist

1. Inventory runtime, dependencies, infra, and risk surfaces.
2. Set up CI gates (tests, static analysis, security scan, smoke checks).
3. Create an upgrade branch (no feature merges).
4. Map critical packages + compatibility; replace abandoned packages.
5. Upgrade step-by-step for older apps (10 → 11 → 12).
6. Use expand → migrate → contract for schema changes.
7. Validate queues in staging (timeouts, retries, idempotency).
8. Release via canary; monitor p95 latency + error rates + queue health.
9. Keep a written rollback plan with owners + steps.
10. Post-upgrade: schedule monthly dependency audits + quarterly minor updates.

Case studies: a PHP 5.6 to Laravel 13 upgrade for a cabinet manufacturer and a loyalty system moved from PHP 5.6 to Laravel.

---

Next steps

Building a new enterprise Laravel product? Explore: Laravel Development Services and Laravel AI Development.

---

FAQ

What causes downtime in a Laravel 12 upgrade?

Downtime is usually caused by risky database migrations, big-bang deployments, and insufficient staging validation—not the framework upgrade itself.

What’s the biggest risk in enterprise Laravel upgrades?

Third-party dependencies and production-only behaviors (queues, schedule timing, file paths, edge-case payloads). That’s why dependency mapping and staging replay are essential.

Should we jump from Laravel 9 directly to 12?

For enterprise systems, it’s safer to upgrade step-by-step (9 → 10 → 11 → 12) or use a structured modernization plan, so you can isolate breaking changes and reduce risk.

Do we need to upgrade PHP at the same time?

Often yes. Enterprises should align PHP versions across web and workers, then upgrade Laravel with consistent runtime environments to avoid “works on web, fails in workers” problems.