Move settings.php to /settings directory, fold sites.php into settings.php

Problem

1. The new directory layout in D8 hides most parts of the advanced multi-site feature from users that don't need it, which is a good thing:

   Top-level /modules, /themes, and /profiles directories can be used for site-wide extensions.

2. However, settings.php must still be placed into /sites/default/settings.php.

   This is unnecessary and forces the multi-site concept onto users that shouldn't need to care about it.

3. In addition, because the multi-site concept is enabled by default, additional calls to file_exists() are required on all sites (whether sites.php exists), even if there is only one site, which harms performance.

Goal

• Simplify the bootstrap by requiring /settings/settings.php to exist, and explicitly opt-in for the multi-site functionality.

Proposed solution

1. Require a top-level, global /settings/settings.php to exist in any case (set up by the installer).

2. Merge /sites/sites.php into the top-level /settings/settings.php, and turn the $sites variable into an explicit flag for enabling the multi-site functionality.

   This means:

   1. If the root /settings/settings.php does not define the $sites variable at all, then there is no multi-site functionality and no site directory discovery process.
   2. If the root /settings/settings.php defines an empty $sites = array();, then the multi-site functionality is enabled and the site directory is discovered on every request.
   3. If the root /settings/settings.php defines site aliases in the form of $sites['localhost.example'] = 'example.com';, then the specified site aliases are resolved during the site directory discovery (no change).

   This also means:

   1. When the multi-site functionality is enabled, then the root /settings/settings.php acts as if it was a /sites/all/settings.php, which is a concept that does not exist thus far — i.e., the root /settings.php can contain shared settings for all sites.
   2. The root /settings/settings.php is always loaded first. The site-specific sites/foo/settings.php has access to all of the global variables and is able to override them in a granular way.

3. → (Implicitly) Eliminate /sites/default. (DX++)

   If the multi-site functionality is not enabled, the root directory of your Drupal site becomes the site directory itself:

   /files
   /modules
   /profiles
   /themes
   /settings/settings.php
   

   /files is moved (back) to the document root (as in D6 and below).

   /sites no longer exists by default.

   Note: This patch has to retain /sites/default/settings.php due to #2206501: Remove dependency on Drush from test reviews

4. Introduce a new Site singleton class to replace conf_path().

   This is required, because if the root directory is the site directory, then a string concatenation like the following would result in an absolute filesystem path:

   // If the sire directory path is empty (root directory), then the resulting
   // filesystem path would become absolute; i.e.: "/some/file"
   unlink($site_path . '/some/file');
   

   To prevent that, all calls to conf_path() are replaced with the following:

   $site_path_relative = Site::getPath();
   $site_path_absolute = Site::getAbsolutePath();
   $some_file_relative = Site::getPath('settings.php');
   $some_file_absolute = Site::getAbsolutePath('settings.php');
   
   // The argument is a relative subpathname, so this works, too:
   $some_file_relative = Site::getPath('files/translations/foo/bar.txt');
   

5. Move /sites/default/default.settings.php into /core/default.settings.php, so it is updated when Drupal core is updated.

.

.

.

Original summary by @naxoc

This is a split-out from #760992: Where should site specific modules, themes and settings be kept? to move the settings file to the root folder where modules/ themes/ and profiles/ are also going at some point.

It would go for "default" - but not multisite settings files that would still go in the sites folder.

The existence of a sites.php can trigger trying to find multisite settings as suggested in #1055862: Require sites.php to opt-in for multi-site support/functionality