Problem/Motivation

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.

Proposed resolution

Rename the file, which is only mentioned in a commented-out section in default.settings.php. This improves consistency in file naming and makes it obvious that local.settings.php contains code that will override settings.php.

Remaining tasks

None.

User interface changes

None.

API changes

None.

Beta phase evaluation

Reference: https://www.drupal.org/core/beta-changes
Issue category Task
Issue priority Very (very, very) minor
Disruption Minor. Only existing D8 sites that are using settings.local.php will be affected.
CommentFileSizeAuthor
#11 2419213-11-rename-local-settings.patch3.31 KBmikeker
#8 2419213-8-6.interdiff.txt2.46 KBmikeker
#8 2419213-8-4.interdiff.txt885 bytesmikeker
#8 2419213-8-2.interdiff.txt2.02 KBmikeker
#8 2419213-8-rename-local-settings.patch3.49 KBmikeker
#6 drupal_rename-settings-local-php_2419213_6.patch4.49 KBnicoleheard
#4 drupal_rename-settings-local-php_2419213_3.patch6.44 KBlucastockmann
#2 rename-local-settings-2419213-2.patch2.2 KBmikeker
#1 rename-local-settings-2419213.patch2.01 KBmikeker

Comments

mikeker’s picture

mikeker commented
Status: Active » Needs review
StatusFileSize
new rename-local-settings-2419213.patch2.01 KB
mikeker’s picture

mikeker commented
StatusFileSize
new rename-local-settings-2419213-2.patch2.2 KB

Also renaming the example file.

mikeker’s picture

mikeker commented
Related issues: +#1118520: Add inclusion of a settings.local.php file in settings.php

FYI: There was a brief discussion of this at the beginning of #1118520: Add inclusion of a settings.local.php file in settings.php.

lucastockmann’s picture

lucastockmann commented
StatusFileSize
new drupal_rename-settings-local-php_2419213_3.patch6.44 KB

You missed out some "settings.local.php" strings in the comments, I fixed this.
Here is my patch.

But your code changes and renaming worked fine.

mikeker’s picture

mikeker commented
Related issues: +#2315613: Add a development.services.yml for development

Added related issue #2315613: Add a development.services.yml for development, which starts out as services.local and then sees the light... :)

nicoleheard’s picture

nicoleheard commented
StatusFileSize
new drupal_rename-settings-local-php_2419213_6.patch4.49 KB

Re-rolled the patch to apply cleanly to commit db60a8c

mikeker’s picture

mikeker commented
Status: Needs review » Needs work

The example.local.settings.php file is missing from the latest patch... I'm not sure where it happened, but the renaming of the example file seems to have turned into an add/remove instead.

mikeker’s picture

mikeker commented
StatusFileSize
new 2419213-8-rename-local-settings.patch3.49 KB
new 2419213-8-2.interdiff.txt2.02 KB
new 2419213-8-4.interdiff.txt885 bytes
new 2419213-8-6.interdiff.txt2.46 KB

Found another reference that I missed. Grrr... OK, I've grep'ed and searched by install and there are no more references to settings.local.php. Really! Promise! :)

I've included a small pile of interdiffs because the rename of example.settings.local.php went from a two-line "rename from x to y" to a 100 lines of +/- which hides the latest change since it was in that file. Hopefully this makes things clearer.

mikeker’s picture

mikeker commented
Related issues: +#2381091: Improve example.gitignore

Also note that you'll want #2381091: Improve example.gitignore to update your .gitignore file to the new naming scheme.

mikeker’s picture

mikeker commented
Status: Needs work » Needs review
mikeker’s picture

mikeker commented
StatusFileSize
new 2419213-11-rename-local-settings.patch3.31 KB

Just noticed that Git "helpfully" found a similar file (sites/default/local.settings.php) to sites/example.settings.local.php when diff'ing for the patch in #8. So the example file got renamed AND copied. Thanks, Git! :)

This patch does a clean rename from sites/example.settings.local.php to sites/example.local.settings.php. Since I can't really include a proper interdiff with this change, here's a diff of the two patches:

$ git diff --no-index 2419213-8-rename-local-settings.patch 2419213-11-rename-local-settings.patch
diff --git a/2419213-8-rename-local-settings.patch b/2419213-11-rename-local-settings.patch
index ab0062e..83829b1 100644
--- a/2419213-8-rename-local-settings.patch
+++ b/2419213-11-rename-local-settings.patch
@@ -32,10 +32,6 @@ index d5d8704..ea6fb17 100644
 +# if (file_exists(__DIR__ . '/local.settings.php')) {
 +#   include __DIR__ . '/local.settings.php';
  # }
