How to upgrade an old Laravel application safely

To upgrade an old Laravel application safely, first check which Laravel and PHP versions it runs and which packages hold it back, add tests around its most important features, then upgrade the Laravel version one major release at a time, deploying each step with a way to roll back. Jumping straight from a very old release to the latest in one go is where most upgrade projects go wrong. This guide explains each stage in plain terms.

Laravel is a PHP framework: a ready-made foundation that handles common jobs such as routing, databases, logins and emails, so developers can focus on your business logic. Each major release can change how parts of the framework behave, which is why upgrades need care. If you would like help with an older application, our custom software service page explains how we work.

Risks of staying on an old version

An application that works today can feel safe to leave alone. The risk is that problems build up quietly.

• No more security fixes. Laravel publishes a support policy: each release receives bug fixes for 18 months and security fixes for 2 years. After that, newly discovered security problems in that version are not fixed.
• Old PHP versions. PHP itself has a published support timeline. Older Laravel releases cannot run on newer PHP versions, so an old application can keep your server on a PHP version that no longer receives security updates.
• Package problems. Third-party packages drop support for old Laravel versions, so you cannot install fixes or new features.
• Harder hiring. Developers are most familiar with current versions. Old code takes longer for anyone new to understand.
• Bigger jumps later. Laravel releases a new major version every year, so each year of waiting adds another step to the eventual upgrade.

Upgrading regularly turns a risky project into routine maintenance.

Our guide on Laravel for business web applications explains why regular upgrades are part of owning one.

Auditing packages and PHP version

Before changing anything, find out exactly where you stand. This is a short, low-risk task that shapes the whole plan.

1. Check the current Laravel version. Run php artisan --version in the project folder.
2. Check the PHP version on every server. Include production, staging and any developer machines. Mismatched versions cause confusing bugs.
3. List your packages and how outdated they are. Composer, the tool that installs PHP packages, can list direct dependencies with newer versions available:

php artisan --version
composer outdated --direct

4. Find packages that block the upgrade. For each package, check whether a version exists for the Laravel release you are moving to. Composer's why-not command explains what prevents a given version from being installed, for example composer why-not laravel/framework ^13.0.
5. Identify abandoned packages. Some packages are no longer maintained. Plan to replace them, or to move their features into your own code.
6. Note custom changes to framework behaviour. Look for places where the application extends or overrides framework classes. These are the spots most likely to break.

The result should be a simple table: each package, its current version, the version you need and any replacement required.

When to replace a package instead of waiting

Sometimes a package you depend on has no version for the Laravel release you need, and no sign of one coming. Waiting can stall the whole upgrade. Consider replacing it when:

1. The package has had no updates for a long time and its issue list shows unanswered questions.
2. Laravel now offers the same feature itself, which the upgrade guides sometimes point out.
3. You only use a small part of the package, which could be written in your own code with tests.
4. A well-maintained alternative exists that does the same job.

Replacing a package is its own small project. Do it before the framework upgrade where possible, so each change can be tested on its own.

If anyone questions whether PHP is worth the effort, our guide on whether PHP is still used explains how the language has changed.

Adding tests before changing anything

Tests are small programs that check your application still does what it should. They let you upgrade with evidence instead of hope. Many older applications have few or no tests, so this step is often the biggest part of the work.

1. List the features that must never break. Logins, checkout, bookings, invoices, key reports and anything involving money.
2. Write feature tests for those journeys first. A feature test sends a request to your application and checks the response, just as a browser would. Laravel supports Pest and PHPUnit for this.
3. Use a separate test database. Tests should create their own data and never touch real customer information.
4. Add tests for tricky business rules. Pricing, discounts, permissions and date calculations are common places for silent changes.
5. Run the tests on the current version first. They must all pass before the upgrade begins, so any later failure is clearly caused by the upgrade.

A simple Pest feature test looks like this:

use App\Models\User;

test('the dashboard loads for a signed-in user', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->get('/dashboard')
        ->assertOk();
});

