Running Craft updates

Question

This is a newbie question regarding running Craft updates. In the past I've been caught out by stupidly running updates on the live server. I'm now trying to get into the habit of running the updates on a local version, then pushing that to the live version - the proper way of course. Am I right to assume that the only files that have been changed after an update are composer.json and composer.lock (along with the db)?

Answer 1

I guess you are running composer update to update craft. A composer update usually updates your composer.lock and the vendor folder. The composer.json defines your dependencies (and some additional information) and should never be changed by a composer update.

If you have the possibility I would use rsync with some excludes (for example the user upload folder(s)) to deploy your complete project, makes things easier.

Answer 2

composer.json and composer.lock aren't technically the only files that change; for example some of the files in the vendor folder change each time you update. If you're using Project Config, occasionally the project.yaml file will change if a plugin update makes some data architecture changes or something.

Some Info on Composer and Craft and Updating

The only time composer.json would change on an update is if you ran the update via Craft's updater. When you use Craft's updater, it disregards what is specified in the composer.json; it does its own checking and when it updates a package it locks the packages down in the composer.json to that particular version number. However, when you use composer update to do your updating, it will use what is specified in the composer.json to do see if there are any new versions that match the specified semantic versioning constraints (semver); running a composer update changes nothing in your composer.json file.

Here's an example of what the difference might look like:

1) "nystudio107/craft-seomatic": "3.2.3",   // Craft updates style (note the absolute version number)

2) "nystudio107/craft-seomatic": "^3.1.0",  // Composer semver style (note the '^')

When you run Craft's updater; it won't matter which of these lines you use. Craft will do its own checking and overwrite the current semver as necessary. If you use composer update, #1 won't allow you to install anything other 3.2.3 because that is what is explicitly declared; #2 will allow anything that fits 3.X.X. So if you've used Craft's updater in the past, you'll need to manually add ^ or ~ to your version numbers before composer update has any affect.

The composer.lock file works quite similarly to the way the Craft updater uses the composer.json package version numbers. It's basically a big file that contains the installed version number (as well as a bunch of other stuff) of every single package as well as all the dependencies. It changes any time you update, whether via Craft or composer.

Then you've also got composer install which behaves differently than composer update. composer update takes the semver provided in the composer.json file and checks to see if any newer version that fits the constraints are available, if so it installs it. composer install looks in the composer.lock file and installs whatever is specified there. This means that running composer install on an existing codebase should have no effect provided everything's previously been installed.

A Typical Craft Upgrade Strategy

Here are the typical steps for updating your Craft sites locally and pushing those changes to a live/production server.

1. Depending on whether you use Craft or composer for your updating:
   • Run composer update locally. Again, this fetches any newer package versions that comply with the semver, installs them, and makes the necessary changes to the composer.lock file. OR
   • Run Craft's updater locally. Again, this fetches any newer package versions, installs them, and makes the necessary changes to the composer.json and composer.lock file.
2. Depending on the nature of the updates, you may need to run a database migration locally. You'll also want to quickly test your site and make sure nothing broke because of the updates.
3. You'll commit the changes to composer.lock (and if you used the Craft updater, the changes to composer.json) and merge branches / push to your remote Git repo per your typical process.
4. Usually you'll have some sort of deployment process setup (Buddy, DeployBot, Laravel Forge deployments, etc) that watches your remote Git repo and does a deployment every time you push. This deployment usually looks like a git pull of the latest changes and then, depending on your deployment tool of choice, this next step might be done on the deployment server and the resulting files pushed to the live server or it might be done on the live server itself...

5. You'll typically need to do several things as part of the final step of the deployment process:

   1. Run composer install - remember, this takes that composer.lock file (which is now different from the files in the vendor folder on the live server) and installs anything it can (i.e. if the lockfile and the vendor folder agree on a certain package, it skips it; otherwise it updates it).
   2. Run your database migration on the live site.
   3. If you're using project config, and the project config file changed during the updates, you'll want to sync any changes there.
   4. Finally you'll want to clear caches so you get the latest and greatest on the frontend of your site.

   These steps take some time to do manually, which is why it is a good idea to automate them. You can run them all via the CLI via your deployment tool, but an even better idea would be to add them to the scripts in your composer.json file. For example:

   ...
   "scripts": {
     "post-install-cmd": [
       "@php craft migrate/all",
       "@php craft project-config/sync",
       "@php craft clear-caches/all"
     ],
     ...
   },
   ...
   

   If you add that to your composer.json, any time you run composer install those other three commands will be run directly after.

---

My apologies on the short answer, I was pressed for time. JK lol 😂