October 27, 2024
I follow these general steps when manually updating a Laravel or Statamic project. These steps might seem obvious, but having steps to follow when faced with a long list of errors helps me get my head in order and get on with the update.
I'm sharing them in the hope they will be helpful to someone else, too.
Run composer update or composer update -W and see what you get.
Chances are there will be a bunch of errors and problems, often due to incompatible versions of packages and their dependencies. The list will be long and scary, possibly making you panic a bit.
Pick one error/package to start with.
Check upgrade guides for packages if there are any. Laravel and Statamic both have upgrade guides; some minor packages might not, but there might be something in the README or in the GitHub issues/pull requests discussions.
There is no need to worry about any packages in the vendor file; only packages that are in the composer.json file are my problem. Even if you get an error with some illuminate package in the vendor directory, that's probably a dependency of something in my composer. By updating that, this error should disappear. The package you need to focus on may be buried halfway down the list of errors, not even at the beginning or end.
You might need to do some code updates, for example, update a middleware or a config file or remove some references in the code base. That might be the case when a package gets integrated into a framework and no longer needs to be installed separately. These changes should be mentioned in the upgrade guide. Don't just skim the upgrade guide; read it properly.
Also, read the error message. It tells you what you need to do. Sometimes it's a bit cryptic, but in most cases, it actually says what is wrong and what needs to be done. You could take the message and rewrite it in your own words. Delete what doesn't serve you until you are left with something you understand. Something that doesn't make your brain spin.
If you do have to remove a package, the correct way to do it is to use composer to remove it: composer remove [package]. However, since the composer update is most likely broken at this point, it might not work, and you might get Removal failed, reverting ./composer.json to its original content. You'll need to delete the package from composer.json manually and then run composer update again.
Remember, composer update uses composer.json while composer install uses composer.lock. For updating packages, run composer update.
Most importantly, don't panic. The errors are awful; they are long and confusing, and they spam your brain with information you don't need. It feels like it's too much, but take a deep breath and take it one step at a time.
You've got this 💪.