Acquia CMS

Upgrading Drupal Starter Kits and its dependencies

The upgrade of Drupal Starter Kits from 1.x to 2.x changes it from a profile to a module. The Drupal Starter Kits 2.x module retains all the required dependencies previously available in the Drupal Starter Kits 1.x profile. When you upgrade to Drupal Starter Kits 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 Drupal Starter Kits:

  • 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 Drupal Starter Kits to 2.x, complete the following tasks:

Upgrading Drupal Starter Kits 1.x from its current version to the latest version

Use the following steps to upgrade Drupal Starter Kits 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 Drupal Starter Kits 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 Drupal Starter Kits 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 Drupal Starter Kits 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 Drupal Starter Kits 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 Drupal Starter Kits 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 Drupal Starter Kits 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 Drupal Starter Kits.

  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 Drupal Starter Kits 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 Drupal Starter Kits 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.

 

Did not find what you were looking for?

If this content did not answer your questions, try searching or contacting our support team for further assistance.

Acquia Help

Filter by product:

Acquia CMS common questions