github.com/ddev/ddev@v1.23.2-0.20240519125000-d824ffe36ff3/docs/content/users/usage/cms-settings.md (about)

     1  # Managing CMS Settings
     2  
     3  Any CMS-specific project type, meaning any of the non-generic [CMS Quickstarts](../../users/quickstart.md), has settings that DDEV manages to save you time and optimize configuration for local development.
     4  
     5  Generally, DDEV will:
     6  
     7  * Create a main settings file if none exists, like Drupal’s `settings.php`.
     8  * Create a specialty config file with DDEV-specific settings, like `AdditionalSettings.php` for TYPO3 or `settings.ddev.php` for Drupal.
     9  * Add an include of the specialty file if needed, like adding `settings.ddev.php` include to the bottom of Drupal’s `settings.php`.
    10  
    11  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.
    12  
    13  ## Controlling or Removing CMS Settings
    14  
    15  There are several ways to back off DDEV’s CMS settings management:
    16  
    17  1. **Take control of files by removing the `#ddev-generated` comment.**  
    18  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!)
    19  
    20      !!!tip "Reversing the change"
    21          If you change your mind and want DDEV to take over the file again, delete it and run [`ddev start`](../usage/commands.md#start). DDEV will recreate its own version, which you may want to remove from your Git project.
    22  
    23  2. **Disable settings management.**  
    24  You can tell DDEV to use a specific project type without creating settings files by either setting [`disable_settings_management`](../configuration/config.md#disable_settings_management) to `true` or running [`ddev config --disable-settings-management`](../configuration/config.md#type).
    25  
    26  3. **Switch to the generic PHP project type.**  
    27  If you don’t want DDEV’s CMS-specific settings, you can switch your project to the generic `php` type by editing [`type: php`](../configuration/config.md#type) in the project’s settings or running [`ddev config --project-type=php`](../usage/commands.md#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](../extend/customization-extendibility.md#custom-nginx-configuration) or [Apache settings](../extend/customization-extendibility.md#custom-apache-configuration) separately.
    28  
    29  4. **Un-set the `$IS_DDEV_PROJECT` environment variable.**  
    30  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.
    31  
    32  !!!tip "Ignore `.ddev/.gitignore`"
    33      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.
    34  
    35  ## CMS-Specific Help and Techniques
    36  
    37  ### Drupal Specifics
    38  
    39  #### Drupal Settings Files
    40  
    41  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.
    42  
    43  #### Database requirements for Drupal 9.5+
    44  
    45  * Using MySQL or MariaDB, Drupal requires `SET GLOBAL TRANSACTION ISOLATION LEVEL READ COMMITTED` and DDEV does this for you on [`ddev start`](../usage/commands.md#start).
    46  * Using PostgreSQL, Drupal requires the`pg_trm` extension. DDEV creates this extension automatically for you on `ddev start`.
    47  
    48  #### Twig Debugging
    49  
    50  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.
    51  
    52  ```php
    53  $settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
    54  ```
    55  
    56  #### Multisite
    57  
    58  1. Start with the [DDEV Drupal 8 Multisite Recipe](<https://github.com/ddev/ddev-contrib/tree/master/recipes/drupal8-multisite>).
    59  2. Update configuration files.
    60      1. Update each `site/{site_name}/settings.php`:
    61  
    62          ```php
    63          /**
    64           * DDEV environments will have $databases (and other settings) set
    65           * by an auto-generated file. Make alterations here for this site
    66           * in a multisite environment.
    67           */
    68          elseif (getenv('IS_DDEV_PROJECT') == 'true') {
    69            /**
    70             * Alter database settings and credentials for DDEV environment.
    71             * Includes loading the DDEV-generated `default/settings.ddev.php`.
    72             */
    73            include $app_root . '/' . $site_path . '/settings.databases.ddev.inc';
    74          }
    75          ```
    76  
    77      2. Add a `settings.databases.ddev.inc` in each `site/{site_name}/`:
    78  
    79          ```php
    80          /**
    81           * Fetch DDEV-generated database credentials and other settings.
    82           */
    83          require $app_root . '/sites/default/settings.ddev.php';
    84  
    85          /**
    86           * Alter default database for this site. `settings.ddev.php` will have
    87           * “reset” this to 'db'.
    88           */
    89          $databases['default']['default']['database'] = 'site_name';
    90          ```
    91  
    92      3. Update your [`web_environment`](../configuration/config.md#web_environment) config option if you’re using site aliases:
    93  
    94          ```yaml
    95          web_environment:
    96            # Make DDEV Drush shell PIDs last for entire life of the container
    97            # so `ddev drush site:set @alias` persists for all Drush connections.
    98            # https://chrisfromredfin.dev/posts/drush-use-ddev/
    99            - DRUSH_SHELL_PID=PERMANENT
   100          ```
   101  
   102  ### TYPO3 Specifics
   103  
   104  #### Settings Files
   105  
   106  On [`ddev start`](../usage/commands.md#start), DDEV creates a `public/typo3conf/AdditionalConfiguration.php` file with database configuration in it.
   107  
   108  #### Setup a Base Variant (since TYPO3 9.5)
   109  
   110  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`:
   111  
   112  ```yaml
   113  web_environment:
   114  - TYPO3_CONTEXT=Development/DDEV
   115  ```
   116  
   117  This variable will be available after the project start or restart.
   118  
   119  Afterwards add a `Base Variant` to your `Site Configuration`:
   120  
   121  ```yaml
   122  baseVariants:
   123    -
   124      base: 'https://example.com.ddev.site/'
   125      condition: 'applicationContext == "Development/DDEV"'
   126  ```
   127  
   128  See also [TYPO3 Documentation](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/BaseVariants.html).