Content

Introductory

On December 2019, 4, Drupal released its currently latest base system, 8.8.0. It has been mentioned before, how to easily upgrade the Drupal base system, but more has changed in this release, so you have to go a little deeper. Since the update is a bit more macerated than the basic patches with minor patches, I thought it was worth a Mass here. So in this tutorial we will look at how to upgrade our Drupal base system from 8.7.10 to 8.8.0.

Prerequisites

Drupal offers several methods to upgrade the base system, including here Compose we will do the upgrade.

Here I will not go into as much detail as the details of each of the necessary basic conditions, because these are the previous guide I have already introduced them, so now I just list them. So, to successfully complete the upgrade, we need the following:

• Terminal, SSH hozzáférés
• Compose PHP package manager
• Git version management system
• Drush

Backup

Before making any updates, always back up the entire file structure of the website and the database. This will be discussed in more detail in another description.

Also, if we can, upgrade first in a test environment and then on our production page.

Download and unpack the update package

Download and unzip the Drupal 8.8.0 installation package to your / tmp directory:

cd /tmp
wget https://ftp.drupal.org/files/projects/drupal-8.8.0.tar.gz
tar -xzf drupal-8.8.0.tar.gz
cd drupal-8.8.0/

Manage file discrepancies

The earlier Drupal base system from the update description otherwise we now know exactly what the differences are in the new release, so we're focusing on comparing them. Drupal 8.8.0 release you can read more about it here.

composer.json

The composer.json file in the web root of our Drupal system describes what extra modules are built into the page. Not all modules can be installed via the web interface, but are installed using the composer PHP package manager. The composer.json file stores, among other things, the names of the modules you add, so that you can update which packages you need to download again.

First, take a look at the composer.json factory file for the previous version of Drupal (8.7.10):

{
    "name": "drupal/drupal",
    "description": "Drupal is an open source content management platform powering millions of websites and applications.",
    "type": "project",
    "license": "GPL-2.0-or-later",
    "require": {
        "composer/installers": "^1.0.24",
        "wikimedia/composer-merge-plugin": "^1.4"
    },
    "replace": {
        "drupal/core": "^8.7"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "config": {
        "preferred-install": "dist",
        "autoloader-suffix": "Drupal8"
    },
    "extra": {
        "_readme": [
            "By default Drupal loads the autoloader from ./vendor/autoload.php.",
            "To change the autoloader you can edit ./autoload.php.",
            "This file specifies the packages.drupal.org repository.",
            "You can read more about this composer repository at:",
            "https://www.drupal.org/node/2718229"
        ],
        "merge-plugin": {
            "include": [
                "core/composer.json"
            ],
            "recurse": true,
            "replace": false,
            "merge-extra": false
        },
        "installer-paths": {
            "core": ["type:drupal-core"],
            "modules/contrib/{$name}": ["type:drupal-module"],
            "profiles/contrib/{$name}": ["type:drupal-profile"],
            "themes/contrib/{$name}": ["type:drupal-theme"],
            "drush/contrib/{$name}": ["type:drupal-drush"],
            "modules/custom/{$name}": ["type:drupal-custom-module"],
            "themes/custom/{$name}": ["type:drupal-custom-theme"]
        }
    },
    "autoload": {
        "psr-4": {
            "Drupal\\Core\\Composer\\": "core/lib/Drupal/Core/Composer"
        }
    },
    "scripts": {
        "pre-autoload-dump": "Drupal\\Core\\Composer\\Composer::preAutoloadDump",
        "post-autoload-dump": "Drupal\\Core\\Composer\\Composer::ensureHtaccess",
        "post-package-install": "Drupal\\Core\\Composer\\Composer::vendorTestCodeCleanup",
        "post-package-update": "Drupal\\Core\\Composer\\Composer::vendorTestCodeCleanup",
        "drupal-phpunit-upgrade-check": "Drupal\\Core\\Composer\\Composer::upgradePHPUnit",
        "drupal-phpunit-upgrade": "@composer update phpunit/phpunit phpspec/prophecy symfony/yaml --with-dependencies --no-progress",
        "phpcs": "phpcs --standard=core/phpcs.xml.dist --runtime-set installed_paths $($COMPOSER_BINARY config vendor-dir)/drupal/coder/coder_sniffer --",
        "phpcbf": "phpcbf --standard=core/phpcs.xml.dist --runtime-set installed_paths $($COMPOSER_BINARY config vendor-dir)/drupal/coder/coder_sniffer --"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        }
    ]
}

Then look at the newer release (8.8.0):

