I took a copy of an old billing and estimates app and tried to move it from Laravel 6 to Laravel 12 in one jump. Separate repository, disposable environment, permission to make a mess. I wanted to find out where I'd get stuck before anyone handed me the real job.
I think of it as a visit to the technical debt museum. The exhibits were a custom authentication provider I was once proud of, a routing system that still carried around an abandoned plan for multitenancy, and an impressive number of ways for PHP to fail before it could serve a page.
This was an exercise on a copy, with basic operation as the finish line. The interesting parts are the decisions and the failures along the way. Use the version-by-version upgrade guides and your own regression checks to plan a production migration.
What I started with
The app had 14 models, mostly around estimates and invoices, more than 15 controllers, and no automated tests. Its local Docker setup ran Apache. The database and Redis weren't part of that setup, so getting a stage environment ready had meant setting up an EC2 instance separately.
The application declared PHP ^7.2 in Composer, while the old development Dockerfile was already on the PHP 7.4 Apache image. Those were two different facts about the same project. The target for this exercise was PHP 8.4 and Laravel 12.
{
"php": "^7.2",
"laravel/framework": "^6.2",
"fzaninotto/faker": "^1.4"
}There was a lot more going on than the version numbers suggested. The app registered its own auth provider, used a handful of custom facades, and read some routes from Config::get('routes'). I once thought the custom provider was clever. If I were building the same app today, I'd try the framework's defaults first.
The order I tried
- Get PHP 8.4 and Composer running in a repeatable local environment. Bring the database into that environment so app boot doesn't depend on a temporary stage machine.
- Resolve Composer dependencies for Laravel 12. Review replacements for packages that are no longer maintained and remove packages only after identifying what the app used them for.
- Get the framework to boot, then work through model and seeder namespaces, routes, and the authentication flow.
- Check basic application behavior. For a production project I'd also need representative billing and estimate flows, third-party integrations, and a rollback rehearsal.
I made the framework jump all at once because this was an experiment. I could still work through failures in layers. That was a useful distinction to make when Composer succeeded and the application still refused to start.
PHP, Docker, and Composer
Rebuild the runtime before chasing app errors
I moved the old PHP 7.4 Apache image to PHP 8.4 and refreshed Composer. The Dockerfile also consolidated OS package installation and built the extensions the app needed, including ZIP and Intl. That gave me a known runtime before I started changing code.
The fuller local setup used Nginx in front of PHP-FPM with a MySQL service. Redis was in the proposed stack for cache and sessions. A Node container was meant to support Vite. The old checkout didn't have a package.json, which told me that starting a Node service was a separate frontend task with its own prerequisites.
Go through the Composer changes one by one
| Dependency | Starting point | Experiment |
|---|---|---|
| PHP constraint | ^7.2 | ^8.4 |
| Laravel framework | ^6.2 | ^12.19.3 in Composer |
| PHPUnit | ^8.0 | ^11.0 |
| Faker | fzaninotto/faker | fakerphp/faker |
| Ignition | facade/ignition | spatie/laravel-ignition |
I ended up updating 83 packages. The abandoned Faker package was an obvious replacement. I also reviewed whether I still needed fideloper/proxy and doctrine/dbal, since newer Laravel versions cover parts of what those packages provided. Check the pieces your application actually uses, especially if it calls a package directly.
I considered tools like Pint, Breeze, Sail, and Predis as part of the refresh. They solve different problems. Adding a formatter or scaffolding a new login flow can be a separate decision from getting the old application to boot.
PHP compatibility affected independent pieces of the app too. I looked for removed functions such as each() and create_function(), reversed arguments to implode(), and code that caught Exception even though the upgraded runtime could throw an Error. Throwable covers both in PHP. I still want the catch to sit at a boundary that can actually handle the failure.
The Apple Silicon detour
I lost time to container startup on an Apple Silicon Mac. Several services took long enough to time out. A temporary architecture-specific image got me unstuck, then I switched back to official multi-architecture tags where available. The PHP image that worked for me was php:8.4-fpm-alpine.
I also moved sessions and cache to file-backed stores for this stage of the experiment. That let me take Redis out of the boot path while I worked on Laravel. For a multi-instance production deployment, shared session and cache requirements need their own decision.
The database was another source of ambiguity. Compose can start a MySQL container before MySQL is ready to accept connections. I put a health check on the database and made the PHP service depend on the healthy state.
php:
depends_on:
mysql:
condition: service_healthyAlpine kept my image smaller. It uses musl, so verify any legacy binary or native extension that expects glibc before you base your image on it. I found that CPU architecture, database readiness, and PHP boot were worth checking separately. All three can look like “the container never came up” when you're staring at the terminal.
What broke after Laravel 12 installed
Composer's PSR-4 errors were literal
I moved models such as App\User to App\Models\User, and seeders from database/seeds to database/seeders under Database\Seeders. I had to update references in controllers, factories, and seeders. I also switched seeders over to the matching PSR-4 autoload mapping.
Then Composer gave me several PSR-4 warnings. Some files had a different name than the class they contained. Others had App\models in the namespace and Models on disk. Those are easy to miss on a case-insensitive development filesystem. I checked the namespace, directory, filename, and class name together.
I also went through service providers in config/app.php, environment variables in .env.example, and the registered route files. A success message from Composer only gets you as far as an installable dependency graph.
I was still booting the Laravel 6 application
One boot attempt failed with Class "Illuminate\Foundation\Application" not found. In that attempt I was trying to start the newer dependency set with the old app bootstrap wiring.
I switched the experiment to the newer skeleton's Application::configure(...) style and wired in the route files and middleware intentionally. That cleared the boot error in this copy. Laravel's own upgrade guidance says existing applications can keep their structure. On a real upgrade, first verify the vendor autoloader and inspect which bootstrap file, route files, and provider registrations are in use. The new skeleton was a choice I made for this experiment. Laravel 11 application structure guidance
Routes and login were where the old decisions showed up
The controller namespace was coming from somewhere
The old app stored strings such as LoginController@login in its route configuration. The route provider made those work by prefixing the controller namespace. Laravel 8 changed the default for newly created apps. An upgraded app can retain the old RouteServiceProvider and its namespace setting.
When I moved to the newer skeleton, I made controller references explicit. The callable form gives the IDE a real class to navigate to.
use App\Http\Controllers\LoginController;
Route::get('/', [LoginController::class, 'index']);
For configuration that still stores action strings, I reviewed where each string was resolved before changing it. That was more useful than changing every occurrence of Controller@ across the repository. Laravel 8 controller namespace changes
The stale auth trait was easy to remove. The behavior was the part to check.
My app still imported AuthenticatesUsers. Its custom login action was already validating input, calling Auth::attempt(), and regenerating the session on success. Its custom logout action already regenerated the token. That let me remove the unused import in this copy.
The old app didn't offer the remember-me or throttling behavior from the scaffold. If your app relies on those features, account for them when you replace or upgrade its authentication scaffolding. The legacy trait may come from Laravel UI, so look at the installed package and its compatibility as well as the framework version.
For a Blade form, I'd run the actual login and logout flow with the web middleware and the form's @csrf in place. I'd check a successful login, a rejected login, session regeneration, and access after logout. Add remember-me and rate-limiting checks if they are part of your app's contract. Laravel authentication docs
What I'd take into a real migration
The most useful thing about this exercise was being able to break the copy without worrying about anyone's production data or release schedule. Now, when I see a legacy Laravel app, I know to look for the Composer/runtime split, the assumptions in its bootstrap, and the handful of places where it quietly bypasses the framework's defaults.
To turn that knowledge into a production plan, I'd record a working baseline first. Then I'd pick a small set of behaviors a real user cares about, such as logging in, creating an estimate, raising an invoice, and exporting it. Those checks give the team a way to judge the migration while the dependency and infrastructure changes are still reversible. Laravel 12 upgrade guide
Q&A
Can I upgrade from Laravel 6 straight to Laravel 12?
This exercise shows that a direct jump can be worth exploring in an isolated copy. For a production plan, trace the breaking changes in the intervening upgrade guides, choose a rollout you can verify, and prepare rollback steps for both code and data.
Do I have to move models or adopt the new bootstrap structure?
Existing Laravel applications can keep their structure where the configuration supports it. I adopted the newer layout in this copy. If you move models or seeders, update their namespaces, all references, and Composer's autoload mapping together.
What should I check if Laravel installs but the app won't boot?
Start with the PHP version and extensions used by the runtime, the Composer autoloader, and the bootstrap file and providers actually being loaded. If the app is waiting on the database, confirm service readiness before digging into framework code.
For a separate example of checking PHP runtime changes, see the PHP 8.6 upgrade checklist.


コメントを残す