Once you would like to update your Drupal 8 website (especially for the first time) you first google or visit official Drupal documentation. I did the same and stumbled upon very abstract tutorials without clear steps and moreover without references to the common issues you may face. Hence, this article was born. Hope it will help some Drupal 8 strugglers :)
Before we start with the update itself, a quick insight on dependencies. Basically, if ModuleA relies/depends on the functionality provided by ModuleB, we can say that ModuleB is a dependency for ModuleA. In other words, ModuleA cannot function properly without ModuleB.
Moreover, not just ModuleA depends on ModuleB, ModuleA version X depends on ModuleB version Y. The reason for this is that modules evolve independently and a newer version of ModuleB may be incompatible with what you reply/depend in your current version of ModuleA.
That’s why it’s critical to ensure your dependencies don’t have problems (conflicts), as blindly updating your ModuleB may break ModuleA and probably the whole website. Which will involve a lot of debugging later and potentially a downtime.
2. What are the ways to update Drupal 8 website
You have the following options (at least at the time this article was posted):
- Manual. Here you manually upload and install modules, which most probably will break your site. Main reason is that it puts you at risk not paying attention to all dependencies (that can be many) and suddenly you have “The website encountered an unexpected error. Please try again later.”. Hence, this options is not recommended and I personally discourage you from relying on it.
- Composer. The recommended way to update Drupal 8. It’s recommended, because Composer will take care of all dependencies and as minimum won’t allow you to bring your website down. Yes, it involves some studying, but you do this once and forever.
- Drush. Official documentation states very clearly: “Drush 9 no longer supports updating Drupal and leaves the work to composer”.
So, even though it seems you have choice, you actually haven’t )) You should start using Composer.
3. Update location
Most probably, you won’t be able to update Drupal 8 site with Composer directly on your hosting. At least on a shared hosting. So, your update location will almost always be your local machine. Which means you need to back up your production site and then deploy it on your dev machine.
BTW, I suppose you already have PHP environment set up on your local machine, as you probably installed and configured your Drupal site at some point. But in rare cases (i.e. when you just received a request to maintain someone’s Drupal-based website) you may not have it ready. In this case you should first install WAMP server (Windows Users). There are many WAMP-like servers, they do pretty much the same thing - installing PHP, Apache, MySql, phpMyAdmin and some other tools.
Once your local environment is ready and your live site’s backup resorted on it, you can move on to the next chapter.
Official documentation makes it look easy to update your Drupal 8 site with Composer. Just don’t forget to back up your website and fire “composer update drupal/core --with-dependencies”. Done.
Wait. What? If I’m a newbie, were I’m gonna do that? Like in CMD? Let’s try... “’composer’ is not recognized as an internal or external command, operable program or batch file”. Doesn’t seam like a message of a successful Drupal update.
Actually, documentation forgot to mention one small thing. Composer is an application and has to be installed first. Installed how? There are multiple ways, that you can find at Composer’s official site: https://getcomposer.org.
Personally, I have installed Composer via Windows Installer. Just one-click job.
In order to check if you have successfully installed Composer, open Command Prompt (CMD) and type “composer -V”. This should print Composer’s version. If you got it, you are good to go to update your Drupal 8 site.
5. Drupal 8 website update with Composer
First of all, you need to open Command Prompt (CMD) and navigate to the directory, where your Drupal site is deployed (i.e. "c:\wamp64\www\drupalwebsite").
Now, let’s start with the command provided by Drupal documentation: “composer update drupal/core --with-dependencies”. This command means: let’s use Composer to update Drupal Core module and all its dependencies of the website in the current location (we reached it in the previous paragraph).
If you have used the above command and everything went well, congratulations! But, in case you weren’t lucky and got errors/warnings, please move to the next chapter.
6. Common problems that occur while updating Drupal 8 website with Composer
Nothing to install or update
Weird, because I actually have something to update! Well, it’s not like Composer is not willing to update your site, it simply doesn’t know that it is required. In order to find out what Composer “thinks” is required and what is not, you should open composer.json file in the root directory of your Drupal 8 installation. This is a configuration file that tells Composer what your site requires. And one of the first few sections should look like:
Section “require” tells Composer what is required to install. Section “replace” is written by Composer once it replaces module’s current version with the new version during update process. So, if you don’t have "drupal/core": "^X.X" in “require” section, Composer simply doesn’t know that the update is required.
Eventually, the solution to “Nothing to install or update” problem is usually to:
- Open composer.json file in the root directory of your Drupal 8 installation
- Add "drupal/core": "^X.X" to the “require” section (replacing X.X with the actual version)
- Remove “replace” section completely
- Save composer.json changes
- Run “composer update drupal/core --with-dependencies” again
Your requirements could not be resolved to an installable set of packages
Here, you can have many variations, the most common:
- Can only install one of: ModuleA[X.X.X, Y.Y.Y]
If you review “Dependencies” section of this post once again, you can see that a particular version of ModuleA may require a specific version of ModuleB. These requirements are listed in a file called composer.lock, which can be found next to composer.json in the root directory of your Drupal 8 installation. In this file, modules “lock” the versions of their dependencies ensuring a dependency update won’t break them.
In case multiple modules depend on the same module, your composer.lock may have something like: ModuleA and ModuleB depend on ModuleC. ModuleA depends on ModuleC version 1.0 and ModuleB depends on ModuleC version 2.0. In this scenario Composer cannot really do anything, as if it will install ModuleC version 1.0, then ModuleB will stop functioning and if it will install ModuleC version 2.0, then ModuleA will stop functioning. Kind of a deadlock. In a such scenario Composer will give you a message: “Can only install one of: ModuleC[1.0, 2.0]”, informing you that two different versions are specified in the composer.lock, but only one version of ModuleC can be installed.
There’s no solution known to me that can easily solve this problem. You may need to wait until a newer version of ModuleA will be published, most probably aligned with ModuleC version 2.0. Alternatively, you can uninstall/replace either ModuleA or ModuleB, to solve the conflict.
- ModuleA X.X.X requires ModuleB Y.Y.Y -> no matching package found
This usually happens when your ModuleA requires the version of ModuleB that doesn’t satisfy minimum stability specified in your composer.lock. If you open composer.lock file, you should find “minimum-stability” line in the root of the file. It can be set to “stable”, “dev”, etc. So, if you have minimum stability set to “stable”, but ModuleB is available only in "dev"/"alpha"/etc. version, you’ll have “no matching package found”. You either need to change “minimum-stability” to a lower value (i.e. "dev") or wait till ModuleB will release a version with the satisfiable version (i.e. "stable").
BTW, default "minimum-stability" value is "stable". So, if this property is missing in your composer.lock file, it actually have "stable" value set by default.
The requested package ModuleA X.X.X is satisfiable by ModuleA [Y.Y.Y] but these conflict with your requirements or minimum-stability.
This can mean one of two things:
To fix the error, go through:
- “minimum-stability” flag in your composer.lock / composer.json is set to higher version than the available version of the required package. For example, you have requested a package with version ~1.5. Available package of this module has version 1.6.x-dev. Your “minimum-stability” flag says “stable” (or not set, which defaults to “stable”). In this case available, “dev” version of the module cannot be installed due to the minimum stability set to “stable”.
- In one or more of your composer.lock / composer.json files you have got a module listed with a lower version than required. For example, in core/composer.json you have "symfony/yaml": "~3.2.8", but in your root/composer.lock you have "symfony/yaml": "~3.4.0" in “require” section of drupl/core. In this case, composer will try to install “symfony/yaml” with version ~3.4.0, but then it will see that in core/composer.json a lower version is requested (~3.2.8) and will yield an error.
- root/composer.json (“require” section should have correct version)
- root/composer.lock (“require” section of “drupal/core” should have the same correct version)
- core/composer.json (“require” section should have the same correct version)
- check if version of the requested packaged conflicts with your “minimum-stability” configuration in composer.lock / composer.json files
7. I’m desperate, nothing works!
OMG, if you reached this section, nothing worked. Ok, here are some approaches that you can take at your own risk. Don’t forget to back up!
- Ensure composer.json has "drupal/core": "^X.X" in the “require” section. Replace X.X with the required Drupal 8 version
- If you are aware of some mandatory dependencies (i.e. Drush), list them in “require” section too
- Delete "replace" section from composer.json
- Delete “vendor” and “core” directories and “composer.lock” file
- Run Composer update command: “composer update drupal/core --with-dependencies”
- If all good, run update.php and clear caches
You can try to run just “composer update” command.