Acquia CMS

Upgrading Acquia CMS and its dependencies

The upgrade of Acquia CMS from 1.x to 2.x changes it from a profile to a module. The Acquia CMS 2.x module retains all the required dependencies previously available in the Acquia CMS 1.x profile. When you upgrade to Acquia CMS 2.x, you can use the latest features of the composable architecture.

Important

The instructions on this page are tested with the following versions of Drupal core and Acquia CMS:

  • drupal/core:9.3.17
  • acquia/acquia_cms:1.4.11

If you use any other versions than the listed ones, instructions might differ.

Prerequisites

  • Update your PHP version to 8.1 with the following command:

    composer config platform.php 8.1
  • Take a backup of database and configuration of your site.
  • Complete your site setup as mentioned in Studio configuration management strategy.

Upgrade checklist

To upgrade Acquia CMS to 2.x, complete the following tasks:

S. No.Task
1Upgrading Acquia CMS 1.x from its current version to the latest version 
2Upgrading Acquia CMS from 1.x to 2.x
3Upgrading Drupal core to the latest version of 10.x

Upgrading Acquia CMS 1.x from its current version to the latest version

Use the following steps to upgrade Acquia CMS 1.x from its current version to the latest version:

  1. Update Drupal core to the latest version 9.5.11 with the following command:

    drupal/core:~9.4.0 acquia/cohesion:~6.9.0 drupal/core-recommended:~9.4.0

  2. Update Acquia CMS to its compatible version 1.5.8 with the following command:

    composer update acquia/acquia_cms -W with drupal/acquia_cms_common:~1.9.0

  3. Add Page Manager and Panels modules to the codebase with the following command:

    composer require drupal/panels drupal/page_manager

    You can remove them from the codebase later, if required. With Drupal core 9.x, the Acquia CMS Common module 1.9.x uses the Moderation Dashboard module 2.x, which removes the Page Manager and Panels modules from the codebase.

  4. Add the Webform module to Composer dependencies with the following command:

    composer require 'drupal/webform:~6.0.0'

    You can remove it from the codebase later, if required. The latest version of the Acquia CMS Starter module removes the Webform module from Composer dependencies.

  5. Update your database with the following command:

    ./vendor/bin/drush updb -y

  6. (Optional) On running any Drush command, if you get the Error: Class "Drupal\Driver\Database\mysql\Connection" not found error, update database specification by replacing the line 'namespace' => 'Drupal\\mysql\\Driver\\Database\\mysql' in your settings.php file:

    $databases['default']['default'] = array (
  'database' => 'drupal',
  'username' => 'drupal',
  'password' => 'drupal',
  'namespace' => 'Drupal\\mysql\\Driver\\Database\\mysql',
  'driver' => 'mysql',
);

  7. (Optional) If you use Facet accordion custom style on the site, update its configuration:

    1. Edit Facet accordion from: /admin/cohesion/styles/cohesion_custom_styles.

    2. Update the .collapsiblock element to .collapsiblockTitle :

    3. Change anchor to button under the .collapsiblockTitle (child) element:

    4. Change anchor to button under the .facet-item (child) element:

    5. Add custom CSS property to button element under the .collapsiblockTitle (child) “CSS property: width” & “CSS value: 100%”:

    6. Click Save and Continue to save changes to the component.
    7. Export your Site Studio configuration to retain the preceding changes in your configurations.

  8. Uninstall the Acquia Telemetry module as its functionality is available in Acquia Connector from the version 4.0.0-beta4.

    ./vendor/bin/drush pmu acquia_telemetry
./vendor/bin/drush cex

  9. Commit all changes, deploy them to your development environment, and run the following commands:

    ./vendor/bin/drush updb -y
./vendor/bin/drush cim -y

  10. Update Drupal core to 9.5.11 along with Acquia CMS and its dependencies:

    composer update "drupal/core-*" acquia/acquia_cms  -W
  11. (Optional) If you use Claro as the admin theme:

    1. Install the Site Studio Claro sub-module. The Acquia CMS Site Studio module 1.6.0 uses Acquia Site Studio 7.4.2, which includes the Site Studio Claro sub-module. This sub-module fixes template and style issues for media library in Page Builder. If you do not install this sub-module, you might get the following error while updating your database:

    2. Enable the Acquia Claro module with the following command:

      ./vendor/bin/drush en sitestudio_claro

  12. Clear cache and run the database update and configuration export commands.

    ./vendor/bin/drush cr
