Acquia CMS

Using the Drupal Recommended Settings plugin


Drupal Recommended Settings (DRS) is a Composer-based plugin that minimizes the development effort by automating the changes required to run a Drupal site in Acquia Cloud, Cloud IDE, or your local machine.

It adds the following changes by updating the setting.php file:

  • The necessary database credentials.
  • Configuration sync directory path.
  • Public and private file directory path.
  • Acquia Site Studio sync directory path.

Configuring multisite

DRS supports multisite capability out-of-the box. To configure multisite, you only need to provide the –uri parameter when using the site:install command. For example:

drush site:install --uri site1

The following are the prerequisites to pass URL in the -uri parameter:

  1. Set up the first multi-site with URL:

    1. Copy example.sites.php and paste it in your /sites/ folder.
    2. Rename example.sites copy.php to sites.php.

    Ignore these steps if you have already set up multisite with a simple -uri such as -uri=site1 or -uri=mysite.

  2. In  sites.php, add the URL that you want to pass in --uri. For example:

    $sites[‘’] = ‘acquia’;
  3. Run the URL in the –uri parameter:

    drush site:install --uri=””

    Acquia directory is created under the sites folder.

Drupal projects created using the acquia/drupal-recommended-project template include DRS out-of-the box.

  1. Create the project with the following command:

    composer create-project acquia/drupal-recommended-project project

DRS is compatible with Drupal projects created using the drupal/recommended-project template.

  1. Create the project with the following command:

    composer create-project drupal/recommended-project project
  2. Add DRS to the project with the following command:

    composer require acquia/drupal-recommended-settings
  3. Run the site:install command:

    drush site:install

    Notice that the command picks up the default database credentials from local.settings.php.

  4. Verify multisite features by running the site install command with the -uri option:

    drush site:install --uri site1

Using BLT with DRS


Acquia will end support for BLT on December 31, 2024. Therefore, Acquia recommends you to use DRS instead of BLT.

In BLT 14 and later, DRS is included out-of-the box. With this upgrade, DRS provides the setting-generation logic instead of BLT.

If you use BLT 13 or earlier, you can upgrade to BLT 14 by running the migrate command and automatically update the codebase to use BLT with DRS.

./vendor/bin/blt blt:migrate

After the update, the following changes occur:

  • Changes in settings.php:

    require DRUPAL_ROOT . "/../vendor/acquia/drupal-recommended-settings/settings/acquia-recommended.settings.php";
    * Do not include additional settings here. Instead, add them to settings
    * included by `acquia-recommended.settings.php`. See Acquia's documentation for more detail.
    * @link
  • Changes in local.settings.php:

    use Acquia\Drupal\RecommendedSettings\Helpers\EnvironmentDetector;

Migrating BLT to DRS


Acquia will end support for BLT on December 31, 2024. Therefore, Acquia recommends you to use DRS instead of BLT.

To migrate BLT to DRS:

  1. Upgrade to BLT 14.
  2. Run the migrate command to update the settings and local.settings files for each site in a multisite structure:

    ./vendor/bin/blt blt:migrate
  3. Remove BLT from codebase:

    composer remove acquia/blt
  4. Remove the BLT directory from your repo root: rm -rf blt.
  5. Remove or replace the BLT integrations that have their own migration paths:
    • Site Factory and multisite: The Drupal Recommended Settings plugin facilitates the settings capabilities of BLT for multisite.
    • SAML: Acquia recommends utilizing the SAML Auth module. SAML Auth is easy to configure through Drupal configuration.
    • BLT plugins: Acquia recommends exploring composer-based automation for commands contained in BLT plugins such as Behat tests.

      For example, the composer test that executes the necessary commands for tasks such as automated testing.

    • Twig linting: GrumPHP can be configured to lint Twig.
  6. Verify your site locally.

Using DRS with Site Factory

DRS uses a plugin to support Acquia Site Factory functionality. Sites using DRS can use drs-acsf and run setup commands to set up the codebase used for Site Factory.

Add and configure the drs-acsf plugin to the project codebase.

  1. Add the plugin with the following command:

    composer require acquia/drs-acsf
  2. Initialise acsf with the following command:

    ./vendor/bin/drush drs:acsf:init:all
    ./vendor/bin/drush drs:acsf:init:drush
  3. Validate all the settings with the following command:

    ./vendor/bin/drush validate:acsf
  4. Commit the changes and push your code to Site Factory.