DevWorkspace Pro

How to upgrade Laravel with Rector

Run the rector-laravel set of the next version, then finish with Composer. The commands we tested, the casts trap, and a one-click recipe for DDEV.

Updated 3 min read
On this page
  1. Run one set for the next version
  2. Do not stop before Composer
  3. Or run it with one click, on DDEV
  4. Limits

To upgrade Laravel with Rector, run the rector-laravel set of the next version, for example LaravelSetList::LARAVEL_110 for Laravel 10 to 11, then update your packages in composer.json and run composer update -W, because Rector changes your code and not your dependencies. DevWorkspace Pro has a Laravel Upgrade recipe that does the Rector part with one click, but it works only on Laravel projects that run in DDEV.

The usual complaint is that Rector ran and nothing changed. This developer was moving from Laravel 11 to 12, and this one saw no changes on a fresh install. Both were on withComposerBased.

Run one set for the next version

Install the two packages:

composer require --dev rector/rector driftingly/rector-laravel

Then put the set of your next version in a Rector config. This is for Laravel 10 to 11:

<?php

use Rector\Config\RectorConfig;
use RectorLaravel\Set\LaravelSetList;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/app',
        __DIR__ . '/config',
        __DIR__ . '/database',
        __DIR__ . '/routes',
        __DIR__ . '/tests',
    ])
    ->withSets([LaravelSetList::LARAVEL_110]);

See what it will change, then run it for real:

vendor/bin/rector process --dry-run
vendor/bin/rector process

On a fresh Laravel 10 app, this set changed one file, app/Models/User.php. On a real app, expect more files, so commit your work first and read the diff.

The two kinds of set are different. LARAVEL_110 has only the rules of that version. The maintainer explains that UP_TO_LARAVEL_110 includes everything from earlier versions too, so it can touch code that has nothing to do with this upgrade. If you use withComposerBased, it does nothing unless you also register LaravelSetProvider.

Do not stop before Composer

On that app, Rector moved the $casts property into a casts() method. This is correct for Laravel 11, but Laravel 10 does not read that method. We created a User with the password plain on Laravel 10, before and after the Rector run:

Casts on the model $user->password
Before Rector id, email_verified_at, password $2y$12$43y2GVlx...
After Rector, still on Laravel 10 id plain

So if your code relies on the hashed cast, your app can run with no error and save a password as plain text until you finish the upgrade. Treat the Rector run and the Composer update as one step.

For Laravel 10 to 11, we made these changes in the composer.json of the default app:

"laravel/framework": "^11.0",
"laravel/sanctum": "^4.0",
"laravel/tinker": "^2.9",
"nunomaduro/collision": "^8.1",
"phpunit/phpunit": "^11.0"

Then run composer update -W. Your own packages will differ, so go through the Laravel upgrade guide as well. It also lists config and other changes that Rector does not make.

Composer can refuse the version with this message: these were not loaded, because they are affected by security advisories. We got it for every Laravel 11 release. Composer does this on purpose. To go through Laravel 11 on your way to a newer version, run composer config audit.block-insecure false, and remove that setting from composer.json when you are done. A Composer dry run for Laravel 12 did not need it.

With those changes, the app reached Laravel 11.57.1, and php artisan test passed the two example tests. Then repeat all of this for the next version.

Or run it with one click, on DDEV

If your Laravel project runs in DDEV, DevWorkspace Pro can do the Rector part for you. The project must be running.

  1. Click Recipes at the right end of the project tab bar.
  2. Run Rector, then Rector Laravel. They install the two packages.
  3. Click Laravel Upgrade. It reads your version from composer.json and shows the next one.
  4. Click Proceed.
The Recipes panel with Rector set up, Rector Laravel installed and Laravel Upgrade ready to run.
Rector and Rector Laravel are in place, so Laravel Upgrade can run.
The Laravel Upgrade dialog showing Current: Laravel 10 and Next: Laravel 11, with Cancel and Proceed buttons.
The recipe moves one major version at a time.

The recipe runs the set of the next version on app, bootstrap/app.php, config, database, routes and tests, with a temporary config file that it removes after. You see the diff, the rules that applied and your next steps.

The finished Laravel Upgrade dialog with the end of the Rector diff, one file changed, and next steps that start with reviewing the changes and updating composer.json.
The Composer step is still yours, and the dialog says so.

To review the diff in the app, see Review Git changes and commit. For all the recipes, see the docs.

Limits

  • Recipe on DDEV only. On a Laravel project outside DDEV, the Recipes panel does not show Rector Laravel or Laravel Upgrade. Use the commands above.
  • The recipe does not change composer.json. So it keeps showing the same version until you update laravel/framework.
  • What we tested. Laravel 10 to 11 end to end on a fresh app, on macOS. After that, the recipe offered Laravel 11 to 12, and we did not run that step.
  • Versions. The recipe supports Laravel 8 to 13. On Laravel 13, it shows Up to date.

FAQ

Frequently asked questions

Does Rector upgrade Laravel by itself?

No. Rector changes your code. You still update laravel/framework and the other packages in composer.json, run composer update -W, and follow the Laravel upgrade guide.

Should I use LARAVEL_110 or UP_TO_LARAVEL_110?

For one upgrade step, use LaravelSetList::LARAVEL_110. It has only the rules for that version. The UP_TO sets include every earlier version as well.

Why did Rector change no file with withComposerBased?

withComposerBased does nothing unless you also register LaravelSetProvider, and it applies only the versioned rules. An explicit set in withSets avoids both questions.

Does the Laravel Upgrade recipe work on every Laravel project?

No. It works only on Laravel projects that run in DDEV. On any other setup, the Recipes panel does not show it, and you use the commands on this page.

Related

All guides

DevWorkspace Pro

One workspace for every project

Files, Git, GitHub, AI agents, the terminal and your runtimes in one desktop app. Works with every project folder.

macOS Windows Linux