./vendor/bin/drush updb -y
./vendor/bin/drush cex

  13. Commit all the changes, deploy them to your development environment, and run the following commands:

    ./vendor/bin/drush updb -y
./vendor/bin/drush cim -y
  14. Verify that your development site works as expected.

Use the following steps to upgrade Acquia CMS from 1.x to 2.x by using the profile switch command. This command also helps you to add the modules that were deleted from the most recent version but are still necessary for Acquia CMS.

  1. If you use BLT, check your install profile with the following commands:

    ./vendor/bin/drush status --fields=install-profile
Install profile : acquia_cms
    1. Edit blt/blt.yml.
    2. Change the profile key to minimal.

  2. Run the profile switcher command to switch the profile from acquia_cms to minimal.

    ./vendor/bin/drush acms:switch

The site's install profile will be switched from acquia_cms to minimal.

Do you want to continue? (yes/no) [ yes ]:

> yes

Profile switched from acquia_cms to minimal.
  3. Verify the site and ensure that it works as expected.

  4. Export the configurations.

    You can observe the changes in the core.extension configuration parameter.

    ./vendor/bin/drush cex

[notice] Differences of the active config to the export directory:

+------------+---------------------+-----------+

| Collection | Config              | Operation |

+------------+---------------------+-----------+

|            | core.extension      | Update    |

|            | system.theme.global | Update    |

+------------+---------------------+-----------+

The .yml files in your export directory (../config/default) will be deleted and replaced with the active config. (yes/no) [yes]:

> 

[success] Configuration successfully exported to ../config/default.

  5. Commit all the changes, deploy them to your development environment, and run the following commands:

    ./vendor/bin/drush cr

./vendor/bin/drush cim --yes

./vendor/bin/drush updb --yes
  6. Verify that your development site works as expected.

  7. Upgrade Acquia CMS to 2.x with the following command:

    composer require -W acquia/acquia_cms:^2.0

  8. (Optional) Add the Google Analytics module to your project, if required.

    composer require -W drupal/google_analytics:^2.0

  9. Update your database.

    ./vendor/bin/drush updb -y

  10. Commit all changes, deploy them to your development environment, and run the following commands:

    ./vendor/bin/drush cr

./vendor/bin/drush cim --yes

./vendor/bin/drush updb --yes

  11. Verify that your development site works as expected.

    The Acquia CMS 2.x module keeps all the required dependencies previously available in the profile. The acquia_cms profile codebase does not exist in the docoot/profiles/contrib directory.

Use the following steps to update the text format to use CKEditor 5, remove the old CKEditor, and upgrade your Drupal core version to the latest version.

  1. Switch from CKEditor 4 to CKEditor 5.

    1. Install the CKEditor 5 module with the following command:

      ./vendor/bin/drush en ckeditor5

    2. Click Configuration > Content authoring > Text formats and editors.

      Alternatively, append /admin/config/content/formats to your application name.

    3. Update each text format, such as Filtered HTML and Full HTML, to use CKEditor 5.

      For more information, see Using the CKEditor5 text editor for the “Site Studio” text format.

    4. Uninstall any previous version of the CKEditor module.

      ./vendor/bin/drush pmu ckeditor

./vendor/bin/drush cex

    5. Commit all changes, deploy them to your development environment, and run the following commands:

      ./vendor/bin/drush cr

./vendor/bin/drush cim --yes

./vendor/bin/drush updb --yes
    6. Verify that the site in your development environment works as expected.
  2. Upgrade your Drupal core version.

    1. Remove incompatible and insignificant modules.

      composer remove drupal/upgrade_status

Composer remove acquia/http-hmac-php

    2. Add the HAL module to the codebase because it is removed from core 10.

      composer require 'drupal/hal:^2.0'  --no-update --no-install

    3. Add the latest version of core and contrib module.

      You can remove modules that are not used in the project. For example, Webform and Google Analytics.

      composer require "drupal/core-composer-scaffold:^10" "drupal/core-recommended:^10" drupal/webform:^6 drupal/google_analytics:^4 drush/drush:^12 --no-update --no-install

    4. Install the latest Drupal core and its required dependencies with the following command:

      composer update -W

    5. Perform post upgrade activities.

      ./vendor/bin/drush cr
./vendor/bin/drush updb -y

./vendor/bin/drush cex
./vendor/bin/drush coh:import

./vendor/bin/drush coh:rebuild

    6. Commit all the changes, deploy them to your development environment, and run the following commands:

      ./vendor/bin/drush cr

./vendor/bin/drush cim --yes

./vendor/bin/drush updb --yes
    7. Verify that the site in your development environment works as expected.