Marilyn Perry On Major Drupal Upgrades, Including Drupal 8 to Drupal 9 and Drupal 9 to Drupal 10
Upgrading Drupal From Drupal 8 to Drupal 9 and From Drupal 9 to Drupal 10
Drupal
drupal.org
Major Drupal Upgrades
Major drupal upgrades, from Drupal 8 to Drupal 9 and from Drupal 9 to Drupal 10, especially upgrades from Drupal 9 to Drupal 10, often require Drupal specific knowledge, expertise, and experience. However, even major Drupal upgrades, such as upgrades all the way from Drupal 8 to Drupal 10 can be accomplished in a matter of hours with the requisite tools and adequate information about Drupal core code changes and Drupal API deprecations. With the information below, it should be possible, often within a matter of hours, to reliably upgrade Drupal projects for compatibility with the latest Drupal 10 core code releases.
One of the prerequisites to successfully upgrading a Drupal project is an appropriate software operating environment as well as various software utilities required during the Drupal project upgrade process. The sections of the article below provide detailed information about what tools are required, and about how to create them if necessary.
Operating Environment Prerequisites
In order to complete a major drupal code upgrade, an operating environment is needed that supports the ability to change its PHP version during each phase of the Drupal core release upgrade process. There at least three difference system types available in which it is possible to change the PHP version it is utilizing, including:
- drupal specific Docker containers
- local machine XAMPP multiple versions
- Alma Linux server with WHM/cPanel
The Docker container approach and the XAMPP approach each involve setting up multiple environments. Ample information about how to install and setup multiple docker containers, each with a differing PHP version install within it, is available on the web. Similarly it is possible to install multiple versions of XAMPP on a single computer running Windows (10/11), each with a specific version of each LAMP stack component, particularly its PHP version. The XAMPP downloads page on sourceforge contains the list of the XAMPP versions available for download. It contains versions of XAMPP that include a range of PHP versions all the way from PHP 7.4.x to 8.2.x. With the XAMPP approach, careful installation, with each XAMPP installation its in own directory is essential. It is also important to run only one and one only copy of XAMPP at a time on a single Windows (10/11). For simplicity, running XAMPP with the standard HTTP / HTTPS ports 80 and 443 enabled is acceptable.
There are several sources available for docker containers setup for Drupal project development. One set docker containers tuned for Drupal is the docker4drupal project on github. The open-source docker4drupal project contains numerous drupal specific docker container releases, each set up with specific PHP and MariaDB/MySQL version configurations. Several other Drupal oriented docker container systems have been documented at the drupal.org page entitled Docker-based development environments for macOS, Linux, and Windows.
The third approach is a server running WHM/cPanel with multiple PHP versions installed within WHM that are then available within each cPanel account's MultiPHP Manager. The WHM/cPanel MultiPHP Manager provides a GUI interface in which it is possible to select the desired PHP version for each web domain running on that WHM/cPanel enabled server. With WHM/cPanel MultiPHP Manager, changing the PHP version configured for a given web domain takes just moments to complete. The major Drupal upgrades described in these notes were performed on a VPS server running Alma Linux with WHM/cPanel installed on it.
Drupal Upgrade Support Tools
composer package manager
drupal code and database backup tools;
Drupal Application Programming Interface (API) Deprecation Modification
Drupal evolution from functional programming APIs to object oriented Drupal service programming interfaces.
Drupal Project Components That Likely Require The Most Attention
Drupal themes, especially custom Drupal themes, and custom drupal modules, are some of the mostly likely Drupal extension components whose PHP code will likely require the most compatibility upgrade attention. Within a custom Drupal theme, essential files to check are the theme's .theme file and theme-settings.php file for PHP code that uses deprecated Drupal PHP application programming interfaces (APIs). The two tables below, sourced from the drupal.org website, provide examples of deprecated Drupal API usage often found in custom Drupal themes that will require modification for Drupal 10 compatibility. Using web searches in the form [drupal "drupal_get_path(" deprecated] and [drupal file_create_url(" deprecated] provided results in which the first entries were drupal.org web pages that contain information about these deprecated Drupal APIs and how to modify their usage for Drupal 10 compatibility.
| Before | After |
|---|---|
drupal_get_path('module', 'node') | \Drupal::service('extension.list.module')->getPath('node') |
drupal_get_path('theme', 'seven') | \Drupal::service('extension.list.theme')->getPath('seven') |
drupal_get_path('profile', 'standard') | \Drupal::service('extension.list.profile')->getPath('standard') |
| Before | After |
|---|---|
file_create_url($uri) | \Drupal::service('file_url_generator')->generateAbsoluteString($uri) |
file_url_transform_relative($file_url) | \Drupal::service('file_url_generator')->transformRelative($file_url) |
file_url_transform_relative(file_create_url($uri) | \Drupal::service('file_url_generator')->generateString($uri) |
Drupal\Core\Url::fromUri(file_create_url($uri)) | \Drupal::service('file_url_generator')->generate($uri) |
Major Drupal Upgrading Process Sequence
First backup the drupal project code and its database. Then update the drupal project's code within its current drupal core version as much as possible, producing a fully work Drupal project within the context of its original Drupal system core version.
linux bash code snippet to create a .zip archive of the drupal project from the project's root directory
# assemble the drupal code .zip backup file name
# example - www.examplewebsitename.com.backup.code.2023.12.27.01.15.00.zip
szDateAndTime=$(date +%Y.%m.%d.%H.%M.%S)
szWebSiteBaseName="www.examplewebsitename.com"
szCodeArchiveFileName=$szWebSiteBaseName
szCodeArchiveFileName+=".backup.code."
szCodeArchiveFileName+=$szDateAndTime
szCodeArchiveFileName+=".zip"
# assemble the drupal code .zip backup file name
# the linux zip utlity must be executed in the directory to be archived in order for it to create correct relative internal paths
# the [ -x $szWebSiteBaseName*.zip ] construct means exclude any previous .zip archives that might not have been moved from the directory
zip -q -r $szCodeArchiveFileName . -i ".*" "*" -x "$szWebSiteBaseName*.zip"
linux bash code snippet to create a .sql.gz archive of the drupal project database
# assemble the file name for the SQL database archive
# example - www.examplewebsitename.com.backup.data.2023.12.27.01.15.00.sql.gz
szDateAndTime=$(date +%Y.%m.%d.%H.%M.%S)
szWebSiteBaseName="www.examplewebsitename.com"
szCodeArchiveFileName=$szWebSiteBaseName
szSQLArchiveFileName+=".backup.data."
szSQLArchiveFileName+=$szDateAndTime
szSQLArchiveFileName+=".sql.gz"
# create the SQL database archive - replacing the example user name and passwords with actual values
szSQLDatabaseName="example_sql_drupal_database_name"
szDefaultSQLUserName="example_sql_database_user_name"
szDefaultSQLPassword="DZ0Dnx!!Z7X3C^^MD45XHobCh" # example password
mysqldump -u $szSQLUserName --password=$szSQLPassword $szSQLDatabaseName | gzip > ./$szSQLArchiveFileName
