README

settingsphp is a composer plugin that provides a layout of settings.*.php files, managed as scaffold files.

The aim of this plugin is to propose an standardisation around the management of settings.php. It has been designed to accomplish the following principles:

1. Keep main settings.php files clean.

In our vision it should be a copy of default.settings.php with minimal additions at the end.

This project adds a single include line to settings.php.

2. Allow configuration via environment variables.

Allowing configuration via environment variables enhances security, flexibility, and portability by separating configuration from code, simplifying deployment, and supporting dynamic customization.

3. Provide sane defaults.

By providing sane defaults we aim to reduce configuration overhead by ensuring Drupal works out-of-the-box with minimal setup.

4. Provide (opinionated) best practices.

File settings.recommended.php provides sbit.io specific Drupal settings.

Those are some of the tricks and best practices that we have learned from our experience as sysadmins for +10 years supporting high-traffic sites in Spain.

5. Allow to extend and override everything.

Extension points to tweak and suit your needs are provided.

Installation

First tell composer to allow this package operations:

composer config --merge --json extra.drupal-scaffold.allowed-packages '["drupal/settingsphp"]'
composer config --json "allow-plugins.drupal/settingsphp" true

Then run composer require drupal/settingsphp and observe this output:

Scaffolding files for drupal/settingsphp:
  - Copy [web-root]/sites/default/settings.php from assets/settings.php
  - Copy [web-root]/sites/default/settings.includes.php from assets/settings.includes.php
  - Copy [web-root]/sites/default/settings.init.php from assets/settings.init.php
  - Copy [web-root]/sites/default/settings.custom.php from assets/settings.custom.php
  - Copy [web-root]/sites/default/settings.recommended.php from assets/settings.recommended.php
  - Copy [web-root]/sites/default/settings.recommended-overrides.php from assets/settings.recommended-overrides.php
  - Copy [web-root]/sites/settings.redis.php from assets/settings.redis.php
  - Copy [web-root]/sites/services.redis.yml from assets/services.redis.yml

Please review those files and leart about the provided configuration and put your customizations in settings.custom.php or settings.recommended-overrides.php.

Note web/sites/default/settings.php is completely replaced and now it just just includes default.settings.php and settings.includes.php.

If you're installing over an existing project, refiew the diff on settings.php and relocate your customizations to the corresponding place.

Wenever possible we suggest to provide configuration via environmente variables.

Finally, review your .gitignore and ensure those files are included in the repo:

• sites/*/settings.php
• sites/*/settings.custom.php
• sites/*/settings.recommended-overrides.php

As an example, for a .gitignore file based on the one provided by drupal (web/.example.gitignore), add those lines:

diff --git a/web/.gitignore b/web/.gitignore
index d77a48bc..b5d09459 100644
--- a/web/.gitignore
+++ b/web/.gitignore
@@ -21,6 +21,11 @@
 sites/*/settings*.php
 sites/*/services*.yml

+# drupal/settingsphp
+!sites/*/settings.php
+!sites/*/settings.custom.php
+!sites/*/settings.recommended-overrides.php

These folders should also be excluded from git:

/private-files
/storage
/tmp

Environment variables reference.

See a reference of environment variables in .env.example.

Docker compose / stack

You can use this variables file directly from your compose file with:

services:
  drupal:
    image: $DRUPAL_IMAGE:$DRUPAL_IMAGE_TAG
    # Allow any env to be passed without having to declare it explicitly.
    env_file: .env

See drupal/dockerize for a containerized solution.