{
    "name": "drupal/legacy-project",
    "description": "Project template for Drupal 8 projects with composer following drupal/drupal layout",
    "type": "project",
    "license": "GPL-2.0-or-later",
    "homepage": "https://www.drupal.org/project/drupal",
    "support": {
        "docs": "https://www.drupal.org/docs/user_guide/en/index.html",
        "chat": "https://www.drupal.org/node/314178"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        }
    ],
    "require": {
        "composer/installers": "^1.2",
        "drupal/core-composer-scaffold": "^8.8",
        "drupal/core-project-message": "^8.8",
        "drupal/core-recommended": "^8.8",
        "drupal/core-vendor-hardening": "^8.8"
    },
    "require-dev": {
    },
    "conflict": {
        "drupal/drupal": "*"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "config": {
        "sort-packages": true
    },
    "extra": {
        "drupal-scaffold": {
            "locations": {
                "web-root": "./"
            }
        },
        "installer-paths": {
            "core": ["type:drupal-core"],
            "libraries/{$name}": ["type:drupal-library"],
            "modules/contrib/{$name}": ["type:drupal-module"],
            "profiles/contrib/{$name}": ["type:drupal-profile"],
            "themes/contrib/{$name}": ["type:drupal-theme"],
            "drush/Commands/contrib/{$name}": ["type:drupal-drush"],
            "modules/custom/{$name}": ["type:drupal-custom-module"],
            "themes/custom/{$name}": ["type:drupal-custom-theme"]
        },
        "drupal-core-project-message": {
            "include-keys": ["homepage", "support"],
            "post-create-project-cmd-message": [
                "<bg=blue;fg=white>                                                         </>",
                "<bg=blue;fg=white>  Congratulations, you’ve installed the Drupal codebase  </>",
                "<bg=blue;fg=white>  from the drupal/legacy-project template!               </>",
                "<bg=blue;fg=white>                                                         </>",
                "",
                "<bg=yellow;fg=black>Next steps</>:",

                "  * Install the site: https://www.drupal.org/docs/8/install",
                "  * Read the user guide: https://www.drupal.org/docs/user_guide/en/index.html",
                "  * Get support: https://www.drupal.org/support",
                "  * Get involved with the Drupal community:",
                "      https://www.drupal.org/getting-involved",
                "  * Remove the plugin that prints this message:",
                "      composer remove drupal/core-project-message"
            ]
        }
    }
}

At first glance, you can see that there is quite a difference between them.

If you have not installed anything with the Composer PHP package manager, then you have nothing to do with it, you just have to overwrite it with the file operations. In the meantime, let's not do anything with it.

However, if you have already installed modules with composer, its contents have changed. In this case, you have to comb the changes. This means that whatever changes have been made to our composer.json file from the original, you will need to put exactly the same changes in the correct places in the new one.

You can use the linux diff command also, but I think it is more convenient and clearer to open the original composer.json file and our own in an editor and then compare the differences line by line, which we write to a temporary file, just so that the changes are separate.