-diff --git a/sites/example.settings.local.php b/sites/default/local.settings.php
-similarity index 100%
-copy from sites/example.settings.local.php
-copy to sites/default/local.settings.php
 diff --git a/sites/development.services.yml b/sites/development.services.yml
 index cc21211..7637af8 100644
 --- a/sites/development.services.yml
Shivam Agarwal’s picture

Shivam Agarwal commented
Status: Needs review » Needs work

Patch doesn't seems to work. It throws following error when I tried to apply :
<

error: patch failed: sites/default/default.settings.php:639
error: sites/default/default.settings.php: patch does not apply
Checking patch sites/development.services.yml...
error: sites/development.services.yml: No such file or directory
Checking patch sites/example.settings.local.php => sites/example.local.settings.php...
error: sites/example.settings.local.php: No such file or directory
mikeker’s picture

mikeker commented
Status: Needs work » Needs review

@Shivam Agarwal: I just applied the patch to the latest pull of 8.0.x without errors. Can you try it against the latest HEAD?

Please include the errors from git apply and set the issue to Needs work if you still have problems.

Shivam Agarwal’s picture

Shivam Agarwal commented
Status: Needs review » Reviewed & tested by the community

@mikekr, sorry my fault. It cleanly applied to latest head. It looks good. :) Thanks

xjm’s picture

xjm
she/her
Primary language English
commented
Version: 8.0.x-dev » 9.x-dev
Status: Reviewed & tested by the community » Postponed

Thanks @Shivam Agarwal and @mikeker for your work here! And thank you for adding the beta evaluation.

Unfortunately, this is not only a documentation change. While it is indeed commented out by default, it still makes a change to system_requirements() and to a recommendation or expectation for a functional code path. The "unfrozen" category for documentation is intended to encourage people to improve actual documentation that explains how Drupal works.

@alexpott and I discussed the disruption (or not) of this patch for awhile this morning. At first glance I thought this change would break existing sites using settings.local.php once the section in the main settings.php was changed. But that is not actually the case -- since we do not update existing sites' settings.php (and shouldn't), those sites would continue to use the previous code checking for the other name pattern.

Still, we are at a minimum changing a site builder expectation (and a bit of runtime code), so I think it's better to postpone this to 9.x. If you disagree, move it back and we can discuss it more.

xjm’s picture

xjm
she/her
Primary language English
commented
Issue summary: View changes
mikeker’s picture

mikeker commented

@xjm: Understood re: doc changes. I think I added that part of the beta eval before I added the system_requirements change. Sorry, I should have updated the beta eval when that change went into the patch.

I'm fine with postponing. I'll keep my OCD in check when adding my dev settings file for the next few years... :) Thank you for giving this issue such thorough consideration!

Somewhat tangentially related issue, while we're on the subject of settings files: #2381091: Improve example.gitignore

catch’s picture

catch
he/him
Primary language English
commented
Version: 9.x-dev » 8.1.x-dev

I think we could look at this for a minor release - it'd only be documentation + string changes.

star-szr’s picture

star-szr
he/him
Primary language English
commented

Just made this somewhat related issue: #2618158: The location of example.settings.local.php is confusing

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.0-beta1 was released on March 2, 2016, which means new developments and disruptive changes should now be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

heddn’s picture

heddn
Primary language English
Location Nicaragua
commented

From a file system sort ordering thing, I prefer all my "settings" files to be together. ex. settings.local.php, settings.dev.php, settings.stage.php, settings.php, etc. If they are scattered around with various names, then I find it is harder to locate them and I miss seeing them in a visual inspection.

corbacho’s picture

corbacho commented
Related issues: +#2723261: Ignore local development files in example.gitignore

Good idea.

I spotted a possible issue with gitignore, but I opened it in a new issue, in case the scope of this one gets bigger:
#2723261: Ignore local development files in example.gitignore

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

chipway’s picture

chipway commented

I agree with @heddn, for the naming parts order to find related files together.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

jcnventura’s picture

jcnventura
Primary language English
commented
Version: 9.3.x-dev » 10.0.x-dev

If this were to happen, it should not be before 10.0, since Drupal 9 is already been released and this should not be the kind of change done in minor versions.

That being said, I agree with @heddn. settings.local.php makes a LOT more sense than local.settings.php. I vote to simply close this issue as a "won't fix".

berdir’s picture

berdir
Primary language German
Location Switzerland
commented
Status: Postponed » Closed (won't fix)

There has been no attempt at moving this forward in many years, agree to have the settings files together is useful. Yes, default.settings.php is different, but that is actually also something very different and is not used at runtime, so makes kind of sense to have it separate.

Agreed with won't fix. If someone feels strongly we could reopen but apparently nobody did in 6 years now or so :)