From 7043f6d7abf3b3f94341bda58ca17a447167fb17 Mon Sep 17 00:00:00 2001 From: Jennifer Hodgdon Date: Fri, 24 Aug 2012 11:15:37 -0700 Subject: Issue #1018324 by Albert Volkman, webbykat, disasm, jhr, jorap: Fix up documentation for multisite --- includes/bootstrap.inc | 58 +++++-------------------------- sites/default/default.settings.php | 40 ++++++++++++++-------- sites/example.sites.php | 70 ++++++++++++++++++++++---------------- 3 files changed, 74 insertions(+), 94 deletions(-) diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc index 709666714..03e58802a 100644 --- a/includes/bootstrap.inc +++ b/includes/bootstrap.inc @@ -498,56 +498,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 @@ -560,6 +516,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__, ''); @@ -731,7 +689,7 @@ function drupal_valid_http_host($host) { function drupal_settings_initialize() { global $base_url, $base_path, $base_root; - // 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; $conf = array(); diff --git a/sites/default/default.settings.php b/sites/default/default.settings.php index 30699a0a2..0ae34a2bb 100644 --- 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 08c1020ff..2b00151d7 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: '..' => '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'; -- cgit v1.2.3