Controlling CMS Settings Files in DDEV¶
One DDEV feature that lots of people love is its creation and management of CMS-specific settings files. This makes starting and installing a new project a breeze, and is a fantastic time-saver for many users. People can follow one of the many DDEV Quickstart Guides and have a project up and installed in no time. To make this happen, DDEV does a quite a bit of settings management for explicitly-supported CMSes. DDEV will:
- Create a main settings file if none exists, like Drupal’s
- Create a specialty config file with DDEV-specific settings, like
AdditionalSettings.phpfor TYPO3 or
- Add an include of the specialty file if needed, like adding
settings.ddev.phpinclude to the bottom of Drupal’s
This helps new users and people who are kicking the tires on a CMS. Plus it’s helpful for many developers in their regular workflow. However, there are plenty of you who have sophisticated team and project workflows and don’t want DDEV to manage settings files, or prefer to manage your own. DDEV has always tried to give you control as needed:
- If you don’t want DDEV to touch a file, remove the
#ddev-generatedline from that file, empty it or put your own contents in it, and check it into version control. DDEV will then ignore that file and not try to regenerate it.
- If you later want DDEV to take that file over again, just remove the one that you edited and
ddev startand DDEV will create its own version. (You may have to remove it from your Git project if you added it).
- If you don’t want DDEV to even know what kind of CMS (or other project) you have, use
type: phpin your
ddev config --project-type=php). DDEV will no longer create or tweak any settings files, you’re now on your own. (The one drawback of this approach is that you don’t get the nginx configuration which has been tweaked for your CMS. But, as always, you can create your own nginx or Apache configurations.) (docs).
- If you want DDEV to know about the project type, but not create settings files, use
disable_settings_management: true. If you want DDEV to use the CMS-specific nginx configuration, but don't want it to touch anything else, you can put
disable_settings_management: truein your
ddev config --disable-settings-management) and DDEV won’t try to create any of the CMS-specific settings files.
- There is also an environment variable
$IS_DDEV_PROJECTthat can be used to fence off DDEV-specific behavior. For example, with
$IS_DDEV_PROJECTempty, the important parts of
AdditionalSettings.php(for TYPO3) are not executed. This means that DDEV’s
settings.ddev.phpwon't be invoked if it somehow ends up in a production environment or in a non-DDEV local development environment.
.ddev/.gitignoreis created by
ddev startbecause it gitignores itself. So the intention is that you should not check in the
.ddev/.gitignoreand it will be created on start if
false. This helps teams to share
.ddevfolder checked in by Git, even if the
.ddev/.gitignorechanges with different versions.
CMS-Specific Help and Techniques¶
- Settings Files: By default, DDEV will create settings files for your project that make it “just work” out of the box. It creates a
sites/default/settings.ddev.phpand adds an include in
sites/default/settings.phpto bring that in. There are guards to prevent the
settings.ddev.phpfrom 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 COMMITTEDand DDEV does this for you on
- Using PostgreSQL, Drupal requires the
pg_trmextension. DDEV creates this extension automatically for you on
- Using MySQL or MariaDB, Drupal requires
- Twig Debugging: With the default Drupal configuration, it’s very difficult to debug Twig templates; you need to use
services.yml. Add this line in your
settings.local.php. See discussion at drupal.org and the Drupal documentation.
- Settings Files: On
ddev start, DDEV creates a
public/typo3conf/AdditionalConfiguration.phpwith 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
Development/DDEV which can be set in the DDEV’s
This variable will be available after the project start or restart.
Afterwards add a
Base Variant to your
See also TYPO3 Documentation.
Running any PHP App with DDEV¶
Nearly any PHP app will run fine with DDEV, and lots of others. If your project type is not one of the explicitly supported project types, that’s fine. Just set the project type to
php and go about setting up settings files or
.env as you normally would.