Even a modest set of tests covering the main journeys gives you far more confidence than clicking through the site by hand.

If you inherited the application from another developer, our guide on taking over a website explains the accounts and documentation to collect first.

How to upgrade the Laravel version one major release at a time

Laravel publishes an upgrade guide for each major release, and each guide covers the move from the previous version only. For example, the Laravel 13 upgrade guide describes upgrading from 12.x. Following them in order is the safest route.

1. Create a separate branch. Keep the upgrade work apart from everyday changes in your version control system.
2. Read the upgrade guide for the next version. Note each change marked as likely to affect you, and check whether your code uses those features.
3. Update PHP if the next version requires it. Each Laravel release lists its minimum PHP version. Laravel 13, for example, requires PHP 8.3 or newer.
4. Update the dependencies in composer.json. Change laravel/framework and the other packages listed in the guide to the new versions, then run composer update.
5. Work through the guide's changes. Update code, configuration and packages as the guide describes.
6. Run the tests and fix failures. Then click through the main journeys by hand on a test environment.
7. Repeat for the next major version. Only move on when the current step is stable.

Some upgrade guides include important choices. For example, the Laravel 11 upgrade guide introduced a slimmer default application structure, but recommends that applications upgrading from Laravel 10 do not try to migrate their structure. Reading the guides carefully saves unnecessary work.

Between major versions, it is often worth deploying each completed step to production. Smaller releases are easier to test and easier to undo.

Common problems to watch for

Every application is different, but some problems appear in many upgrades:

• Changed default behaviour. A feature may still work but behave slightly differently, for example in how database columns are modified. The Laravel 11 upgrade guide describes one such change to column modifications. Tests catch these far better than manual checks.
• Configuration drift. Older applications often carry configuration files from many versions ago. Compare them with the current defaults and update the settings the guide mentions.
• Queued jobs and scheduled tasks. Background work is easy to forget when testing by hand. Check that jobs still run and scheduled commands still fire.
• Front-end build tools. Upgrades sometimes coincide with changes to how CSS and JavaScript are built. Check that pages still look and behave as they should.
• Hidden reliance on old helpers. Code that calls functions removed or renamed in newer versions will fail. Searching the code base before upgrading saves time.

If you need outside help, our guide on hiring a Laravel developer suggests asking about previous upgrades.

Deploying with a rollback plan

A rollback plan is how you return to the previous working version quickly if something goes wrong after release.

1. Test on a staging server first. Staging is a copy of your live setup where you can test safely. Use the same PHP version and similar data.
2. Back up the database before deploying. Check that the backup can actually be restored, not just that the file exists.
3. Review database changes carefully. Some upgrades include database changes. Make sure you know whether they can be reversed.
4. Deploy at a quiet time. Choose a period with low traffic and with people available to watch the release.
5. Keep the previous release ready. Your deployment process should allow switching back to the last working version in minutes.
6. Watch errors and key actions after release. Check error logs, queued jobs, emails and payments closely for the first days.

Once the upgrade is complete, plan to keep up with each new release. Regular small upgrades are cheaper and safer than another large catch-up project in a few years.

A simple routine works well for most businesses: apply minor updates regularly as part of maintenance, and schedule each major upgrade once its guide is published and your key packages support it. Keeping the test suite growing with each new feature means every future upgrade starts from a stronger position.

After the upgrade, our Laravel security checklist is a useful review of production settings.

Summary

• Old Laravel and PHP versions stop receiving security fixes, and the gap grows every year.
• Start with an audit of Laravel, PHP and package versions, including blockers and abandoned packages.
• Add feature tests for the journeys that must never break, and make them pass before upgrading.
• Upgrade one major version at a time, following each official upgrade guide in order.
• Deploy through staging with a tested backup and a quick way to roll back.

An upgrade done step by step is rarely dramatic, and it leaves you with a codebase that is easier to maintain. If you have an older Laravel application that needs attention, you can tell us about it here.