From 6b0793c04d9e0fe7b439b79f4615fe58a68ddfce Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Mon, 20 Aug 2012 09:43:07 -0700
Subject: [PATCH] Issue #1018324 by Albert Volkman, webbykat, disasm,  jhr,
 jorap: Add info and examples to docs on how to set up multi-site

---
 core/includes/bootstrap.inc        | 84 ++++++++++++------------------
 sites/default/default.settings.php | 40 ++++++++------
 sites/example.sites.php            | 70 ++++++++++++++-----------
 3 files changed, 100 insertions(+), 94 deletions(-)

diff --git a/core/includes/bootstrap.inc b/core/includes/bootstrap.inc
index e26cb365961c..f460155b5dfb 100644
--- a/core/includes/bootstrap.inc
+++ b/core/includes/bootstrap.inc
@@ -371,56 +371,12 @@ function timer_stop($name) {
 }
 
 /**
- * Finds the appropriate configuration directory.
+ * Returns the appropriate configuration directory.
  *
- * Finds a matching configuration directory by stripping the website's
- * hostname from left to right and pathname from right to left. The first
- * configuration file found will be used and the remaining ones will be ignored.
- * If no configuration file is found, return a default value '$confdir/default'.
- *
- * With a site located at http://www.example.com:8080/mysite/test/, the file,
- * settings.php, is searched for in the following directories:
- *
- * - $confdir/8080.www.example.com.mysite.test
- * - $confdir/www.example.com.mysite.test
- * - $confdir/example.com.mysite.test
- * - $confdir/com.mysite.test
- *
- * - $confdir/8080.www.example.com.mysite
- * - $confdir/www.example.com.mysite
- * - $confdir/example.com.mysite
- * - $confdir/com.mysite
- *
- * - $confdir/8080.www.example.com
- * - $confdir/www.example.com
- * - $confdir/example.com
- * - $confdir/com
- *
- * - $confdir/default
- *
- * If a file named sites.php is present in the $confdir, it will be loaded
- * prior to scanning for directories. It should define an associative array
- * named $sites, which maps domains to directories. It should be in the form
- * of:
- * @code
- * $sites = array(
- *   'The url to alias' => 'A directory within the sites directory'
- * );
- * @endcode
- * For example:
- * @code
- * $sites = array(
- *   'devexample.com' => 'example.com',
- *   'localhost.example' => 'example.com',
- * );
- * @endcode
- * The above array will cause Drupal to look for a directory named
- * "example.com" in the sites directory whenever a request comes from
- * "example.com", "devexample.com", or "localhost/example". That is useful
- * on development servers, where the domain name may not be the same as the
- * domain of the live server. Since Drupal stores file paths into the database
- * (files, system table, etc.) this will ensure the paths are correct while
- * accessed on development servers.
+ * Returns the configuration path based on the site's hostname, port, and
+ * pathname. Uses find_conf_path() to find the current configuration directory.
+ * See default.settings.php for examples on how the URL is converted to a
+ * directory.
  *
  * @param bool $require_settings
  *   Only configuration directories with an existing settings.php file
@@ -433,6 +389,8 @@ function timer_stop($name) {
  *
  * @return
  *   The path of the matching directory.
+ *
+ * @see default.settings.php
  */
 function conf_path($require_settings = TRUE, $reset = FALSE) {
   $conf = &drupal_static(__FUNCTION__, '');
@@ -453,15 +411,41 @@ function conf_path($require_settings = TRUE, $reset = FALSE) {
 /**
  * Finds the appropriate configuration directory for a given host and path.
  *
+ * Finds a matching configuration directory file by stripping the website's
+ * hostname from left to right and pathname from right to left. By default,
+ * the directory must contain a 'settings.php' file for it to match. If the
+ * parameter $require_settings is set to FALSE, then a directory without a
+ * 'settings.php' file will match as well. The first configuration
+ * file found will be used and the remaining ones will be ignored. If no
+ * configuration file is found, returns a default value '$confdir/default'. See
+ * default.settings.php for examples on how the URL is converted to a directory.
+ *
+ * If a file named sites.php is present in the $confdir, it will be loaded
+ * prior to scanning for directories. That file can define aliases in an
+ * associative array named $sites. The array is written in the format
+ * '<port>.<domain>.<path>' => 'directory'. As an example, to create a
+ * directory alias for http://www.drupal.org:8080/mysite/test whose configuration
+ * file is in sites/example.com, the array should be defined as:
+ * @code
+ * $sites = array(
+ *   '8080.www.drupal.org.mysite.test' => 'example.com',
+ * );
+ * @endcode
+ *
  * @param $http_host
  *   The hostname and optional port number, e.g. "www.example.com" or
  *   "www.example.com:8080".
  * @param $script_name
  *   The part of the url following the hostname, including the leading slash.
+ * @param $require_settings
+ *   Defaults to TRUE. If TRUE, then only match directories with a
+ *   'settings.php' file. Otherwise match any directory.
  *
  * @return
  *   The path of the matching configuration directory.
  *
+ * @see default.settings.php
+ * @see example.sites.php
  * @see conf_path()
  */
 function find_conf_path($http_host, $script_name, $require_settings = TRUE) {
@@ -697,7 +681,7 @@ function unicode_check() {
 function drupal_settings_initialize() {
   global $base_url, $base_path, $base_root, $script_path;
 
-  // Export the following settings.php variables to the global namespace
+  // Export these settings.php variables to the global namespace.
   global $databases, $cookie_domain, $conf, $installed_profile, $update_free_access, $db_url, $db_prefix, $drupal_hash_salt, $is_https, $base_secure_url, $base_insecure_url, $config_directory_name;
   $conf = array();
 
diff --git a/sites/default/default.settings.php b/sites/default/default.settings.php
index ba17413628a9..2c1263895fa2 100755
--- a/sites/default/default.settings.php
+++ b/sites/default/default.settings.php
@@ -5,41 +5,51 @@
  * Drupal site-specific configuration file.
  *
  * IMPORTANT NOTE:
- * This file may have been set to read-only by the Drupal installation
- * program. If you make changes to this file, be sure to protect it again
- * after making your modifications. Failure to remove write permissions
- * to this file is a security risk.
- *
- * The configuration file to be loaded is based upon the rules below.
- *
- * The configuration directory will be discovered by stripping the
- * website's hostname from left to right and pathname from right to
- * left. The first configuration file found will be used and any
- * others will be ignored. If no other configuration file is found
- * then the default configuration file at 'sites/default' will be used.
+ * This file may have been set to read-only by the Drupal installation program.
+ * If you make changes to this file, be sure to protect it again after making
+ * your modifications. Failure to remove write permissions to this file is a
+ * security risk.
+ *
+ * The configuration file to be loaded is based upon the rules below. However
+ * if the multisite aliasing file named sites/sites.php is present, it will be
+ * loaded, and the aliases in the array $sites will override the default
+ * directory rules below. See sites/example.sites.php for more information about
+ * aliases.
+ *
+ * The configuration directory will be discovered by stripping the website's
+ * hostname from left to right and pathname from right to left. The first
+ * configuration file found will be used and any others will be ignored. If no
+ * other configuration file is found then the default configuration file at
+ * 'sites/default' will be used.
  *
  * For example, for a fictitious site installed at
- * http://www.drupal.org/mysite/test/, the 'settings.php'
- * is searched in the following directories:
+ * http://www.drupal.org:8080/mysite/test/, the 'settings.php' file is searched
+ * for in the following directories:
  *
+ * - sites/8080.www.drupal.org.mysite.test
  * - sites/www.drupal.org.mysite.test
  * - sites/drupal.org.mysite.test
  * - sites/org.mysite.test
  *
+ * - sites/8080.www.drupal.org.mysite
  * - sites/www.drupal.org.mysite
  * - sites/drupal.org.mysite
  * - sites/org.mysite
  *
+ * - sites/8080.www.drupal.org
  * - sites/www.drupal.org
  * - sites/drupal.org
  * - sites/org
  *
  * - sites/default
  *
- * If you are installing on a non-standard port number, prefix the
+ * Note that if you are installing on a non-standard port number, prefix the
  * hostname with that number. For example,
  * http://www.drupal.org:8080/mysite/test/ could be loaded from
  * sites/8080.www.drupal.org.mysite.test/.
+ *
+ * @see example.sites.php
+ * @see conf_path()
  */
 
 /**
diff --git a/sites/example.sites.php b/sites/example.sites.php
index 08c1020ff439..2b00151d7336 100644
--- a/sites/example.sites.php
+++ b/sites/example.sites.php
@@ -4,40 +4,52 @@
  * @file
  * Configuration file for Drupal's multi-site directory aliasing feature.
  *
- * Drupal searches for an appropriate configuration directory based on the
- * website's hostname and pathname. A detailed description of the rules for
- * discovering the configuration directory can be found in the comment
- * documentation in 'sites/default/default.settings.php'.
+ * This file allows you to define a set of aliases that map hostnames, ports, and
+ * pathnames to configuration directories in the sites directory. These aliases
+ * are loaded prior to scanning for directories, and they are exempt from the
+ * normal discovery rules. See default.settings.php to view how Drupal discovers
+ * the configuration directory when no alias is found.
  *
- * This file allows you to define a set of aliases that map hostnames and
- * pathnames to configuration directories. These aliases are loaded prior to
- * scanning for directories, and they are exempt from the normal discovery
- * rules. The aliases are defined in an associative array named $sites, which
- * should look similar to the following:
+ * Aliases are useful on development servers, where the domain name may not be
+ * the same as the domain of the live server. Since Drupal stores file paths in
+ * the database (files, system table, etc.) this will ensure the paths are
+ * correct when the site is deployed to a live server.
  *
+ * To use this file, copy and rename it such that its path plus filename is
+ * 'sites/sites.php'. If you don't need to use multi-site directory aliasing,
+ * then you can safely ignore this file, and Drupal will ignore it too.
+ *
+ * Aliases are defined in an associative array named $sites. The array is
+ * written in the format: '<port>.<domain>.<path>' => 'directory'. As an
+ * example, to map http://www.drupal.org:8080/mysite/test to the configuration
+ * directory sites/example.com, the array should be defined as:
+ * @code
  * $sites = array(
- *   'devexample.com' => 'example.com',
- *   'localhost.example' => 'example.com',
+ *   '8080.www.drupal.org.mysite.test' => 'example.com',
  * );
+ * @endcode
+ * The URL, http://www.drupal.org:8080/mysite/test/, could be a symbolic link or
+ * an Apache Alias directive that points to the Drupal root containing
+ * index.php. An alias could also be created for a subdomain. See the
+ * @link http://drupal.org/documentation/install online Drupal installation guide @endlink
+ * for more information on setting up domains, subdomains, and subdirectories.
  *
- * The above array will cause Drupal to look for a directory named
- * "example.com" in the sites directory whenever a request comes from
- * "example.com", "devexample.com", or "localhost/example". That is useful
- * on development servers, where the domain name may not be the same as the
- * domain of the live server. Since Drupal stores file paths into the database
- * (files, system table, etc.) this will ensure the paths are correct while
- * accessed on development servers.
+ * The following examples look for a site configuration in sites/example.com:
+ * @code
+ * URL: http://dev.drupal.org
+ * $sites['dev.drupal.org'] = 'example.com';
  *
- * To use this file, copy and rename it such that its path plus filename is
- * 'sites/sites.php'. If you don't need to use multi-site directory aliasing,
- * then you can safely ignore this file, and Drupal will ignore it too.
- */
-
-/**
- * Multi-site directory aliasing:
+ * URL: http://localhost/example
+ * $sites['localhost.example'] = 'example.com';
+ *
+ * URL: http://localhost:8080/example
+ * $sites['8080.localhost.example'] = 'example.com';
+ *
+ * URL: http://www.drupal.org:8080/mysite/test/
+ * $sites['8080.www.drupal.org.mysite.test'] = 'example.com';
+ * @endcode
  *
- * Edit the lines below to define directory aliases. Remove the leading hash
- * signs to enable.
+ * @see default.settings.php
+ * @see conf_path()
+ * @see http://drupal.org/documentation/install/multi-site
  */
-# $sites['devexample.com'] = 'example.com';
-# $sites['localhost.example'] = 'example.com';
-- 
GitLab