How to Kill your Drupal Site: Updates

It seems counter intuitive, but sometimes the easiest way to bring your site down is to catch up with your updates.

Let me qualify that, slightly: the risk of bringing your site down grows considerably when you're not constantly keeping up with updates. If you've neglected your updates for more than a few months or so, you may be inviting the WSOD (White Screen of Death--a digital grim reaper, of sorts) the next time you run your updates. Even without months of neglect, unless you're paying attention, updates can still be deadly to your site. Here's why:

Dependencies

Dependencies are what make Drupal Drupal; they put the system in 'Content Management System'. They're fundamental to how sites like Drupal and Wordpress work, so if you're playing the CMS game, you'll want to have a good understanding of what dependencies are.

Let's start with an analogy. A CMS is rather like a living organism. It has a central nervous system (Drupal Core, for example) that developers can tap into in order to provide various extensions and features (most often, via modules or plugins). The same way moving your arm is dependent on any number of core body functions (oxygen from your lungs that flows to your blood, caloric intake, signals from your brain), most modules and plugins can't really work without tying into other elements of your site. In some cases, certain modules not only tie into core--they tie into each-other. This can make for a spiderweb of inter-dependency. In order for something to work right, something else has to work right, too; in order to update one module, you may have to update another.

Here's a real world example of what this can look like (and another). Let's say your Drupal site is running on version 8.7.6 of Drupal core. It's been a while since you updated core, and your site has been sending you those annoying e-mails reminding you that there are security updates available. It's suggested that you update to the newest release of the site: Drupal 8.8.2.

First, let's do the math: 8.8.2 doesn't immediately follow 8.7.6--you've obviously missed more than a couple updates to Drupal core. "The site is smart enough to send me e-mails about updates!"--you think--"It probably knows what's best for me... let's get this update under way."

STOP. Don't do it. You're about to unleash a gargantuan bag of ugly on your site.

Before you do anything, let's make a backup of your database (make sure you're confident with how to restore your database as well--pretty straight forward if you have phpmyadmin: export to make a backup; drop all tables and import to restore); next let's make a backup of your site code (you're committing with Git for each and every update--right?).

Okay... now that that's out of the way, let's have a look at why your update is likely to catastrophically fail. In short, it's because you have no idea what's happened between your version of core (8.7.6) and the one that Drupal thinks you need. In this very specific case, Drupal core underwent some rather drastic changes right around 8.8.0. In order to know what those changes were, you'd need to look at the documentation for that specific update. Right off the bat, here's a real zinger:

If you have the contributed Pathauto module enabled, you must update to the latest version of Pathauto before or at the same time as you update to Drupal 8.8.0. Failure to update Pathauto before updating core could result in data loss. Drupal 8.8.0 declares a conflict with Pathauto 8.x-1.5 or lower for this reason. (Source)

Okay... so what's true for 8.8.0 will be true upstream for 8.8.2; you can't go there unless you update Pathauto first. Now, Pathauto is probably running on most Drupal sites in 2020--so this is likely an issue for most everybody looking to run this update. Pathauto, if you don't recall, is the module that creates URL patterns for content types (it's used to turn 'mysite.com/node/1281' into 'mysite.com/title-of-my-page'). This means that without the update to pathauto, updating core will result in most of your site's internal links breaking. That bit about data loss means that once the links are broken, they won't come back (yes... I know from experience--my database restore game is strong, though).

8.8.0 didn't only have Pathauto as a dependency, though. Here's a dependency that could not just break links, but break your entire site:

PHP 5.5 and 5.6 support was officially removed in 8.7, but Drupal still allowed sites to apply security updates on those PHP 5 versions. Drupal 8.8.0 ends that support and updates will now fail if servers are not updated to at least PHP 7.0.8. (Source)

This bit refers to the version of PHP you have installed on your server (if you're not sure, either do some digging on your cpanel or get a hold of your hosting company to confirm). In this case, if you're running a legacy version of PHP on the server, your update will fail. The definition of failure here isn't made clear, but I wouldn't race to find out. Regardless, any reputable host should be running a modern version of PHP in 2020; the chances of your server running PHP 5.5 or 5.6 as a default are perhaps small. In some cases, though, hosts allow users to "self provision" their needs: meaning they won't change your PHP version unless you request them to (there are good reasons to self provision like this).

A PHP version change at the server level is nothing to take lightly, though. You'll want to do a somewhat thorough check that the new version is fully compatible with your codebase; this is something usually done at the command line by installing PHP CodeSniffer alongside a localhost copy of your site.

The Moral

Running updates, whether core or modules/plugins can be a very risky business. There are three best practices to help minimize that risk: 1) stay on top of them--i.e.; don't go months on end without updating, and 2) walk through your updates--i.e.; don't skip from 8.7.6 all the way up to 8.8.2. It's a pain in the butt, but modules and core sometimes need to be upgraded one version at a time. This is easier with the help of tools like Drush and Git. For a novice, these can be difficult to set up; if you can get them into your entire workflow, though, the effort will more than pay for itself. Lastly, 3) READ THE DOCUMENTATION for your updates. The fine print matters; it can mean the difference between keeping with industry trends and losing your site altogether. If everything is already going wrong, the documentation can shine a light on why. Don't take it for granted that your modules and core are going to seamlessly integrate.

And...

Lastly, because it can't be stressed enough, before you even think about making that update, back up your database and code. No matter how rough your updates are, so long as you've got backups there's no need to panic.