With my own specific example, I have included these in the composer.json file in the last approx. 2 years:

    "require": {
    	...,
    	..., 		(fontos, hogy vesszővel végződjön minden olyan sor, ami után még van további sor!)
    	A hozzáadott rész:


        "drush/drush": "^9.2",
		"jackmoore/colorbox": "1.6.4",
        "drupal/geshifilter": "^1.2",
        "drupal/amptheme": "^1.0",
        "drupal/superfish": "^1.2",
        "drupal/amp": "^2.1",
        "masterminds/html5": "2.3.1"


[...]

    "extra": {
    	...,
        "installer-paths": {
			...,
			...,
			a hozzáadott rész (ez már benne van a Drupal 8.8 gyári composer fájljában is!):
        
			"libraries/{$name}": ["type:drupal-library"]

[...]

    "repositories": [
        {
        	...
        },				(vesszővel zárul!)
        
        És a hozzáadott rész:
        
		{
			"type": "package",
			"package": {
				"name": "jackmoore/colorbox",
				"version": "1.6.4",
				"type": "drupal-library",
				"dist": {
				  "url": "https://github.com/jackmoore/colorbox/archive/1.6.4.zip",
				  "type": "zip"
				}
			}
		}

So here are 3 parts: require, Extra / installer-paths and the repositories.

I commented in the sections above just to make the insertion process easier to understand.

Then open the composer.json file in the new Drupal release (8.8.0) and place these changes in the appropriate places. Accordingly, the new composer.json file looks like this to me:

{
    "name": "drupal/legacy-project",
    "description": "Project template for Drupal 8 projects with composer following drupal/drupal layout",
    "type": "project",
    "license": "GPL-2.0-or-later",
    "homepage": "https://www.drupal.org/project/drupal",
    "support": {
        "docs": "https://www.drupal.org/docs/user_guide/en/index.html",
        "chat": "https://www.drupal.org/node/314178"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
		{
			"type": "package",
			"package": {
				"name": "jackmoore/colorbox",
				"version": "1.6.4",
				"type": "drupal-library",
				"dist": {
				  "url": "https://github.com/jackmoore/colorbox/archive/1.6.4.zip",
				  "type": "zip"
				}
			}
		}
    ],
    "require": {
        "composer/installers": "^1.2",
        "drupal/core-composer-scaffold": "^8.8",
        "drupal/core-project-message": "^8.8",
        "drupal/core-recommended": "^8.8",
        "drupal/core-vendor-hardening": "^8.8",
        "drush/drush": "^9.2",
		"jackmoore/colorbox": "1.6.4",
        "drupal/geshifilter": "^1.2",
        "drupal/amptheme": "^1.0",
        "drupal/superfish": "^1.2",
        "drupal/amp": "^2.1",
        "masterminds/html5": "2.3.1"
    },
    "require-dev": {
    },
    "conflict": {
        "drupal/drupal": "*"
    },
    "minimum-stability": "dev",
    "prefer-stable": true,
    "config": {
        "sort-packages": true
    },
    "extra": {
        "drupal-scaffold": {
            "locations": {
                "web-root": "./"
            }
        },
        "installer-paths": {
            "core": ["type:drupal-core"],
            "libraries/{$name}": ["type:drupal-library"],
            "modules/contrib/{$name}": ["type:drupal-module"],
            "profiles/contrib/{$name}": ["type:drupal-profile"],
            "themes/contrib/{$name}": ["type:drupal-theme"],
            "drush/Commands/contrib/{$name}": ["type:drupal-drush"],
            "modules/custom/{$name}": ["type:drupal-custom-module"],
            "themes/custom/{$name}": ["type:drupal-custom-theme"]
        },
        "drupal-core-project-message": {
            "include-keys": ["homepage", "support"],
            "post-create-project-cmd-message": [
                "<bg=blue;fg=white>                                                         </>",
                "<bg=blue;fg=white>  Congratulations, you’ve installed the Drupal codebase  </>",
                "<bg=blue;fg=white>  from the drupal/legacy-project template!               </>",
                "<bg=blue;fg=white>                                                         </>",
                "",
                "<bg=yellow;fg=black>Next steps</>:",

                "  * Install the site: https://www.drupal.org/docs/8/install",
                "  * Read the user guide: https://www.drupal.org/docs/user_guide/en/index.html",
                "  * Get support: https://www.drupal.org/support",
                "  * Get involved with the Drupal community:",
                "      https://www.drupal.org/getting-involved",
                "  * Remove the plugin that prints this message:",
                "      composer remove drupal/core-project-message"
            ]
        }
    }
}

We need to improve on this later, now I intentionally left a version number causing the compatibility error in it so that we can fix any errors. For now, just save this composer.json file to a separate location. If, on the other hand, you are working in a test environment, you can already save it in its place.

.htaccess

The .htaccess file also changed, but here's just a small one. Therefore, if we already have our own additions, it is easier to make this small change in ours.

A diff command to get the difference between the .htaccess files in the two Drupal releases. I have both Drupal installation packages downloaded to the tmp directory of my test environment, so I can conveniently list the differences with the following command:

diff drupal-8.7.10/.htaccess drupal-8.8.0/.htaccess

And the output clearly shows that there is only one line difference:

Copy the second copy - which comes from the newer file - and paste it into your .htaccess file, overwriting the original line. We can do this on the sharp side as well, it will not cause an error.

settings.php

And finally, we need to do a few more things in the settings.php file. Settings.php is in the Drupal web root sites / default subdirectory, which is read-only by default. To access it, you must first add write access to the file. To do this, stand in the web root of our Drupal instance and perform the following commands:

cd sites/default/
chmod u+w settings.php

Then open it for editing:

nano settings.php

And look for the following section:

$config_directories['sync'] = 'beállított útvonalunk';

And change it to

$settings['config_sync_directory'] = 'beállított útvonalunk';

And then look for this:

$config['system.file']['path']['temporary'] = 'temp könyvtárunk útvonala';

And replace it with:

$settings['file_temp_path'] = 'temp könyvtárunk útvonala';

So in these, the array variables and their indexes are replaced, retaining our value in it. Source.

Finally, save the file and remove the write permission:

chmod u-w settings.php

Upgrading the base system

If we are in the process of modifying the above files, we can start the upgrade.

Maintenance mode

First, set up the page maintenance mode, as we did in the previous description.

File structure operations

The next step is to overwrite the originals with the modified files if the changes were not made at the destination.

Then enter the Drupal web root and delete the core / and vendor / subdirectories. These libraries include the Drupal base system and third-party modules. Our own settings are not lost, they are not stored in these directories. 

So go to the web root of our Drupal system and issue the delete command:

rm -rf core/ vendor/

Then delete the composer.lock file, which will be rebuilt by the following update:

rm composer.lock

As well as give writing rights a sites / default directory. By default, the system removes write access from this directory for security reasons, but you want to delete the composer from this directory while running composer. default.services.yml file to overwrite the new one. However, you cannot delete it without permission, so the update will stop with an error message. So to avoid this, give this directory the write root by running a command at the web root:

chmod +w sites/default/

Update with the composer command

To remain in the web root, run the following command:

composer update --with-dependencies

Unlike the previous update description from this part here we are not copying core and vendor libraries from the new install package (of course it could be), but we are running a complete upgrade that downloads all necessary packages and rebuilds our core and vendor libraries with the appropriate version components.

If we are lucky, everything runs smoothly. In this case, skip to the next section.

Troubleshoot compatibility issues

If we are not lucky, the composer command will stop with some error message. At this point, we have to improvise, but as I mentioned above, I intentionally left an incorrect version number in my composer.json example so that I can now show you how to fix this kind of bug.

So I got the update interrupted with the following error message:

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - drupal/core-recommended 8.9.x-dev requires masterminds/html5 2.3.0 -> satisfiable by masterminds/html5[2.3.0] but these conflict with your requirements or minimum-stability.
    - drupal/core-recommended 8.8.x-dev requires masterminds/html5 2.3.0 -> satisfiable by masterminds/html5[2.3.0] but these conflict with your requirements or minimum-stability.
    - drupal/core-recommended 8.8.0-rc1 requires masterminds/html5 2.3.0 -> satisfiable by masterminds/html5[2.3.0] but these conflict with your requirements or minimum-stability.
    - drupal/core-recommended 8.8.0-beta1 requires masterminds/html5 2.3.0 -> satisfiable by masterminds/html5[2.3.0] but these conflict with your requirements or minimum-stability.
    - drupal/core-recommended 8.8.0-alpha1 requires masterminds/html5 2.3.0 -> satisfiable by masterminds/html5[2.3.0] but these conflict with your requirements or minimum-stability.
    - drupal/core-recommended 8.8.0 requires masterminds/html5 2.3.0 -> satisfiable by masterminds/html5[2.3.0] but these conflict with your requirements or minimum-stability.
    - Installation request for drupal/core-recommended ^8.8 -> satisfiable by drupal/core-recommended[8.8.0, 8.8.0-alpha1, 8.8.0-beta1, 8.8.0-rc1, 8.8.x-dev, 8.9.x-dev].

This occurs when an incorrect version is specified in the "require" section of the composer.json file for the current base system.

Although I copied exactly the changed parts from my old composer file, this version of this component does not match this new base system.

The solution

Open our composer.json file for editing and change the appropriate section to the version number specified in the error message. So I had to edit the following line:

        "masterminds/html5": "2.3.1"

for:

        "masterminds/html5": "2.3.0"

So somehow the newer basic system is more like a lower version mastermind / html5 I needed a package.

Please fix the version number in the composer.json file according to our error message and then run the composer command again:

composer update --with-dependencies

The update is running normally

If all goes well, the upgrade will start and the packages will be downloaded:

It takes a long time to load packages, and then comes with suggestions on what packages to use, etc. Whether we deal with them or not, they are not a mistake. Finally, it builds the composer.lock file:

Refresh database using the drush command

Once all is well done, you may want to upgrade your database. You can also do this by running update.php on the web, but I'd recommend drush, because here's where you get detailed information about the problem. In contrast, the web update is interrupted by one Internal Server Error with an error message that we don’t know much about unless we start beetling the PHP error log files.

If you don't already have the drush French, a see previous description, how to install it.

So run the drush database update with the command from the Drupal web root:

vendor/bin/drush updatedb

This is a list of possible updates, of course press Enter:

There were quite a few things the system had to upgrade in this 8.8.0 release, but that's why I made this description because there were more changes here than with an average base system upgrade.

The command runs the necessary updates and then we get our shell back. In these cases, I still read the? the value of the environment variable to make sure there was nothing wrong with it:

echo $?

Delete Cahce and query system status

Then clear the cache:

vendor/bin/drush cr

Finally, we will check the status of our system:

vendor/bin/drush status

If all goes well, we get something like this:

Conclusion

This is exactly how I updated this Drupal-based page, which was a bit fluffier than a smooth subversion upgrade, but with a little patience it can be done easily.

The complexity of the upgrade depends on how many and which modules you use with Composer installed outside the base system, so this scenario may be different for everyone. However, the basic thread is the same in all cases, so if we move on from it, we can make fewer mistakes.