Upgrading TheMag Theme from Drupal 8 to 9

I've been using TheMAG theme on this site for over a year now. Minor upgrades has always been straightforward but this time it is a major upgrade from Drupal 8 to 9 which is a bit more involved so i decided it might be good to write an article on upgrading to Drupal 9 using this TheMAG theme distribution. If you are already using TheMAG theme and is planning on upgrading to Drupal 9, i hope you will find this helpful.

I have taken a different approach since following this guide 'Upgrading from Drupal 8 to Drupal 9 (or higher)' didn't work for me.

A little introduction about TheMAG theme:

TheMAG is a Drupal theme that lets you create a modern magazine website with ease. It is ideal for sites that want to rake in ad revenue or profit from content. This bestseller theme is perfect for blogging, journalism, or entertainment sites.

I ended up using this theme to save development time and it has a really nice layout builder which makes this theme very configurable and quick to whack up a layout on a per page basis or section of a site. It comes with pre-configured section of blocks for content but altering and adding your own in code is easy too.  

Before we begin

You must check the Drupal 9 requirements. It must meet the following requirements:

• PHP 7.3+
• Apache 2.4.7
• MySQL or Percona 5.7.8
• MariaDB 10.3.7+ (Note that this is a more recent release than the MySQL version)

If it does meet the server and database requirements (listed above), go ahead and download the latest version of TheMAG 4 theme. This is a paid professional theme on Themeforest.

As of writing this guide, the latest version of TheMAG theme is v4.1.1 released on 17 June 2002 (pinkdexo__themag_4.1.1).

If you have installed additional contrib modules that are not used in TheMAG theme, you must check to make sure the modules are all Drupal 9 compatible. Usually you will find a label under the module download page on drupal.org that says 'Requires Drupal: ^8.8.0 || ^9.0' then you know it's fine. Remember to check dev version if you don't see that label on a stable release. If modules are not yet ready, check the module queue to see if there are any patch file submitted to fix this. If you find a patch file you can include this in your composer.json to patch the module (more on this later). If there are none, you might want to hold off upgrading until the modules are ready or fix the compatibility issue yourself. 

All the custom and contrib modules used in TheMAG theme are all Drupal 9 ready. Therefore, if you have not installed any other modules other than the one used in TheMAG theme, you have nothing to worry about and can continue to the next step. 

Skills required: it is assumed that you know how to work with Composer manager and apply a Drupal patch file.

Note: Although theMAG comes with Commerce and option to include Thunder distribution, i never use any of these. In fact, Commerce is removed from my installation. So your upgrade will probably be very different or that this guide will not help you at all. 

Let's get started

Let's assume you have the recommended requirements and all the modules are Drupal 9 ready, then we begin the preparation for the upgrade. 

You may also want to use Upgrade Status module to help review each modules in your installation though i never use Upgrade Status for this guide.

First thing we want to do is make sure Drupal core and modules are all updated to latest version. For modules that are used in TheMAG theme, we can leave these alone for now. We will start with Drupal core. Run this command:

composer require 'drupal/core'

Next, update any of the additional modules you have added but leave the ones that are already part of TheMAG theme alone for now. To update module, visit the module page on drupal.org and check if they have been updated to be compatible with Drupal 9.

For example, to update Admin Toolbar, we check the page, it is marked: 

Requires Drupal: ^8.8.0 || ^9.0

This means it is both Drupal 8 and Drupal 9 ready. Go ahead and update the module, using this command:

composer require 'drupal/admin_toolbar'

 Note: if you don't append the version number at the end, it will fetch and download the latest stable version. 

If the module is not marked as 'Requires Drupal: ^8.8.0 || ^9.0', then check the dev version. To install/update to dev version:

composer require 'drupal/admin_toolbar:2.x-dev'

You may run into an issue where a module (stable or dev version) has not been updated to support Drupal 9 yet. You have 2 options: You can hold off upgrading until these modules have been updated or you can try and fix this issue yourself later. 

Go through all your additional modules and update them all to be Drupal 9 ready.

Note: I encountered many version conflicts with Drupal Console module and its dependencies. It was difficult to fix. Fortunately, i really didn't need this module so i removed it:

composer remove 'drupal/console'

I thought it was worth mentioning Drupal Console module because after multiple tempts to upgrade to Drupal 9 i just couldn't get through many version conflicts. It was only when Drupal Console module was removed, updates went smoothly without issues. Perhaps, upgrading Drupal Console may have resolved many of the issues i had experienced but at the end, i really didn't need the module anyway.  

Applying a patch

If you require to add a patch file, add it under the patch object in your composer.json, for example, there was a patch in the issue queue for Mobile Device Detection module (this is an additional module i added to TheMAG theme). This patch was to add Drupal 9 compatibility. To add a patch in composer, open your existing composer.json file. Inside the "patches" object add:

"patches": {
  "drupal/mobile_device_detection": {
     "3135771: Drupal 9 readiness": "https://www.drupal.org/files/issues/2020-05-12/3135771-2.patch"
   }
               }

Now run: 

composer update

It should remove your module and re-install it so it can include the patch as well. 

If for some reason, it's not applying the patch file, it might be that you are missing "cweagans/composer-patches". Install this:

composer require 'cweagans/composer-patches:^1.6'

Upgrading to Drupal 9

Login to your Themeforest account and download the latest version of TheMAG. The latest version at the time of writing this article is v4.1.1

Unzip the downloaded file and navigate to pinkdexo__themag_4.1.1/INSTALLATION/ and unzip themag-drupal-project.zip file. You should find a composer.json file in pinkdexo__themag_4.1.1/INSTALLATION/themag-drupal-project/ 

