[D8] Introduce a new example.settings.local.php file

[alanmels]

Didn't want to hijack the https://github.com/backdrop/backdrop-issues/issues/1855, because that one's been created for Documentation purpose, so am creating a new one.

Description of the need

As developers we find it always handy to set number of configurations in certain ways, for example, making it show all the errors on the screen, disabling some cache, or setting the current theme to rebuild its registry on every page load, etc. And instead of going through different pages on UI every time we start a new project, it's much easier just to use the feature discussed and introduced on https://github.com/backdrop/backdrop-issues/issues/1752.

Proposed solution

Nevertheless, the check for local settings file has already been introduced, manually compiling that kind of local settings file also takes valuable time. I suggest to take this further and add missing feature parity with Drupal 8 - as we can see on https://git.drupalcode.org/project/drupal/tree/8.8.x/sites Drupal 8 is shipped with the well-formatted example.settings.local.php file. It would be really useful for developers to have ready-to-use example.settings.local.php file in Backdrop core.

[jenlampton]

I am against adding any developer-specific settings to a settings.local.php file, should we choose to add one. In Drupal 8, I believe they intend their example file to be used by developers. In Backdrop this file is not for developers.

I use settings.local.php on every environment (not just my laptop) to contain all the local settings I don't want in Git (like db connection info and files directories). I'd never want developer-specific settings on my production or staging environments, so I wouldn't want them to be provided by default in settings.local.php.

[alanmels]

I am against adding any developer-specific settings to a settings.local.php file, should we choose to add one. In Drupal 8, I believe they intend their example file to be used by developers. In Backdrop this file is not for developers.

I use settings.local.php on every environment (not just my laptop) to contain all the local settings I don't want in Git (like db connection info and files directories). I'd never want developer-specific settings on my production or staging environments, so I wouldn't want them to be provided by default in settings.local.php.

I think I am either having difficulties here to properly understand you, because English is a learned language for me or you must be confusing the settings.php file with the settings.local.php file. I always believed the settings.local.php is exactly what you are using it for as a developer:

I use settings.local.php on every environment (not just my laptop) to contain all the local settings I don't want in Git (like db connection info and files directories).

and that's exactly why that file should be excluded for git pushes. At the same time, the settings.php file is for all users and that file should be synced between environments.

For example, I really would not want to place $settings['error_level'] = 'all' in the settings.php file, because it will be synced between environments. However, placing it inside the settings.local.php file is ideal, because it is git excluded and effects only the environment where the file is used.

[alanmels]

In Backdrop this file is not for developers.

Has this been documented anywhere?

[jenlampton]

I think I am either having difficulties here to properly understand you, because English is a learned language for me

I think your English is great! :) I couldn't tell.

or you must be confusing the settings.php file with the settings.local.php file

We are using them in different ways. I use mine everywhere -- it sounds like you only use yours for local development.

I always believed the settings.local.php is exactly what you are using it for as a developer

Well, I use settings.php as a developer too, but now I'm getting into a really slippery slope.

Has this been documented anywhere?

Only in settings.php above where the file is included automatically:

/**
 * Include a local settings file, if available.
 *
 * To make local development easier, you can add a settings.local.php file that
 * contains settings specific to your local installation, or to any secondary
 * environment (staging, development, etc).
 *
 * Typically used to specify a different database connection information, to
 * disable caching, JavaScript/CSS compression, re-routing of outgoing e-mails,
 * Google Analytics, and other things that should not happen on development and
 * testing sites.
 *
 * This local settings file can be ignored in your Git repository, so that any
 * updates to settings.php can be pulled in without overwriting your local
 * changes.
 *
 * Keep this code block at the end of this file to take full effect.
 */

The line you can add a settings.local.php file that contains settings specific to your local installation, or to any secondary environment (staging, development, etc). covers both your use case (specific to your local installation) and mine (or to any secondary environment).

In addition, I also put my production database connection info into a file named settings.local.php on my production environment, so that my settings.php file is safe to commit and deploy via Git. That's not defined in the docs above, but I think it's an important use case, which I think you also use?

At the same time, the settings.php file is for all users and that file should be synced between environments.

[alanmels]

In addition, I also put my production database connection info into a file named settings.local.php on my production environment, so that my settings.php file is safe to commit and deploy via Git.

@jenlampton, if it helps any, both settings.php file and settings.local.php files can contain database connection details. The database settings in settings.local.php always takes over, so that's why we safely sync the settings.php containing production DB connection between all development, testing, stage, production environments regardlessly where they physically are (so they can be local or remote, doesn't matter).

And that's why we place database connection for development branch in its own settings.local.php file. Testing, stage branches can have their own settings.local.php. That's why the file is called local, because it is local to each environment. And thats exactly why temporary developer overrides should be placed in the example.settings.local.php file, so developers could just copy and start using it in any branch they want to work with enforcing temporary developer overrides.

On the other hand the settings.php is not for developers, it is for all regular users, so they can sometimes, for example, turn access to update.php file for themselves. And believe me most of the developer stacks like Docksal sync the settings.php file at the same time placing settings.local.php in .gitignore file, so developers could use it for local needs for each environment.

[jenlampton]

Ah, you just answered the question I asked in https://github.com/backdrop/backdrop-issues/issues/4190.

And that's why we place database connection for development branch in its own settings.local.php file. Testing, stage branches can have their own settings.local.php. That's why the file is called local, because it is local to each environment.

See, this is the exact same workflow I use. I'm not alone :) This is option 2 in https://github.com/backdrop/backdrop-issues/issues/4190. But I'm not sure why you voted for 1 if you are doing number 2.

[herbdool]

Seems to me there is more or less agreement to create this file and put in some basic info on what settings can be overridden (once the other PR is committed)

[alanmels]

Ah, you just answered the question I asked in #4190.

And that's why we place database connection for development branch in its own settings.local.php file. Testing, stage branches can have their own settings.local.php. That's why the file is called local, because it is local to each environment.

See, this is the exact same workflow I use. I'm not alone :) This is option 2 in #4190. But I'm not sure why you voted for 1 if you are doing number 2.

Please see https://github.com/backdrop/backdrop-issues/issues/4190#issuecomment-549032637 Thanks!

[alanmels]

And if this ever will be implemented, then to address two issues at once we need to name such a file example.local.settings.php in accordance with the taken, but postponed decision on https://www.drupal.org/node/2419213

[herbdool]

@alanmels I don't think your proposed file renaming adds enough value to offset the hassle of forcing people to change their files.

[alanmels]

@herbdool It's ok if we do not. I was just finding arguments on https://www.drupal.org/node/2419213 legitimate for Backdrop too:

Most files in Drupal core are named from specific-to-general separated by dots. For example, development.services.yml, default.settings.php, or example.gitignore. But not settings.local.php.

[izmeez]

There are some interesting ideas in this issue and #4190 I wondering if the different ideas are in a document page somewhere. Examples of how to add some items like those described in the opening comment would be handy.