# Managing CMS Settings

Any CMS-specific project type, meaning any of the non-generic [CMS Quickstarts](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>), has settings that DDEV manages to save you time and optimize configuration for local development.

Generally, DDEV will:

- Create a main settings file if none exists, like Drupal’s `settings.php`.
- Create a specialty config file with DDEV-specific settings, like `AdditionalSettings.php` for TYPO3 or `settings.ddev.php` for Drupal.
- Add an include of the specialty file if needed, like adding `settings.ddev.php` include to the bottom of Drupal’s `settings.php`.

While this reduces setup time for new users, makes it easier to try out a CMS, and speeds up project creation, you may still want to modify or override DDEV’s CMS-specific behavior.

## Controlling or Removing CMS Settings

There are several ways to back off DDEV’s CMS settings management:

1. **Take control of files by removing the `#ddev-generated` comment.** DDEV will automatically update any it’s added containing a `#ddev-generated` comment. This means you don’t need to touch that file, but also that any changes you make will be overwritten. As soon as you remove the comment, DDEV will ignore that file and leave you fully in control over it. (Don’t forget to check it into version control!)

   > **Reversing the change**
   >
   > If you change your mind and want DDEV to take over the file again, delete it and run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>). DDEV will recreate its own version, which you may want to remove from your Git project.
