Fast. Simple. No meetings. No delays.
Home / Blog / Laravel / How to Upgrade an Old Laravel Application Safely

How to Upgrade an Old Laravel Application Safely

A safe path for upgrading an old Laravel application: reading upgrade notes, stepping through versions, fixing packages and verifying behaviour.

Cover graphic for the article: How to Upgrade an Old Laravel Application Safely

To upgrade a Laravel application safely, pick a supported target version, protect your work with backups, a branch and tests, then move one major version at a time while reading each official upgrade guide, fixing packages and verifying behaviour. Deploy to staging first and keep a rollback path. This guide walks through each stage.

Decide the target version to upgrade your Laravel application

Start by finding out where you are: check the framework version in composer.lock and the PHP version on every environment. Then check the official Laravel release notes for the currently supported versions and their support windows. These change over time, so rely on the documentation rather than on memory or an old blog post.

Your target is usually a currently supported release, and the PHP version it requires may be newer than the one you run, which can mean a PHP upgrade first. Our PHP 7 to PHP 8 checklist covers the language layer. Also decide how ambitious the goal is: only reaching a supported version, or also adopting the newer structure and features. Doing the first before the second keeps each change small and reviewable.

Backups, branches and tests

Before you change anything:

  • Take verified backups of the database and uploaded files, and confirm you can restore them.
  • Create a dedicated upgrade branch, and keep the main branch deployable for urgent fixes.
  • Make sure you can build the application locally and on a staging server that mirrors production.
  • Run the existing test suite and record the baseline. If tests already fail, note which, so you can tell old failures from new ones.

If the application has few or no tests, write characterisation tests for the most important behaviour first: login, key calculations, imports and exports, scheduled jobs, payments and anything customers or staff rely on daily. Tests need not be perfect; they only need to catch big regressions. A manual test script is better than nothing, though less repeatable.

Step through major versions

Laravel's official guidance is to move one major version at a time. Skipping versions can seem faster, but it merges several sets of breaking changes into one confusing debugging session and makes it hard to see which change caused which failure. The slower path is usually quicker overall.

For each step:

  1. Read the official upgrade guide for that version end to end, and write down every item that applies to your code.
  2. Update the framework requirement and related packages in composer.json, then run the update.
  3. Fix errors in the order they appear: autoload and package conflicts, then boot errors, then test failures.
  4. Run the tests and click through key flows.
  5. Commit with a clear message, and only then start the next version.

Automated helpers exist, including refactoring tools with Laravel rule sets and paid upgrade services. They can handle a lot of mechanical changes, but review the results and still run your tests.

Package compatibility

Packages are where upgrades usually stall. Make a table of every Composer dependency with its current version, the version supporting your target and its maintenance status. Use composer outdated and composer why-not to see what blocks you. Then handle each package in one of these ways:

SituationTypical action
New version exists and supports your targetUpgrade it, read its changelog
Maintained but behindCheck open issues and pull requests, consider a temporary fork only as a short-term bridge
Abandoned, small functionalityReplace with a small amount of your own code
Abandoned, large functionalityFind a maintained alternative and plan the migration as its own task
Replaced by framework featuresRemove it and use the built-in feature

Be wary of long-lived private forks: they pull maintenance work into your team. Note the security aspect, too: an abandoned package will not receive fixes. Our OWASP-based PHP security checklist covers dependency hygiene.

Config and structure changes

Across major versions, the framework's default skeleton changes: configuration files, middleware registration, service providers, route files, the console kernel and directory layout. Newer versions have also slimmed down the default application structure. You are not always forced to adopt the new layout, since existing applications typically keep working with their current one when the upgrade guide's required changes are applied, but check the guide for what is mandatory and what is optional.

Practical tips:

  • Compare your configuration files with those of a fresh application of the target version, and merge in new keys deliberately rather than overwriting.
  • Review environment variable names, cache and session drivers, queue and mail settings.
  • Check any custom exception handler, middleware, service providers and authentication code, since these touch framework internals.
  • Clear and rebuild config, route and view caches after each change.

Regression checks

After the tests pass, test as a user would. Build a regression checklist from your own application:

  • Login, logout, password reset, and permission boundaries for each role.
  • Every form that writes data, with valid and invalid input.
  • Queues, scheduled commands and emails, which often fail silently.
  • File uploads, downloads and generated documents.
  • Integrations with payment, accounting or shipping services in their sandbox modes.
  • Reports and exports compared with known results from before the upgrade.
  • Database migrations run against a copy of production data, including timing.

Review the log files during all of this, including deprecation warnings that you can fix now rather than later.

Deploy and monitor

Deploy the upgrade as you would any release, but more carefully. Rehearse on staging with production-like data. Pick a quiet window, take a fresh backup, deploy, run migrations, rebuild caches, restart queue workers, and smoke test the critical flows. Keep the previous release available so rollback is a matter of redeploying it, remembering that database migrations may need reversing or be designed to be backward compatible.

Afterwards, watch error tracking and logs closely for a while, and note the upgrade date and the next planned review in your maintenance calendar. Regular small upgrades are much easier than a long gap; keeping a PHP or Laravel application healthy describes a sustainable rhythm. If an upgrade turns out to be a deeper problem than version bumps, consider the options in modernizing a legacy PHP application.

If you would like an outside review of an old application before you commit, see our software development for US businesses page, or contact us with the framework and PHP versions you are on.

Frequently asked questions

Should I skip versions?

It is safer not to. Laravel's guidance is to upgrade one major version at a time and read each upgrade guide. Skipping combines several sets of breaking changes, making failures harder to diagnose. Smaller steps with tests and a commit after each are usually faster overall.

What if a package is abandoned?

Look for a maintained alternative, a built-in framework feature, or a small replacement written in your own code. Treat a private fork as a short-term bridge only, because you inherit its maintenance and security fixes. Plan the replacement as its own task with tests.

How long does a Laravel upgrade take?

It depends on how many versions behind you are, the number and health of packages, test coverage, customisation of framework internals and how much time reviewers have. Rather than guessing, scan the application, list the upgrade guide items that apply, and estimate each step.

Related articles

🚀 Start Now