If you did not install any additional modules to your TheMag theme, you can just copy and overwrite your existing composer.json file with the one found in pinkdexo__themag_4.1.1/INSTALLATION/themag-drupal-project/composer.json

If you do have additional modules added which did not come with TheMAG theme, then open up both your existing composer.json and the one found in pinkdexo__themag_4.1.1/INSTALLATION/themag-drupal-project/ folder. Compare the 2 files and update your existing composer.json to match the modules' newer version. 

For example:

"composer/installers": "^1.7" change to "composer/installers": "^1.9"
"drupal/blazy": "^1.0@RC" change to "drupal/blazy": "^2.1"
and so on...

It is important to copy these lines to your existing composer.json file:

"drupal/core": "9.0.0 as 8.9.0",
"drupal/core-composer-scaffold": "^9",
"drupal/core-recommended": "^9",

These modules will help upgrade to Drupal 9.

If for some reason you have this in your existing composer.json file: 

    "require-dev": {
        "drupal/core-dev": "^8.8.0"
    }

You should remove it.

Open your existing composer.json file in your Drupal installation. Under the 'patches' object remove: 

"patches": {
  "drupal/core": {
    "3045171: Form blocks rendered inside layout builder break save": "https://www.drupal.org/files/issues/2020-02-04/layout-builder-save-issue-3045171-140.patch",
    "3062742: Drag-and-drop reordering doesn't work if the region content is nested in other elements": "https://www.drupal.org/files/issues/2019-11-21/3062742_4.patch"
  },
  "drupal/entity_browser": {
    "2858438: Provide inline entity form FieldWidgetDisplay": "https://www.drupal.org/files/issues/2019-07-04/2858438_17.patch"
  },
  "drupal/poll": {
    "2331515: Allow to show the poll question in the vote/result templates": "https://www.drupal.org/files/issues/2019-03-15/question-title-is-displayed-as-block-title-2923946-8.x-1.x-dev-7.patch"
  },
  "drupal/mailchimp": {
      "2936099: Notice: Undefined property: stdClass::$size in mailchimp_insert_drupal_form_tag()": "https://www.drupal.org/files/issues/2018-06-07/suppress-size-notice-2936099-6.patch"

Copy the patch arrays in pinkdexo__themag_4.1.1/INSTALLATION/themag-drupal-project/composer.json to your existing composer.json in your Drupal installation:

"drupal/libraries": {
  "3119010: Drupal 9 Deprecated Code Report": "https://www.drupal.org/files/issues/2020-05-26/3119010-14_0.patch". 
  },
"drupal/realname": {
    "3101961: Drupal 9 Deprecated Code Report": "https://www.drupal.org/files/issues/2020-06-04/realname.patch"
   },
 "drupal/inline_entity_form": {
   "3121071: Replace theme_inline_entity_form_entity_table() with twig template": "https://www.drupal.org/files/issues/2020-05-24/3121071-21.patch"
    },
"drupal/entity_browser": {
  "2858438: Provide inline entity form FieldWidgetDisplay": "https://www.drupal.org/files/issues/2019-07-04/2858438_17.patch"
  },
"drupal/poll": {
  "2331515: Allow to show the poll question in the vote/result templates": "https://www.drupal.org/files/issues/2019-03-15/question-title-is-displayed-as-block-title-2923946-8.x-1.x-dev-7.patch",
  "3151308: Render callbacks must implement TrustedCallbackInterface" : "https://www.drupal.org/files/issues/2020-06-12/3151308-2.patch"
  },
"drupal/mailchimp": {
  "3138909: Drupal 9 compatibility": "https://www.drupal.org/files/issues/2020-05-22/mailchimp-d9-compatibility-3138909-3.patch"
  }

Remember not to overwrite the patch arrays you have added for your additional modules added to TheMAG if you had any. 

Once all the above is done, run:

composer update

If you get a msg saying "The package has modified files:", just type 'y' (for yes)

Hopefully, it completed updating without issues at this point. I would run 'composer update' again just to be sure everything is fully updated.

Next, visit your website and run: /update.php 

You should get some error messages (as shown in image below). Don't worry, we'll fix all of them. 

Errors that needs to be fixed:

CONFIGURATION SYNC DIRECTORY

$settings['config_sync_directory'] is already in the settings.php file. You need to uncomment it and change it to:

$settings['config_sync_directory'] = '../config/sync';

Now go to your website and refresh your web browser. If fixed, the above error should disappear. 

Next, 

INCOMPATIBLE MODULES

These are modules that are used in TheMag theme. We need to copy the updated ones over to your Drupal installation.

Open up pinkdexo__themag_4.1.1/INSTALLATION/web/modules/custom/

You will find these custom modules:

• themag_commerce_field_group
• themag_default_content
• themag_demo
• themag_layouts

Copy all the modules and replace and overwrite these in your Drupal installation. Refresh your web browser and if fixed, the error should disappear.

INCOMPATIBLE THEMES

Next, we do the same for the theme files. 

Open up pinkdexo__themag_4.1.1/INSTALLATION/web/themes/custom/

Copy both 

• pinkdexo_admin 
• themag

to your Drupal installation and overwrite your older themes.

If you have created a subtheme, you need to add this line to your *.info.yml file:

core_version_requirement: ^8 || ^9

Refresh your web browser again. Now you should be able to complete the database update. 

Go ahead and click on 'apply pending updates' button.

Well done, you have upgraded TheMAG 4 theme to Drupal 9.

UPDATED ON 28 JULY 2020

TheMag v4.2.0 has been released. If you have been following this guide, the only thing you need to update is to copy and replace your custom modules and themes directories. This new version adds 2 regions to your theme (which are first and second top bar regions). It also now comes with 2 packages - Drupal 8.x and 9.x version.