2. **Disable settings management.** You can tell DDEV to use a specific project type without creating settings files by either setting [`disable_settings_management`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) to `true` or running [`ddev config --disable-settings-management`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).
3. **Switch to the generic PHP project type.** If you don’t want DDEV’s CMS-specific settings, you can switch your project to the generic `php` type by editing [`type: php`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#type>) in the project’s settings or running [`ddev config --project-type=php`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). DDEV will no longer create or tweak any settings files. You’ll lose any perks from the nginx configuration for the CMS, but you can always customize [nginx settings](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-nginx-configuration>) or [Apache settings](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-apache-configuration>) separately.
4. **Un-set the `$IS_DDEV_PROJECT` environment variable.** This environment variable is set `true` by default in DDEV’s environment, and can be used to fence off DDEV-specific behavior. When it’s empty, the important parts of `settings.ddev.php` and `AdditionalSettings.php` (for TYPO3) are not executed. This means that DDEV’s `settings.ddev.php` won’t be invoked if it somehow ends up in a production environment or in a non-DDEV local development environment.

> [!TIP]
>
> **Ignore `.ddev/.gitignore`**
>
> The `.ddev/.gitignore` file is created when you run `ddev start` and `disable_settings_management` is `false`. You should *not* check this file in, since it ignores itself and DDEV’s temporary and automatically-managed files. This makes it easier for teams to share the `.ddev` folder via Git, even if the `.ddev/.gitignore` file changes with different versions.

## CMS-Specific Help and Techniques

### Backdrop Specifics

#### Configuration considerations

By default, Backdrop stores both active and staging configuration in the filesystem. In this case, if you are updating the database (either from a live site, or reloading while working locally) it can be important to also refresh the active configuration directory to make sure your database structure is in line with what your configuration is describing.

Backdrop also allows you to store your active configuration in the database ([as of Backdrop 1.28.0](<https://docs.backdropcms.org/change-records/swappable-config-storage>)), which can be simpler while developing locally, especially if you are making use of DDEV’s snapshot feature. In this case, the database and the active configuration are effectively bundled and refreshing the database also refreshes the active configuration.

### Drupal Specifics

#### Drupal Settings Files

By default, DDEV will create settings files for your project that work out of the box. It creates a `sites/default/settings.ddev.php` and adds an include in `sites/default/settings.php` to bring that in. There are guards to prevent the `settings.ddev.php` from being active when the project is not running under DDEV, but it still should not be checked in and is gitignored.

#### Database requirements for Drupal 9.5+

- Using MySQL or MariaDB, Drupal requires `SET GLOBAL TRANSACTION ISOLATION LEVEL READ COMMITTED` and DDEV does this for you on [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).
- Using PostgreSQL, Drupal requires the`pg_trm` extension. DDEV creates this extension automatically for you on `ddev start`.

#### Twig Debugging

With the default Drupal configuration, it’s very difficult to debug Twig templates; you need to use `development.services.yml` instead of `services.yml`. Add this line in your `settings.php` or `settings.local.php`. See discussion at [drupal.org](<https://www.drupal.org/forum/support/module-development-and-code-questions/2019-09-02/ddev-twig-debugging>) and the Drupal documentation.

```
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
```

#### Drush and Xdebug

Drush 13+ disables Xdebug even when [Xdebug is enabled on DDEV](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>).

As per [Drush docs](<https://www.drush.org/13.x/commands/#xdebug>) you can:

- Enable it for a single Drush command by running: `ddev drush --xdebug`
- Set `DRUSH_ALLOW_XDEBUG=1` [environment variable](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>), allowing every Drush call to be run with Xdebug when the PHP extension is enabled.

#### Multisite

1. Start with the [DDEV Drupal 8 Multisite Recipe](<https://github.com/ddev/ddev-contrib/tree/master/recipes/drupal8-multisite>).
2. Update configuration files.

   1. Update each `site/{site_name}/settings.php`:

      ```
      /**
       * DDEV environments will have $databases (and other settings) set
       * by an auto-generated file. Make alterations here for this site
       * in a multisite environment.
       */
      elseif (getenv('IS_DDEV_PROJECT') == 'true') {
        /**
         * Alter database settings and credentials for DDEV environment.
         * Includes loading the DDEV-generated `default/settings.ddev.php`.
         */
        include $app_root . '/' . $site_path . '/settings.databases.ddev.inc';
      }
      ```
   2. Add a `settings.databases.ddev.inc` in each `site/{site_name}/`:

      ```
      /**
       * Fetch DDEV-generated database credentials and other settings.
       */
      require $app_root . '/sites/default/settings.ddev.php';

      /**
       * Alter default database for this site. `settings.ddev.php` will have
       * “reset” this to 'db'.
       */
      $databases['default']['default']['database'] = 'site_name';
      ```
   3. Update your [`web_environment`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_environment>) config option if you’re using site aliases:

      ```
      web_environment:
          # Make DDEV Drush shell PIDs last for entire life of the container
          # so `ddev drush site:set @alias` persists for all Drush connections.
          # https://chrisfromredfin.dev/posts/drush-use-ddev/
          - DRUSH_SHELL_PID=PERMANENT
      ```

### MODX Specifics

#### MODX Settings File

On [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>), DDEV manages MODX Revolution’s main configuration file, `core/config/config.inc.php`, for both MODX 2.x and 3.x. It writes the DDEV database credentials (database name, user, and password are all `db`; host is `db`) along with the MODX path and URL constants, so a project whose database has been imported or seeded connects and boots straight away, including the `/manager/` backend.

The generated file carries the `#ddev-generated` signature. If you want to take over the file and manage it yourself, remove that signature line and DDEV will respect your version and won’t overwrite it. DDEV also leaves a config file that was written by the MODX installer (which has no signature) alone.

The `config.core.php` stub files (at the web root and in `core/`, `manager/`, and `connectors/`) only define `MODX_CORE_PATH` and `MODX_CONFIG_KEY`; DDEV does not touch them.

### TYPO3 Specifics

#### Settings Files

On [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>), DDEV creates a `config/system/additional.php` file with database configuration in it.

#### Setup a Base Variant (since TYPO3 9.5)

Since TYPO3 9.5 you have to setup a `Site Configuration` for each site you like to serve. To be able to browse the site on your local environment, you have to set up a `Base Variant` in your `Site Configuration` depending on your local context. In this example we assume a `Application Context` `Development/DDEV` which can be set in the DDEV’s `config.yaml`:

```
web_environment:
    - TYPO3_CONTEXT=Development/DDEV
```

This variable will be available after the project start or restart.

Afterwards add a `Base Variant` to your `Site Configuration`:

```
baseVariants:
  -
    base: 'https://example.com.ddev.site/'
    condition: 'applicationContext == "Development/DDEV"'
```

See also [TYPO3 Documentation](<https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/BaseVariants.html>).

### WordPress Specifics

#### WP-CLI and changing the docroot in config.yaml

[`ddev wp`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#wp>) defaults WP-CLI’s `path` to your project’s docroot, so WP-CLI still finds WordPress when the docroot is something other than the project root (`''`).

If WordPress does not live at the docroot, override that default with a `wp-cli.yml` file in the project root directory. [Bedrock](<https://roots.io/bedrock/>), for example, serves from `web` but keeps WordPress in `web/wp`, so its `wp-cli.yml` contains:

```
path: web/wp
```

A `--path` flag, an [alias](<https://make.wordpress.org/cli/handbook/references/config/#config-files>), and `wp-cli.local.yml` all take precedence over the DDEV default in the same way.

#### WordPress Environment Type

By default, [`wp_get_environment_type()`](<https://developer.wordpress.org/reference/functions/wp_get_environment_type/>) returns `production`. However, you can override it in one of two ways:

1. Setting an environment variable, such as with the following [ddev command](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>):

   ```
   ddev config --web-environment-add="WP_ENVIRONMENT_TYPE=local"
   ```
2. Defining the `WP_ENVIRONMENT_TYPE` constant:

   To do this, modify your `wp-config-ddev.php` file by [removing](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#what-if-i-dont-like-the-settings-files-or-gitignores-ddev-creates>) the `#ddev-generated` line and adding this code snippet:

   ```
   defined( 'WP_ENVIRONMENT_TYPE' ) || define( 'WP_ENVIRONMENT_TYPE', 'local' );
   ```