Index: includes/bootstrap.inc =================================================================== RCS file: /cvs/drupal/drupal/includes/bootstrap.inc,v retrieving revision 1.466 diff -u -p -r1.466 bootstrap.inc --- includes/bootstrap.inc 19 Feb 2011 16:59:43 -0000 1.466 +++ includes/bootstrap.inc 24 Feb 2011 16:50:53 -0000 @@ -162,8 +162,7 @@ define('DRUPAL_BOOTSTRAP_PAGE_HEADER', 5 define('DRUPAL_BOOTSTRAP_LANGUAGE', 6); /** - * Final bootstrap phase: Drupal is fully loaded; validate and fix - * input data. + * Final bootstrap phase: Drupal is fully loaded; validate and fix input data. */ define('DRUPAL_BOOTSTRAP_FULL', 7); @@ -178,8 +177,9 @@ define('DRUPAL_ANONYMOUS_RID', 1); define('DRUPAL_AUTHENTICATED_RID', 2); /** - * The number of bytes in a kilobyte. For more information, visit - * http://en.wikipedia.org/wiki/Kilobyte. + * The number of bytes in a kilobyte. + * + * For more information, visit http://en.wikipedia.org/wiki/Kilobyte. */ define('DRUPAL_KILOBYTE', 1024); @@ -248,8 +248,10 @@ define('REGISTRY_WRITE_LOOKUP_CACHE', 2) define('DRUPAL_PHP_FUNCTION_PATTERN', '[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*'); /** - * Start the timer with the specified name. If you start and stop the same - * timer multiple times, the measured intervals will be accumulated. + * Starts the timer with the specified name. + * + * If you start and stop the same timer multiple times, the measured intervals + * will be accumulated. * * @param name * The name of the timer. @@ -262,10 +264,11 @@ function timer_start($name) { } /** - * Read the current timer value without stopping the timer. + * Reads the current timer value without stopping the timer. * * @param name * The name of the timer. + * * @return * The current timer value in ms. */ @@ -285,10 +288,11 @@ function timer_read($name) { } /** - * Stop the timer with the specified name. + * Stops the timer with the specified name. * * @param name * The name of the timer. + * * @return * A timer array. The array contains the number of times the timer has been * started and stopped (count) and the accumulated timer value in ms (time). @@ -312,7 +316,7 @@ function timer_stop($name) { } /** - * Find the appropriate configuration directory. + * Finds the appropriate configuration directory. * * Try finding a matching configuration directory by stripping the website's * hostname from left to right and pathname from right to left. The first @@ -320,8 +324,8 @@ function timer_stop($name) { * configuration file is found, return a default value '$confdir/default'. * * Example for a fictitious site installed at - * http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in - * the following directories: + * http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in the + * following directories: * * 1. $confdir/8080.www.drupal.org.mysite.test * 2. $confdir/www.drupal.org.mysite.test @@ -340,38 +344,39 @@ function timer_stop($name) { * * 13. $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: - * + * 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. + * 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. * * @param $require_settings - * Only configuration directories with an existing settings.php file - * will be recognized. Defaults to TRUE. During initial installation, - * this is set to FALSE so that Drupal can detect a matching directory, - * then create a new settings.php file in it. + * (optional) Only configuration directories with an existing settings.php file + * will be recognized. Defaults to TRUE. During initial installation, this is + * set to FALSE so that Drupal can detect a matching directory, then create a + * new settings.php file in it. * @param reset - * Force a full search for matching directories even if one had been + * (optional) Force a full search for matching directories even if one had been * found previously. + * * @return * The path of the matching directory. */ @@ -409,22 +414,22 @@ function conf_path($require_settings = T } /** - * Set appropriate server variables needed for command line scripts to work. + * Sets appropriate server variables needed for command line scripts to work. * * This function can be called by command line scripts before bootstrapping - * Drupal, to ensure that the page loads with the desired server parameters. - * This is because many parts of Drupal assume that they are running in a web - * browser and therefore use information from the global PHP $_SERVER variable - * that does not get set when Drupal is run from the command line. + * Drupal, to ensure that the page loads with the desired server parameters. This + * is because many parts of Drupal assume that they are running in a web browser + * and therefore use information from the global PHP $_SERVER variable that does + * not get set when Drupal is run from the command line. * * In many cases, the default way in which this function populates the $_SERVER - * variable is sufficient, and it can therefore be called without passing in - * any input. However, command line scripts running on a multisite installation - * (or on any installation that has settings.php stored somewhere other than - * the sites/default folder) need to pass in the URL of the site to allow - * Drupal to detect the correct location of the settings.php file. Passing in - * the 'url' parameter is also required for functions like request_uri() to - * return the expected values. + * variable is sufficient, and it can therefore be called without passing in any + * input. However, command line scripts running on a multisite installation (or + * on any installation that has settings.php stored somewhere other than the + * sites/default folder) need to pass in the URL of the site to allow Drupal to + * detect the correct location of the settings.php file. Passing in the 'url' + * parameter is also required for functions like request_uri() to return the + * expected values. * * Most other parameters do not need to be passed in, but may be necessary in * some cases; for example, if Drupal's ip_address() function needs to return @@ -432,11 +437,11 @@ function conf_path($require_settings = T * script should pass in the desired value via the 'REMOTE_ADDR' key. * * @param $variables - * (optional) An associative array of variables within $_SERVER that should - * be replaced. If the special element 'url' is provided in this array, it - * will be used to populate some of the server defaults; it should be set to - * the URL of the current page request, excluding any $_GET request but - * including the script name (e.g., http://www.example.com/mysite/index.php). + * (optional) An associative array of variables within $_SERVER that should be + * replaced. If the special element 'url' is provided in this array, it will be + * used to populate some of the server defaults; it should be set to the URL of + * the current page request, excluding any $_GET request but including the + * script name (e.g., http://www.example.com/mysite/index.php). * * @see conf_path() * @see request_uri() @@ -454,9 +459,8 @@ function drupal_override_server_variable } unset($variables['url']); } - // Define default values for $_SERVER keys. These will be used if $_SERVER - // does not already define them and no other values are passed in to this - // function. + // Define default values for $_SERVER keys. These will be used if $_SERVER does + // not already define them and no other values are passed in to this function. $defaults = array( 'HTTP_HOST' => 'localhost', 'SCRIPT_NAME' => NULL, @@ -471,7 +475,7 @@ function drupal_override_server_variable } /** - * Initialize PHP environment. + * Initializes the PHP environment. */ function drupal_environment_initialize() { if (!isset($_SERVER['HTTP_REFERER'])) { @@ -482,8 +486,8 @@ function drupal_environment_initialize() } if (isset($_SERVER['HTTP_HOST'])) { - // As HTTP_HOST is user input, ensure it only contains characters allowed - // in hostnames. See RFC 952 (and RFC 2181). + // As HTTP_HOST is user input, ensure it only contains characters allowed in + // hostnames. See RFC 952 (and RFC 2181). // $_SERVER['HTTP_HOST'] is lowercased here per specifications. $_SERVER['HTTP_HOST'] = strtolower($_SERVER['HTTP_HOST']); if (!drupal_valid_http_host($_SERVER['HTTP_HOST'])) { @@ -498,11 +502,11 @@ function drupal_environment_initialize() $_SERVER['HTTP_HOST'] = ''; } - // When clean URLs are enabled, emulate ?q=foo/bar using REQUEST_URI. It is - // not possible to append the query string using mod_rewrite without the B - // flag (this was added in Apache 2.2.8), because mod_rewrite unescapes the - // path before passing it on to PHP. This is a problem when the path contains - // e.g. "&" or "%" that have special meanings in URLs and must be encoded. + // When clean URLs are enabled, emulate ?q=foo/bar using REQUEST_URI. It is not + // possible to append the query string using mod_rewrite without the B flag + // (this was added in Apache 2.2.8), because mod_rewrite unescapes the path + // before passing it on to PHP. This is a problem when the path contains e.g. + // "&" or "%" that have special meanings in URLs and must be encoded. $_GET['q'] = request_path(); // Enforce E_ALL, but allow users to set levels not part of E_ALL. @@ -530,7 +534,7 @@ function drupal_environment_initialize() } /** - * Validate that a hostname (for example $_SERVER['HTTP_HOST']) is safe. + * Validates that a hostname (for example $_SERVER['HTTP_HOST']) is safe. * * @return * TRUE if only containing valid characters, or FALSE otherwise. @@ -540,8 +544,9 @@ function drupal_valid_http_host($host) { } /** - * Loads the configuration and sets the base URL, cookie domain, and - * session name correctly. + * Loads the configuration from settings.php. + * + * Also sets the base URL, cookie domain, and session name. */ function drupal_settings_initialize() { global $base_url, $base_path, $base_root; @@ -573,8 +578,8 @@ function drupal_settings_initialize() { $base_url = $base_root; - // $_SERVER['SCRIPT_NAME'] can, in contrast to $_SERVER['PHP_SELF'], not - // be modified by a visitor. + // $_SERVER['SCRIPT_NAME'] can, in contrast to $_SERVER['PHP_SELF'], not be + // modified by a visitor. if ($dir = rtrim(dirname($_SERVER['SCRIPT_NAME']), '\/')) { $base_path = $dir; $base_url .= $base_path; @@ -592,11 +597,11 @@ function drupal_settings_initialize() { $session_name = $cookie_domain; } else { - // Otherwise use $base_url as session name, without the protocol - // to use the same session identifiers across http and https. + // Otherwise use $base_url as session name, without the protocol to use the + // same session identifiers across http and https. list( , $session_name) = explode('://', $base_url, 2); - // HTTP_HOST can be modified by a visitor, but we already sanitized it - // in drupal_settings_initialize(). + // HTTP_HOST can be modified by a visitor, but we already sanitized it in + // drupal_settings_initialize(). if (!empty($_SERVER['HTTP_HOST'])) { $cookie_domain = $_SERVER['HTTP_HOST']; // Strip leading periods, www., and port numbers from cookie domain. @@ -609,16 +614,17 @@ function drupal_settings_initialize() { } } // Per RFC 2109, cookie domains must contain at least one dot other than the - // first. For hosts such as 'localhost' or IP Addresses we don't set a cookie domain. + // first. For hosts such as 'localhost' or IP Addresses we don't set a cookie + // domain. if (count(explode('.', $cookie_domain)) > 2 && !is_numeric(str_replace('.', '', $cookie_domain))) { ini_set('session.cookie_domain', $cookie_domain); } - // To prevent session cookies from being hijacked, a user can configure the - // SSL version of their website to only transfer session cookies via SSL by - // using PHP's session.cookie_secure setting. The browser will then use two - // separate session cookies for the HTTPS and HTTP versions of the site. So we - // must use different session identifiers for HTTPS and HTTP to prevent a - // cookie collision. + // To prevent session cookies from being hijacked, a user can configure the SSL + // version of their website to only transfer session cookies via SSL by using + // PHP's session.cookie_secure setting. The browser will then use two separate + // session cookies for the HTTPS and HTTP versions of the site. So we must use + // different session identifiers for HTTPS and HTTP to prevent a cookie + // collision. if ($is_https) { ini_set('session.cookie_secure', TRUE); } @@ -627,29 +633,30 @@ function drupal_settings_initialize() { } /** - * Returns and optionally sets the filename for a system item (module, - * theme, etc.). The filename, whether provided, cached, or retrieved - * from the database, is only returned if the file exists. - * - * This function plays a key role in allowing Drupal's resources (modules - * and themes) to be located in different places depending on a site's - * configuration. For example, a module 'foo' may legally be be located - * in any of these three places: + * Returns and optionally sets the filename for a module, theme, etc. + * + * The filename, whether provided, cached, or retrieved from the database, is + * only returned if the file exists. + * + * This function plays a key role in allowing Drupal's resources (modules and + * themes) to be located in different places depending on a site's configuration. + * For example, a module 'foo' may legally be be located in any of these three + * places: * * modules/foo/foo.module * sites/all/modules/foo/foo.module * sites/example.com/modules/foo/foo.module * - * Calling drupal_get_filename('module', 'foo') will give you one of - * the above, depending on where the module is located. + * Calling drupal_get_filename('module', 'foo') will give you one of the above, + * depending on where the module is located. * * @param $type * The type of the item (i.e. theme, theme_engine, module, profile). * @param $name * The name of the item for which the filename is requested. * @param $filename - * The filename of the item if it is to be set explicitly rather - * than by consulting the database. + * The filename of the item if it is to be set explicitly rather than by + * consulting the database. * * @return * The filename of the requested item. @@ -667,12 +674,12 @@ function drupal_get_filename($type, $nam $files[$type][$name] = $filename; } elseif (isset($files[$type][$name])) { - // nothing + // Do nothing. } - // Verify that we have an active database connection, before querying - // the database. This is required because this function is called both - // before we have a database connection (i.e. during installation) and - // when a database connection fails. + // Verify that we have an active database connection, before querying the + // database. This is required because this function is called both before we + // have a database connection (i.e. during installation) and when a database + // connection fails. else { try { if (function_exists('db_query')) { @@ -683,9 +690,9 @@ function drupal_get_filename($type, $nam } } catch (Exception $e) { - // The database table may not exist because Drupal is not yet installed, - // or the database might be down. We have a fallback for this case so we - // hide the error completely. + // The database table may not exist because Drupal is not yet installed, or + // the database might be down. We have a fallback for this case so we hide + // the error completely. } // Fallback to searching the filesystem if the database could not find the // file or the file returned by the database is not found. @@ -707,9 +714,9 @@ function drupal_get_filename($type, $nam require_once DRUPAL_ROOT . '/includes/common.inc'; } // Scan the appropriate directories for all files with the requested - // extension, not just the file we are currently looking for. This - // prevents unnecessary scans from being repeated when this function is - // called more than once in the same page request. + // extension, not just the file we are currently looking for. This prevents + // unnecessary scans from being repeated when this function is called more + // than once in the same page request. $matches = drupal_system_listing("/^" . DRUPAL_PHP_FUNCTION_PATTERN . "\.$extension$/", $dir, 'name', 0); foreach ($matches as $matched_name => $file) { $files[$type][$matched_name] = $file->uri; @@ -723,15 +730,24 @@ function drupal_get_filename($type, $nam } /** - * Load the persistent variable table. + * Loads the persistent variable table. * * The variable table is composed of values that have been saved in the table * with variable_set() as well as those explicitly specified in the configuration * file. + * + * @param $conf + * (optional) An array of variables to merge with the variables in the database + * and configuration file. The array keys are the variable names and the array + * values are the variable values. + * + * @return + * An array of variables. The array keys are the variable names and the array + * values are the variable values. */ function variable_initialize($conf = array()) { - // NOTE: caching the variables improves performance by 20% when serving - // cached pages. + // NOTE: caching the variables improves performance by 20% when serving cached + // pages. if ($cached = cache_get('variables', 'cache_bootstrap')) { $variables = $cached->data; } @@ -762,14 +778,14 @@ function variable_initialize($conf = arr /** * Returns a persistent variable. * - * Case-sensitivity of the variable_* functions depends on the database - * collation used. To avoid problems, always use lower case for persistent - * variable names. + * Case-sensitivity of the variable_* functions depends on the database collation + * used. To avoid problems, always use lower case for persistent variable names. * * @param $name * The name of the variable to return. * @param $default - * The default value to use if this variable has never been set. + * (optional) The default value to use if this variable has never been set. + * Defaults to NULL. * * @return * The value of the variable. @@ -786,9 +802,8 @@ function variable_get($name, $default = /** * Sets a persistent variable. * - * Case-sensitivity of the variable_* functions depends on the database - * collation used. To avoid problems, always use lower case for persistent - * variable names. + * Case-sensitivity of the variable_* functions depends on the database collation + * used. To avoid problems, always use lower case for persistent variable names. * * @param $name * The name of the variable to set. @@ -812,9 +827,8 @@ function variable_set($name, $value) { /** * Unsets a persistent variable. * - * Case-sensitivity of the variable_* functions depends on the database - * collation used. To avoid problems, always use lower case for persistent - * variable names. + * Case-sensitivity of the variable_* functions depends on the database collation + * used. To avoid problems, always use lower case for persistent variable names. * * @param $name * The name of the variable to undefine. @@ -834,16 +848,16 @@ function variable_del($name) { } /** - * Retrieve the current page from the cache. + * Retrieves the current page from the cache. * * Note: we do not serve cached pages to authenticated users, or to anonymous - * users when $_SESSION is non-empty. $_SESSION may contain status messages - * from a form submission, the contents of a shopping cart, or other user- - * specific content that should not be cached and displayed to other users. + * users when $_SESSION is non-empty. $_SESSION may contain status messages from + * a form submission, the contents of a shopping cart, or other user-specific + * content that should not be cached and displayed to other users. * * @param $check_only - * (optional) Set to TRUE to only return whether a previous call found a - * cache entry. + * (optional) Set to TRUE to only return whether a previous call found a cache + * entry. * * @return * The cache object, if the page was found in the cache, NULL otherwise. @@ -866,10 +880,10 @@ function drupal_page_get_cache($check_on } /** - * Determine the cacheability of the current page. + * Determines the cacheability of the current page. * * @param $allow_caching - * Set to FALSE if you want to prevent this page to get cached. + * (optional) Set to FALSE if you want to prevent this page from being cached. * * @return * TRUE if the current page can be cached, FALSE otherwise. @@ -885,7 +899,7 @@ function drupal_page_is_cacheable($allow } /** - * Invoke a bootstrap hook in all bootstrap modules that implement it. + * Invokes a bootstrap hook in all bootstrap modules that implement it. * * @param $hook * The name of the bootstrap hook to invoke. @@ -895,11 +909,10 @@ function drupal_page_is_cacheable($allow function bootstrap_invoke_all($hook) { // Bootstrap modules should have been loaded when this function is called, so // we don't need to tell module_list() to reset its internal list (and we - // therefore leave the first parameter at its default value of FALSE). We - // still pass in TRUE for the second parameter, though; in case this is the - // first time during the bootstrap that module_list() is called, we want to - // make sure that its internal cache is primed with the bootstrap modules - // only. + // therefore leave the first parameter at its default value of FALSE). We still + // pass in TRUE for the second parameter, though; in case this is the first + // time during the bootstrap that module_list() is called, we want to make sure + // that its internal cache is primed with the bootstrap modules only. foreach (module_list(FALSE, TRUE) as $module) { drupal_load('module', $module); module_invoke($module, $hook); @@ -907,8 +920,9 @@ function bootstrap_invoke_all($hook) { } /** - * Includes a file with the provided type and name. This prevents - * including a theme, engine, module, etc., more than once. + * Includes a file with the provided type and name. + * + * This prevents including a theme, engine, module, etc., more than once. * * @param $type * The type of item to load (i.e. theme, theme_engine, module). @@ -940,7 +954,7 @@ function drupal_load($type, $name) { } /** - * Set an HTTP response header for the current page. + * Sets an HTTP response header for the current page. * * Note: When sending a Content-Type header, always include a 'charset' type, * too. This is necessary to avoid security bugs (e.g. UTF-7 XSS). @@ -948,11 +962,12 @@ function drupal_load($type, $name) { * @param $name * The HTTP header name, or the special 'Status' header name. * @param $value - * The HTTP header value; if equal to FALSE, the specified header is unset. - * If $name is 'Status', this is expected to be a status code followed by a - * reason phrase, e.g. "404 Not Found". + * The HTTP header value; if equal to FALSE, the specified header is unset. If + * $name is 'Status', this is expected to be a status code followed by a reason + * phrase, e.g. "404 Not Found". * @param $append - * Whether to append the value to an existing header or to replace it. + * (optional) Set to TRUE to append the value to an existing header, or FALSE + * to replace the header. Defaults to FALSE. */ function drupal_add_http_header($name, $value, $append = FALSE) { // The headers as name/value pairs. @@ -976,11 +991,12 @@ function drupal_add_http_header($name, $ } /** - * Get the HTTP response headers for the current page. + * Gets the HTTP response headers for the current page. * * @param $name - * An HTTP header name. If omitted, all headers are returned as name/value - * pairs. If an array value is FALSE, the header has been unset. + * (optional) An HTTP header name. If omitted, all headers are returned as + * name/value pairs. If an array value is FALSE, the header has been unset. + * * @return * A string containing the header value, or FALSE if the header has been set, * or NULL if the header has not been set. @@ -997,8 +1013,17 @@ function drupal_get_http_header($name = } /** + * Sets the preferred header name. + * * Header names are case-insensitive, but for maximum compatibility they should * follow "common form" (see RFC 2617, section 4.2). + * + * @param $name + * (optional) The header name to set. If ommitted, an array of all header names + * that have been set is returned. + * + * @return + * If $name is omitted, an array of all header names that have been set. */ function _drupal_set_preferred_header_name($name = NULL) { static $header_names = array(); @@ -1010,14 +1035,16 @@ function _drupal_set_preferred_header_na } /** - * Send the HTTP response headers previously set using drupal_add_http_header(). - * Add default headers, unless they have been replaced or unset using + * Sends the HTTP response headers previously set by drupal_add_http_header(). + * + * Also adds default headers, unless they have been replaced or unset using * drupal_add_http_header(). * * @param $default_headers - * An array of headers as name/value pairs. - * @param $single - * If TRUE and headers have already be sent, send only the specified header. + * (optional) An array of headers as name/value pairs. + * @param $only_default + * (optional) If TRUE and headers have already been sent, send only the + * specified header. */ function drupal_send_headers($default_headers = array(), $only_default = FALSE) { $headers_sent = &drupal_static(__FUNCTION__, FALSE); @@ -1047,29 +1074,27 @@ function drupal_send_headers($default_he } /** - * Set HTTP headers in preparation for a page response. + * Sets HTTP headers in preparation for a page response. * * Authenticated users are always given a 'no-cache' header, and will fetch a * fresh page on every request. This prevents authenticated users from seeing * locally cached pages. * - * Also give each page a unique ETag. This will force clients to include both - * an If-Modified-Since header and an If-None-Match header when doing - * conditional requests for the page (required by RFC 2616, section 13.3.4), - * making the validation more robust. This is a workaround for a bug in Mozilla - * Firefox that is triggered when Drupal's caching is enabled and the user - * accesses Drupal via an HTTP proxy (see - * https://bugzilla.mozilla.org/show_bug.cgi?id=269303): When an authenticated - * user requests a page, and then logs out and requests the same page again, - * Firefox may send a conditional request based on the page that was cached - * locally when the user was logged in. If this page did not have an ETag + * Also give each page a unique ETag. This will force clients to include both an + * If-Modified-Since header and an If-None-Match header when doing conditional + * requests for the page (required by RFC 2616, section 13.3.4), making the + * validation more robust. This is a workaround for a bug in Mozilla Firefox that + * is triggered when Drupal's caching is enabled and the user accesses Drupal via + * an HTTP proxy (see https://bugzilla.mozilla.org/show_bug.cgi?id=269303): When + * an authenticated user requests a page, and then logs out and requests the same + * page again, Firefox may send a conditional request based on the page that was + * cached locally when the user was logged in. If this page did not have an ETag * header, the request only contains an If-Modified-Since header. The date will * be recent, because with authenticated users the Last-Modified header always * refers to the time of the request. If the user accesses Drupal via a proxy * server, and the proxy already has a cached copy of the anonymous page with an * older Last-Modified date, the proxy may respond with 304 Not Modified, making - * the client think that the anonymous and authenticated pageviews are - * identical. + * the client think that the anonymous and authenticated pageviews are identical. * * @see drupal_page_set_cache() */ @@ -1090,15 +1115,18 @@ function drupal_page_header() { } /** - * Set HTTP headers in preparation for a cached page response. + * Sets HTTP headers in preparation for a cached page response. * * The headers allow as much as possible in proxies and browsers without any - * particular knowledge about the pages. Modules can override these headers - * using drupal_add_http_header(). + * particular knowledge about the pages. Modules can override these headers using + * drupal_add_http_header(). + * + * If the request is conditional (using If-Modified-Since and If-None-Match), and + * the conditions match those currently in the cache, a 304 Not Modified response + * is sent. * - * If the request is conditional (using If-Modified-Since and If-None-Match), - * and the conditions match those currently in the cache, a 304 Not Modified - * response is sent. + * @param $cache + * A cache object as returned by cache_get(). */ function drupal_serve_page_from_cache(stdClass $cache) { // Negotiate whether to use compression. @@ -1114,8 +1142,8 @@ function drupal_serve_page_from_cache(st foreach ($cache->data['headers'] as $name => $value) { // In the case of a 304 response, certain headers must be sent, and the - // remaining may not (see RFC 2616, section 10.3.5). Do not override - // headers set in hook_boot(). + // remaining may not (see RFC 2616, section 10.3.5). Do not override headers + // set in hook_boot(). $name_lower = strtolower($name); if (in_array($name_lower, array('content-location', 'expires', 'cache-control', 'vary')) && !isset($hook_boot_headers[$name_lower])) { drupal_add_http_header($name, $value); @@ -1123,12 +1151,12 @@ function drupal_serve_page_from_cache(st } } - // If a cache is served from a HTTP proxy without hitting the web server, - // the boot and exit hooks cannot be fired, so only allow caching in - // proxies if boot hooks are disabled. If the client send a session cookie, - // do not bother caching the page in a public proxy, because the cached copy - // will only be served to that particular user due to Vary: Cookie, unless - // the Vary header has been replaced or unset in hook_boot() (see below). + // If a cache is served from a HTTP proxy without hitting the web server, the + // boot and exit hooks cannot be fired, so only allow caching in proxies if + // boot hooks are disabled. If the client send a session cookie, do not bother + // caching the page in a public proxy, because the cached copy will only be + // served to that particular user due to Vary: Cookie, unless the Vary header + // has been replaced or unset in hook_boot() (see below). $max_age = !variable_get('page_cache_invoke_hooks', TRUE) && (!isset($_COOKIE[session_name()]) || isset($hook_boot_headers['vary'])) ? variable_get('page_cache_maximum_age', 0) : 0; $default_headers['Cache-Control'] = 'public, max-age=' . $max_age; @@ -1155,10 +1183,10 @@ function drupal_serve_page_from_cache(st $default_headers['Last-Modified'] = gmdate(DATE_RFC1123, $cache->created); - // HTTP/1.0 proxies does not support the Vary header, so prevent any caching - // by sending an Expires date in the past. HTTP/1.1 clients ignores the - // Expires header if a Cache-Control: max-age= directive is specified (see RFC - // 2616, section 14.9.3). + // HTTP/1.0 proxies does not support the Vary header, so prevent any caching by + // sending an Expires date in the past. HTTP/1.1 clients ignores the Expires + // header if a Cache-Control: max-age= directive is specified (see RFC 2616, + // section 14.9.3). $default_headers['Expires'] = 'Sun, 19 Nov 1978 05:00:00 GMT'; drupal_send_headers($default_headers); @@ -1183,8 +1211,8 @@ function drupal_serve_page_from_cache(st header('Content-Encoding: gzip'); } else { - // The client does not support compression, so unzip the data in the - // cache. Strip the gzip header and run uncompress. + // The client does not support compression, so unzip the data in the cache. + // Strip the gzip header and run uncompress. $cache->data['body'] = gzinflate(substr(substr($cache->data['body'], 10), 0, -8)); } } @@ -1194,7 +1222,10 @@ function drupal_serve_page_from_cache(st } /** - * Define the critical hooks that force modules to always be loaded. + * Defines the critical hooks that force modules to always be loaded. + * + * @return + * An array of bootstrap hooks. */ function bootstrap_hooks() { return array('boot', 'exit', 'watchdog', 'language_init'); @@ -1203,20 +1234,24 @@ function bootstrap_hooks() { /** * Unserializes and appends elements from a serialized string. * - * @param $obj + * @param $object * The object to which the elements are appended. * @param $field - * The attribute of $obj whose value should be unserialized. + * (optional) The attribute of $object whose value should be unserialized. + * Defaults to 'data'. + * + * @return + * The object, with the appended elements. */ -function drupal_unpack($obj, $field = 'data') { - if ($obj->$field && $data = unserialize($obj->$field)) { +function drupal_unpack($object, $field = 'data') { + if ($object->$field && $data = unserialize($object->$field)) { foreach ($data as $key => $value) { - if (!empty($key) && !isset($obj->$key)) { - $obj->$key = $value; + if (!empty($key) && !isset($object->$key)) { + $object->$key = $value; } } } - return $obj; + return $object; } /** @@ -1229,9 +1264,9 @@ function drupal_unpack($obj, $field = 'd * to enable a fully-translatable site, it is important that all human-readable * text that will be displayed on the site or sent to a user is passed through * the t() function, or a related function. See the - * @link http://drupal.org/node/322729 Localization API @endlink pages for - * more information, including recommendations on how to break up or not - * break up strings for translation. + * @link http://drupal.org/node/322729 Localization API @endlink pages for more + * information, including recommendations on how to break up or not break up + * strings for translation. * * You should never use t() to translate variables, such as calling * @code t($text); @endcode, unless the text that the variable holds has been @@ -1246,18 +1281,18 @@ function drupal_unpack($obj, $field = 'd * $text = t("@name's blog", array('@name' => format_username($account))); * @endcode * Basically, you can put variables like @name into your string, and t() will - * substitute their sanitized values at translation time (see $args below or - * the Localization API pages referenced above for details). Translators can - * then rearrange the string as necessary for the language (e.g., in Spanish, - * it might be "blog de @name"). + * substitute their sanitized values at translation time (see $args below or the + * Localization API pages referenced above for details). Translators can then + * rearrange the string as necessary for the language (e.g., in Spanish, it might + * be "blog de @name"). * * @param $string * A string containing the English string to translate. * @param $args - * An associative array of replacements to make after translation. - * Occurrences in $string of any key in $args are replaced with the - * corresponding value, after sanitization. The sanitization function depends - * on the first character of the key: + * An associative array of replacements to make after translation. Occurrences + * in $string of any key in $args are replaced with the corresponding value, + * after sanitization. The sanitization function depends on the first character + * of the key: * - !variable: Inserted as is. Use this for text that has already been * sanitized. * - @variable: Escaped to HTML using check_plain(). Use this for anything @@ -1330,7 +1365,7 @@ function t($string, array $args = array( } /** - * Encode special characters in a plain-text string for display as HTML. + * Encodes special characters in a plain-text string for display as HTML. * * Also validates strings as UTF-8 to prevent cross site scripting attacks on * Internet Explorer 6. @@ -1339,8 +1374,8 @@ function t($string, array $args = array( * The text to be checked or processed. * * @return - * An HTML safe version of $text, or an empty string if $text is not - * valid UTF-8. + * An HTML safe version of $text, or an empty string if $text is not valid + * UTF-8. * * @see drupal_validate_utf8() * @ingroup sanitization @@ -1352,23 +1387,23 @@ function check_plain($text) { /** * Checks whether a string is valid UTF-8. * - * All functions designed to filter input should use drupal_validate_utf8 - * to ensure they operate on valid UTF-8 strings to prevent bypass of the - * filter. - * - * When text containing an invalid UTF-8 lead byte (0xC0 - 0xFF) is presented - * as UTF-8 to Internet Explorer 6, the program may misinterpret subsequent - * bytes. When these subsequent bytes are HTML control characters such as - * quotes or angle brackets, parts of the text that were deemed safe by filters - * end up in locations that are potentially unsafe; An onerror attribute that - * is outside of a tag, and thus deemed safe by a filter, can be interpreted - * by the browser as if it were inside the tag. + * All functions designed to filter input should use drupal_validate_utf8 to + * ensure they operate on valid UTF-8 strings to prevent bypass of the filter. + * + * When text containing an invalid UTF-8 lead byte (0xC0 - 0xFF) is presented as + * UTF-8 to Internet Explorer 6, the program may misinterpret subsequent bytes. + * When these subsequent bytes are HTML control characters such as quotes or + * angle brackets, parts of the text that were deemed safe by filters end up in + * locations that are potentially unsafe; An onerror attribute that is outside of + * a tag, and thus deemed safe by a filter, can be interpreted by the browser as + * if it were inside the tag. * * The function does not return FALSE for strings containing character codes * above U+10FFFF, even though these are prohibited by RFC 3629. * * @param $text * The text to check. + * * @return * TRUE if the text is valid UTF-8, FALSE if not. */ @@ -1377,14 +1412,19 @@ function drupal_validate_utf8($text) { return TRUE; } // With the PCRE_UTF8 modifier 'u', preg_match() fails silently on strings - // containing invalid UTF-8 byte sequences. It does not reject character - // codes above U+10FFFF (represented by 4 or more octets), though. + // containing invalid UTF-8 byte sequences. It does not reject character codes + // above U+10FFFF (represented by 4 or more octets), though. return (preg_match('/^./us', $text) == 1); } /** - * Since $_SERVER['REQUEST_URI'] is only available on Apache, we - * generate an equivalent using other environment variables. + * Returns the request URI. + * + * Since $_SERVER['REQUEST_URI'] is only available on Apache, we generate an + * equivalent using other environment variables. + * + * @return + * A string containing the request URI. */ function request_uri() { @@ -1409,9 +1449,9 @@ function request_uri() { } /** - * Log an exception. + * Logs an exception. * - * This is a wrapper function for watchdog() which automatically decodes an + * This is a wrapper function for watchdog(), which automatically decodes an * exception. * * @param $type @@ -1419,15 +1459,16 @@ function request_uri() { * @param $exception * The exception that is going to be logged. * @param $message - * The message to store in the log. If empty, a text that contains all useful - * information about the passed in exception is used. + * (optional) The message to store in the log. If empty, a string that contains + * all useful information about the passed-in exception is used. * @param $variables - * Array of variables to replace in the message on display. Defaults to the - * return value of drupal_decode_exception(). + * (optional) Array of variables to replace in the message on display. Defaults + * to the return value of drupal_decode_exception(). * @param $severity - * The severity of the message, as per RFC 3164. + * (optional) The severity of the message, as per RFC 3164. Defaults to + * WATCHDOG_ERROR. * @param $link - * A link to associate with the message. + * (optional) A link to associate with the message. * * @see watchdog() * @see drupal_decode_exception() @@ -1450,26 +1491,25 @@ function watchdog_exception($type, Excep } /** - * Log a system message. + * Logs a system message. * * @param $type * The category to which this message belongs. Can be any string, but the * general practice is to use the name of the module calling watchdog(). * @param $message - * The message to store in the log. Keep $message translatable - * by not concatenating dynamic values into it! Variables in the - * message should be added by using placeholder strings alongside - * the variables argument to declare the value of the placeholders. - * See t() for documentation on how $message and $variables interact. + * The message to store in the log. Keep $message translatable by not + * concatenating dynamic values into it! Variables in the message should be + * added by using placeholder strings alongside the variables argument to + * declare the value of the placeholders. See t() for documentation on how + * $message and $variables interact. * @param $variables - * Array of variables to replace in the message on display or - * NULL if message is already translated or not possible to - * translate. + * (optional) Array of variables to replace in the message on display, or NULL + * if message is already translated or not possible to translate. * @param $severity - * The severity of the message, as per RFC 3164. Possible values are - * WATCHDOG_ERROR, WATCHDOG_WARNING, etc. + * (optional) The severity of the message, as per RFC 3164. Possible values are + * WATCHDOG_ERROR, WATCHDOG_WARNING, etc. Defaults to WATCHDOG_NOTICE. * @param $link - * A link to associate with the message. + * (optional) A link to associate with the message. * * @see watchdog_severity_levels() * @see hook_watchdog() @@ -1479,8 +1519,9 @@ function watchdog($type, $message, $vari static $in_error_state = FALSE; - // It is possible that the error handling will itself trigger an error. In that case, we could - // end up in an infinite loop. To avoid that, we implement a simple static semaphore. + // It is possible that the error handling will itself trigger an error. In that + // case, we could end up in an infinite loop. To avoid that, we implement a + // simple static semaphore. if (!$in_error_state && function_exists('module_implements')) { $in_error_state = TRUE; @@ -1510,22 +1551,28 @@ function watchdog($type, $message, $vari } /** - * Set a message which reflects the status of the performed operation. + * Sets a message that reflects the status of the performed operation. * * If the function is called with no arguments, this function returns all set * messages without clearing them. * * @param $message - * The message should begin with a capital letter and always ends with a - * period '.'. + * (optional) The message should begin with a capital letter and always ends + * with a period '.'. If omitted, returns an array of all previously set + * messages. * @param $type - * The type of the message. One of the following values are possible: + * (optional) The type of the message. One of the following values are + * possible: * - 'status' * - 'warning' * - 'error' + * Defaults to 'status'. * @param $repeat - * If this is FALSE and the message is already set, then the message won't - * be repeated. + * (optional) If this is FALSE and the message is already set, then the message + * won't be repeated. Defaults to TRUE. + * + * @return + * If $message is omitted, an array of all previously set messages. */ function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) { if ($message) { @@ -1546,17 +1593,18 @@ function drupal_set_message($message = N } /** - * Return all messages that have been set. + * Returns all messages that have been set. * * @param $type * (optional) Only return messages of this type. * @param $clear_queue - * (optional) Set to FALSE if you do not want to clear the messages queue + * (optional) Set to FALSE if you do not want to clear the messages queue. + * * @return - * An associative array, the key is the message type, the value an array - * of messages. If the $type parameter is passed, you get only that type, - * or an empty array if there are no such messages. If $type is not passed, - * all message types are returned, or an empty array if none exist. + * An associative array, the key is the message type, the value an array of + * messages. If the $type parameter is passed, you get only that type, or an + * empty array if there are no such messages. If $type is not passed, all + * message types are returned, or an empty array if none exist. */ function drupal_get_messages($type = NULL, $clear_queue = TRUE) { if ($messages = drupal_set_message()) { @@ -1579,7 +1627,9 @@ function drupal_get_messages($type = NUL } /** - * Get the title of the current page, for display on the page and in the title bar. + * Gets the title of the current page. + * + * This is used for display on the page and in the title bar. * * @return * The current page's title. @@ -1587,7 +1637,8 @@ function drupal_get_messages($type = NUL function drupal_get_title() { $title = drupal_set_title(); - // During a bootstrap, menu.inc is not included and thus we cannot provide a title. + // During a bootstrap, menu.inc is not included and thus we cannot provide a + // title. if (!isset($title) && function_exists('menu_get_active_title')) { $title = check_plain(menu_get_active_title()); } @@ -1596,16 +1647,18 @@ function drupal_get_title() { } /** - * Set the title of the current page, for display on the page and in the title bar. + * Sets the title of the current page. + * + * This title is displayed on the page and in the title bar. * * @param $title - * Optional string value to assign to the page title; or if set to NULL - * (default), leaves the current title unchanged. + * (optional) String value to assign to the page title. Defaults to NULL, which + * leaves the current title unchanged. * @param $output - * Optional flag - normally should be left as CHECK_PLAIN. Only set to - * PASS_THROUGH if you have already removed any possibly dangerous code - * from $title using a function like check_plain() or filter_xss(). With this - * flag the string will be passed through unchanged. + * (optional) Sanitation flag. Defaults to CHECK_PLAIN. Only set to + * PASS_THROUGH if you have already removed any possibly dangerous code from + * $title using a function like check_plain() or filter_xss(). With this flag + * the string will be passed through unchanged. * * @return * The updated title of the current page. @@ -1621,33 +1674,33 @@ function drupal_set_title($title = NULL, } /** - * Check to see if an IP address has been blocked. + * Checks to see if an IP address has been blocked. * * Blocked IP addresses are stored in the database by default. However for - * performance reasons we allow an override in settings.php. This allows us - * to avoid querying the database at this critical stage of the bootstrap if - * an administrative interface for IP address blocking is not required. + * performance reasons we allow an override in settings.php. This allows us to + * avoid querying the database at this critical stage of the bootstrap if an + * administrative interface for IP address blocking is not required. * * @param $ip * IP address to check. - * @return bool + * + * @return * TRUE if access is denied, FALSE if access is allowed. */ function drupal_is_denied($ip) { - // Because this function is called on every page request, we first check - // for an array of IP addresses in settings.php before querying the - // database. + // Because this function is called on every page request, we first check for an + // array of IP addresses in settings.php before querying the database. $blocked_ips = variable_get('blocked_ips'); $denied = FALSE; if (isset($blocked_ips) && is_array($blocked_ips)) { $denied = in_array($ip, $blocked_ips); } // Only check if database.inc is loaded already. If - // $conf['page_cache_without_database'] = TRUE; is set in settings.php, - // then the database won't be loaded here so the IPs in the database - // won't be denied. However the user asked explicitly not to use the - // database and also in this case it's quite likely that the user relies - // on higher performance solutions like a firewall. + // @code$conf['page_cache_without_database'] = TRUE; @endcode is set in + // settings.php, then the database won't be loaded here so the IPs in the + // database won't be denied. However the user asked explicitly not to use the + // database and also in this case it's quite likely that the user relies on + // higher performance solutions like a firewall. elseif (class_exists('Database', FALSE)) { $denied = (bool)db_query("SELECT 1 FROM {blocked_ips} WHERE ip = :ip", array(':ip' => $ip))->fetchField(); } @@ -1655,7 +1708,7 @@ function drupal_is_denied($ip) { } /** - * Handle denied users. + * Handles denied users. * * @param $ip * IP address to check. Prints a message and exits if access is denied. @@ -1674,10 +1727,14 @@ function drupal_block_denied($ip) { * * This function is better than simply calling mt_rand() or any other built-in * PHP function because it can return a long string of bytes (compared to < 4 - * bytes normally from mt_rand()) and uses the best available pseudo-random source. + * bytes normally from mt_rand()) and uses the best available pseudo-random + * source. * * @param $count * The number of characters (bytes) to return in the string. + * + * @return + * A string of highly randomized bytes. */ function drupal_random_bytes($count) { // $random_state does not use drupal_static as it stores random bytes. @@ -1693,23 +1750,23 @@ function drupal_random_bytes($count) { $bytes = ''; } if (strlen($bytes) < $count) { - // /dev/urandom is available on many *nix systems and is considered the - // best commonly available pseudo-random source. + // /dev/urandom is available on many *nix systems and is considered the best + // commonly available pseudo-random source. if ($fh = @fopen('/dev/urandom', 'rb')) { - // PHP only performs buffered reads, so in reality it will always read - // at least 4096 bytes. Thus, it costs nothing extra to read and store - // that much so as to speed any additional invocations. + // PHP only performs buffered reads, so in reality it will always read at + // least 4096 bytes. Thus, it costs nothing extra to read and store that + // much so as to speed any additional invocations. $bytes .= fread($fh, max(4096, $count)); fclose($fh); } // If /dev/urandom is not available or returns no bytes, this loop will // generate a good set of pseudo-random bytes on any system. - // Note that it may be important that our $random_state is passed - // through hash() prior to being rolled into $output, that the two hash() - // invocations are different, and that the extra input into the first one - - // the microtime() - is prepended rather than appended. This is to avoid - // directly leaking $random_state via the $output stream, which could - // allow for trivial prediction of further "random" numbers. + // Note that it may be important that our $random_state is passed through + // hash() prior to being rolled into $output, that the two hash() invocations + // are different, and that the extra input into the first one - the + // microtime() - is prepended rather than appended. This is to avoid directly + // leaking $random_state via the $output stream, which could allow for + // trivial prediction of further "random" numbers. while (strlen($bytes) < $count) { $random_state = hash('sha256', microtime() . mt_rand() . $random_state); $bytes .= hash('sha256', mt_rand() . $random_state, TRUE); @@ -1721,7 +1778,7 @@ function drupal_random_bytes($count) { } /** - * Calculate a base-64 encoded, URL-safe sha-256 hmac. + * Calculates a base-64 encoded, URL-safe SHA-256 HMAC. * * @param $data * String to be validated with the hmac. @@ -1729,24 +1786,24 @@ function drupal_random_bytes($count) { * A secret string key. * * @return - * A base-64 encoded sha-256 hmac, with + replaced with -, / with _ and - * any = padding characters removed. + * A base-64 encoded SHA-256 HMAC, with + replaced with -, / with _ and any = + * padding characters removed. */ function drupal_hmac_base64($data, $key) { $hmac = base64_encode(hash_hmac('sha256', $data, $key, TRUE)); - // Modify the hmac so it's safe to use in URLs. + // Modify the HMAC so it's safe to use in URLs. return strtr($hmac, array('+' => '-', '/' => '_', '=' => '')); } /** - * Calculate a base-64 encoded, URL-safe sha-256 hash. + * Calculates a base-64 encoded, URL-safe SHA-256 hash. * * @param $data * String to be hashed. * * @return - * A base-64 encoded sha-256 hash, with + replaced with -, / with _ and - * any = padding characters removed. + * A base-64 encoded SHA-256 hash, with + replaced with -, / with _ and any = + * padding characters removed. */ function drupal_hash_base64($data) { $hash = base64_encode(hash('sha256', $data, TRUE)); @@ -1788,9 +1845,9 @@ function drupal_array_merge_deep() { /** * Merges multiple arrays, recursively, and returns the merged array. * - * This function is equivalent to drupal_array_merge_deep(), except the - * input arrays are passed as a single array parameter rather than a variable - * parameter list. + * This function is equivalent to drupal_array_merge_deep(), except the input + * arrays are passed as a single array parameter rather than a variable parameter + * list. * * The following are equivalent: * - drupal_array_merge_deep($a, $b); @@ -1800,6 +1857,12 @@ function drupal_array_merge_deep() { * - call_user_func_array('drupal_array_merge_deep', $arrays_to_merge); * - drupal_array_merge_deep_array($arrays_to_merge); * + * @param $arrays + * An array of arrays to be merged. + * + * @return + * The merged array. + * * @see drupal_array_merge_deep() */ function drupal_array_merge_deep_array($arrays) { @@ -1830,7 +1893,8 @@ function drupal_array_merge_deep_array($ /** * Generates a default anonymous $user object. * - * @return Object - the user object. + * @return + * A user object. */ function drupal_anonymous_user() { $user = new stdClass(); @@ -1843,20 +1907,23 @@ function drupal_anonymous_user() { } /** - * A string describing a phase of Drupal to load. Each phase adds to the - * previous one, so invoking a later phase automatically runs the earlier - * phases too. The most important usage is that if you want to access the - * Drupal database from a script without loading anything else, you can - * include bootstrap.inc, and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE). + * Bootstraps Drupal to a certain bootstrap phase. + * + * Each phase is a constant describing a phase of Drupal to load. Each phase adds + * to the previous one, so invoking a later phase automatically runs the earlier + * phases too. The most important usage is that if you want to access the Drupal + * database from a script without loading anything else, you can include + * bootstrap.inc, and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE). * * @param $phase - * A constant. Allowed values are the DRUPAL_BOOTSTRAP_* constants. + * (optional) A constant. Allowed values are the DRUPAL_BOOTSTRAP_* constants. + * Defaults to NULL, which simply returns the most recently completed phase. * @param $new_phase - * A boolean, set to FALSE if calling drupal_bootstrap from inside a - * function called from drupal_bootstrap (recursion). + * (optional) A boolean, set to FALSE if calling drupal_bootstrap from inside a + * function called from drupal_bootstrap (recursion). Defaults to TRUE. + * * @return * The most recently completed phase. - * */ function drupal_bootstrap($phase = NULL, $new_phase = TRUE) { // Not drupal_static(), because does not depend on any run-time information. @@ -1935,7 +2002,10 @@ function drupal_bootstrap($phase = NULL, } /** - * Return the time zone of the current user. + * Returns the time zone of the current user. + * + * @return + * A string containing the current user's time zone. */ function drupal_get_user_timezone() { global $user; @@ -1961,7 +2031,8 @@ function drupal_get_user_timezone() { * @param $line * The line number the error was raised at. * @param $context - * An array that points to the active symbol table at the point the error occurred. + * An array that points to the active symbol table at the point the error + * occurred. */ function _drupal_error_handler($error_level, $message, $filename, $line, $context) { require_once DRUPAL_ROOT . '/includes/errors.inc'; @@ -1987,7 +2058,8 @@ function _drupal_exception_handler($exce } catch (Exception $exception2) { // Another uncaught exception was thrown while handling the first one. - // If we are displaying errors, then do so with no possibility of a further uncaught exception being thrown. + // If we are displaying errors, then do so with no possibility of a further + // uncaught exception being thrown. if (error_displayable()) { print '

Additional uncaught exception thrown while handling exception.

'; print '

Original

' . _drupal_render_exception_safe($exception) . '

'; @@ -1997,7 +2069,9 @@ function _drupal_exception_handler($exce } /** - * Bootstrap configuration: Setup script environment and load settings.php. + * Bootstraps the settings.php configuration + * + * Sets up the script environment and loads settings.php. */ function _drupal_bootstrap_configuration() { // Set the Drupal custom error handler. @@ -2012,13 +2086,15 @@ function _drupal_bootstrap_configuration } /** - * Bootstrap page cache: Try to serve a page from cache. + * Bootstraps the page cache + * + * Tries to serve a page from cache. */ function _drupal_bootstrap_page_cache() { global $user; - // Allow specifying special cache handlers in settings.php, like - // using memcached or files for storing cache information. + // Allow specifying special cache handlers in settings.php, like using + // memcached or files for storing cache information. require_once DRUPAL_ROOT . '/includes/cache.inc'; foreach (variable_get('cache_backends', array()) as $include) { require_once DRUPAL_ROOT . '/' . $include; @@ -2032,11 +2108,11 @@ function _drupal_bootstrap_page_cache() $cache_enabled = variable_get('cache'); } drupal_block_denied(ip_address()); - // If there is no session cookie and cache is enabled (or forced), try - // to serve a cached page. + // If there is no session cookie and cache is enabled (or forced), try to serve + // a cached page. if (!isset($_COOKIE[session_name()]) && $cache_enabled) { - // Make sure there is a user object because its timestamp will be - // checked, hook_boot might check for anonymous user etc. + // Make sure there is a user object because its timestamp will be checked, + // hook_boot might check for anonymous user etc. $user = drupal_anonymous_user(); // Get the page from the cache. $cache = drupal_page_get_cache(); @@ -2047,14 +2123,12 @@ function _drupal_bootstrap_page_cache() $_GET['q'] = $cache->data['path']; drupal_set_title($cache->data['title'], PASS_THROUGH); date_default_timezone_set(drupal_get_user_timezone()); - // If the skipping of the bootstrap hooks is not enforced, call - // hook_boot. + // If the skipping of the bootstrap hooks is not enforced, call hook_boot. if (variable_get('page_cache_invoke_hooks', TRUE)) { bootstrap_invoke_all('boot'); } drupal_serve_page_from_cache($cache); - // If the skipping of the bootstrap hooks is not enforced, call - // hook_exit. + // If the skipping of the bootstrap hooks is not enforced, call hook_exit. if (variable_get('page_cache_invoke_hooks', TRUE)) { bootstrap_invoke_all('exit'); } @@ -2068,7 +2142,9 @@ function _drupal_bootstrap_page_cache() } /** - * Bootstrap database: Initialize database system and register autoload functions. + * Bootstraps the database + * + * Initializes the database system and registers autoload functions. */ function _drupal_bootstrap_database() { // Redirect the user to the installation script if Drupal has not been @@ -2107,20 +2183,22 @@ function _drupal_bootstrap_database() { } } - // Initialize the database system. Note that the connection - // won't be initialized until it is actually requested. + // Initialize the database system. Note that the connection won't be + // initialized until it is actually requested. require_once DRUPAL_ROOT . '/includes/database/database.inc'; // Register autoload functions so that we can access classes and interfaces. // The database autoload routine comes first so that we can load the database - // system without hitting the database. That is especially important during - // the install or upgrade process. + // system without hitting the database. That is especially important during the + // install or upgrade process. spl_autoload_register('drupal_autoload_class'); spl_autoload_register('drupal_autoload_interface'); } /** - * Bootstrap variables: Load system variables and all enabled bootstrap modules. + * Bootstraps variables + * + * Loads system variables and all enabled bootstrap modules. */ function _drupal_bootstrap_variables() { global $conf; @@ -2129,7 +2207,8 @@ function _drupal_bootstrap_variables() { require_once DRUPAL_ROOT . '/' . variable_get('lock_inc', 'includes/lock.inc'); lock_initialize(); - // Load variables from the database, but do not overwrite variables set in settings.php. + // Load variables from the database, but do not overwrite variables set in + // settings.php. $conf = variable_initialize(isset($conf) ? $conf : array()); // Load bootstrap modules. require_once DRUPAL_ROOT . '/includes/module.inc'; @@ -2137,7 +2216,10 @@ function _drupal_bootstrap_variables() { } /** - * Bootstrap page header: Invoke hook_boot(), initialize locking system, and send default HTTP headers. + * Bootstraps the page header + * + * Invokes hook_boot(), initializes locking system, and sends default HTTP + * headers. */ function _drupal_bootstrap_page_header() { bootstrap_invoke_all('boot'); @@ -2160,13 +2242,15 @@ function drupal_get_bootstrap_phase() { } /** + * Generates a valid simpletest prefix. + * * Checks the current User-Agent string to see if this is an internal request * from SimpleTest. If so, returns the test prefix for this test. * * @return - * Either the simpletest prefix (the string "simpletest" followed by any - * number of digits) or FALSE if the user agent does not contain a valid - * HMAC and timestamp. + * Either the simpletest prefix (the string "simpletest" followed by any number + * of digits) or FALSE if the user agent does not contain a valid HMAC and + * timestamp. */ function drupal_valid_test_ua() { global $drupal_hash_salt; @@ -2180,13 +2264,13 @@ function drupal_valid_test_ua() { if (isset($_SERVER['HTTP_USER_AGENT']) && preg_match("/^(simpletest\d+);(.+);(.+);(.+)$/", $_SERVER['HTTP_USER_AGENT'], $matches)) { list(, $prefix, $time, $salt, $hmac) = $matches; $check_string = $prefix . ';' . $time . ';' . $salt; - // We use the salt from settings.php to make the HMAC key, since - // the database is not yet initialized and we can't access any Drupal variables. - // The file properties add more entropy not easily accessible to others. + // We use the salt from settings.php to make the HMAC key, since the database + // is not yet initialized and we can't access any Drupal variables. The file + // properties add more entropy not easily accessible to others. $key = $drupal_hash_salt . filectime(__FILE__) . fileinode(__FILE__); $time_diff = REQUEST_TIME - $time; - // Since we are making a local request a 5 second time window is allowed, - // and the HMAC must match. + // Since we are making a local request a 5 second time window is allowed, and + // the HMAC must match. if ($time_diff >= 0 && $time_diff <= 5 && $hmac == drupal_hmac_base64($check_string, $key)) { $test_prefix = $prefix; return $test_prefix; @@ -2197,16 +2281,22 @@ function drupal_valid_test_ua() { } /** - * Generate a user agent string with a HMAC and timestamp for simpletest. + * Generates a user agent string with a HMAC and timestamp for simpletest. + * + * @param $prefix + * A string containing the simpletest prefix. + * + * @return + * A User-Agent string. */ function drupal_generate_test_ua($prefix) { global $drupal_hash_salt; static $key; if (!isset($key)) { - // We use the salt from settings.php to make the HMAC key, since - // the database is not yet initialized and we can't access any Drupal variables. - // The file properties add more entropy not easily accessible to others. + // We use the salt from settings.php to make the HMAC key, since the database + // is not yet initialized and we can't access any Drupal variables. The file + // properties add more entropy not easily accessible to others. $key = $drupal_hash_salt . filectime(__FILE__) . fileinode(__FILE__); } // Generate a moderately secure HMAC based on the database credentials. @@ -2218,8 +2308,8 @@ function drupal_generate_test_ua($prefix /** * Enables use of the theme system without requiring database access. * - * Loads and initializes the theme system for site installs, updates and when - * the site is in maintenance mode. This also applies when the database fails. + * Loads and initializes the theme system for site installs, updates and when the + * site is in maintenance mode. This also applies when the database fails. * * @see _drupal_maintenance_theme() */ @@ -2229,15 +2319,22 @@ function drupal_maintenance_theme() { } /** - * Return TRUE if a Drupal installation is currently being attempted. + * Returns TRUE if a Drupal installation is currently being attempted. + * + * @return + * A boolean indicating whether an installation is currently being attempted. */ function drupal_installation_attempted() { return defined('MAINTENANCE_MODE') && MAINTENANCE_MODE == 'install'; } /** - * Return the name of the localization function. Use in code that needs to - * run both during installation and normal operation. + * Returns the name of the localization function. + * + * Use in code that needs to run both during installation and normal operation. + * + * @return + * A string containing either the localization function. */ function get_t() { static $t; @@ -2250,7 +2347,7 @@ function get_t() { } /** - * Initialize all the defined language types. + * Initializes all the defined language types. */ function drupal_language_initialize() { $types = language_types(); @@ -2275,7 +2372,7 @@ function drupal_language_initialize() { } /** - * The built-in language types. + * Returns an array of the built-in language types. * * @return * An array of key-values pairs where the key is the language type and the @@ -2290,23 +2387,35 @@ function drupal_language_types() { } /** - * Return true if there is more than one language enabled. + * Returns TRUE if there is more than one language enabled. + * + * @return + * A boolean indicating whether there is more than one language enabled. */ function drupal_multilingual() { return variable_get('language_count', 1) > 1; } /** - * Return an array of the available language types. + * Returns an array of the available language types. + * + * @return + * An array of the available language types. The keys are the language types + * and the values are booleans indicating the configurability of the language + * type. */ function language_types() { return array_keys(variable_get('language_types', drupal_language_types())); } /** - * Get a list of languages set up indexed by the specified key + * Gets a list of languages set up indexed by the specified key. * - * @param $field The field to index the list with. + * @param $field + * (optional) The field to index the list with. Defaults to 'language'. + * + * @return + * An array of languages. */ function language_list($field = 'language') { $languages = &drupal_static(__FUNCTION__); @@ -2314,9 +2423,9 @@ function language_list($field = 'languag if (!isset($languages)) { if (drupal_multilingual() || module_exists('locale')) { $languages['language'] = db_query('SELECT * FROM {languages} ORDER BY weight ASC, name ASC')->fetchAllAssoc('language'); - // Users cannot uninstall the native English language. However, we allow - // it to be hidden from the installed languages. Therefore, at least one - // other language must be enabled then. + // Users cannot uninstall the native English language. However, we allow it + // to be hidden from the installed languages. Therefore, at least one other + // language must be enabled then. if (!$languages['language']['en']->enabled && !variable_get('language_native_enabled', TRUE)) { unset($languages['language']['en']); } @@ -2345,10 +2454,15 @@ function language_list($field = 'languag } /** - * Default language used on the site + * Returns the default language used on the site. * * @param $property - * Optional property of the language object to return + * (optional) Property of the language object to return. If omitted, the whole + * language object is returned. + * + * @return + * Depending on whether $property was set, the whole language object or the + * specified property. */ function language_default($property = NULL) { $language = variable_get('language_default', (object) array('language' => 'en', 'name' => 'English', 'native' => 'English', 'direction' => 0, 'enabled' => 1, 'plurals' => 0, 'formula' => '', 'domain' => '', 'prefix' => '', 'weight' => 0, 'javascript' => '')); @@ -2405,22 +2519,24 @@ function request_path() { } /** - * Return a component of the current Drupal path. + * Returns a component of the current Drupal path. * * When viewing a page at the path "admin/structure/types", for example, arg(0) * returns "admin", arg(1) returns "structure", and arg(2) returns "types". * * Avoid use of this function where possible, as resulting code is hard to read. - * In menu callback functions, attempt to use named arguments. See the explanation - * in menu.inc for how to construct callbacks that take arguments. When attempting - * to use this function to load an element from the current path, e.g. loading the - * node on a node page, please use menu_get_object() instead. + * In menu callback functions, attempt to use named arguments. See the + * explanation in menu.inc for how to construct callbacks that take arguments. + * When attempting to use this function to load an element from the current path, + * e.g. loading the node on a node page, please use menu_get_object() instead. * * @param $index - * The index of the component, where each component is separated by a '/' - * (forward-slash), and where the first component has an index of 0 (zero). + * (optional) The index of the component, where each component is separated by + * a '/' (forward-slash), and where the first component has an index of 0 + * (zero). If omitted, an array of all components is returned. * @param $path - * A path to break into components. Defaults to the path of the current page. + * (optional) A path to break into components. Defaults to the path of the + * current page. * * @return * The component specified by $index, or NULL if the specified component was @@ -2430,8 +2546,8 @@ function request_path() { function arg($index = NULL, $path = NULL) { // Even though $arguments doesn't need to be resettable for any functional // reasons (the result of explode() does not depend on any run-time - // information), it should be resettable anyway in case a module needs to - // free up the memory used by it. + // information), it should be resettable anyway in case a module needs to free + // up the memory used by it. // Use the advanced drupal_static() pattern, since this is called very often. static $drupal_static_fast; if (!isset($drupal_static_fast)) { @@ -2454,10 +2570,12 @@ function arg($index = NULL, $path = NULL } /** - * If Drupal is behind a reverse proxy, we use the X-Forwarded-For header - * instead of $_SERVER['REMOTE_ADDR'], which would be the IP address of - * the proxy server, and not the client's. The actual header name can be - * configured by the reverse_proxy_header variable. + * Returns the client's IP address. + * + * If Drupal is behind a reverse proxy, we use the X-Forwarded-For header instead + * of $_SERVER['REMOTE_ADDR'], which would be the IP address of the proxy server, + * and not the client's. The actual header name can be configured by the + * reverse_proxy_header variable. * * @return * IP address of client machine, adjusted for reverse proxy and/or cluster @@ -2472,14 +2590,15 @@ function ip_address() { if (variable_get('reverse_proxy', 0)) { $reverse_proxy_header = variable_get('reverse_proxy_header', 'HTTP_X_FORWARDED_FOR'); if (!empty($_SERVER[$reverse_proxy_header])) { - // If an array of known reverse proxy IPs is provided, then trust - // the XFF header if request really comes from one of them. + // If an array of known reverse proxy IPs is provided, then trust the XFF + // header if request really comes from one of them. $reverse_proxy_addresses = variable_get('reverse_proxy_addresses', array()); // Turn XFF header into an array. $forwarded = explode(',', $_SERVER[$reverse_proxy_header]); - // Trim the forwarded IPs; they may have been delimited by commas and spaces. + // Trim the forwarded IPs; they may have been delimited by commas and + // spaces. $forwarded = array_map('trim', $forwarded); // Tack direct client IP onto end of forwarded array. @@ -2503,15 +2622,21 @@ function ip_address() { */ /** - * Get the schema definition of a table, or the whole database schema. + * Gets the schema definition of a table, or the whole database schema. * - * The returned schema will include any modifications made by any - * module that implements hook_schema_alter(). + * The returned schema will include any modifications made by any module that + * implements hook_schema_alter(). * * @param $table - * The name of the table. If not given, the schema of all tables is returned. + * (optional) The name of the table. If not given, the schema of all tables is + * returned. * @param $rebuild - * If true, the schema will be rebuilt instead of retrieved from the cache. + * (optional) If TRUE, the schema will be rebuilt instead of retrieved from the + * cache. Defaults to FALSE. + * + * @return + * An array containing the schema definition of the specified table or an array + * of schema definitions keyed by table name. */ function drupal_get_schema($table = NULL, $rebuild = FALSE) { static $schema = array(); @@ -2525,11 +2650,11 @@ function drupal_get_schema($table = NULL else { $schema = array(); // Load the .install files to get hook_schema. - // On some databases this function may be called before bootstrap has - // been completed, so we force the functions we need to load just in case. + // On some databases this function may be called before bootstrap has been + // completed, so we force the functions we need to load just in case. if (function_exists('module_load_all_includes')) { - // This function can be called very early in the bootstrap process, so - // we force the module_list() cache to be refreshed to ensure that it + // This function can be called very early in the bootstrap process, so we + // force the module_list() cache to be refreshed to ensure that it // contains the complete list of modules before we go on to call // module_load_all_includes(). module_list(TRUE); @@ -2580,13 +2705,14 @@ function drupal_get_schema($table = NULL */ /** - * Confirm that an interface is available. + * Confirms that an interface is available. * * This function is rarely called directly. Instead, it is registered as an * spl_autoload() handler, and PHP calls it for us when necessary. * * @param $interface * The name of the interface to check or load. + * * @return * TRUE if the interface is currently available, FALSE otherwise. */ @@ -2595,13 +2721,14 @@ function drupal_autoload_interface($inte } /** - * Confirm that a class is available. + * Confirms that a class is available. * * This function is rarely called directly. Instead, it is registered as an * spl_autoload() handler, and PHP calls it for us when necessary. * * @param $class * The name of the class to check or load. + * * @return * TRUE if the class is currently available, FALSE otherwise. */ @@ -2610,18 +2737,19 @@ function drupal_autoload_class($class) { } /** - * Helper to check for a resource in the registry. + * Checks for a resource in the registry. * * @param $type * The type of resource we are looking up, or one of the constants - * REGISTRY_RESET_LOOKUP_CACHE or REGISTRY_WRITE_LOOKUP_CACHE, which - * signal that we should reset or write the cache, respectively. + * REGISTRY_RESET_LOOKUP_CACHE or REGISTRY_WRITE_LOOKUP_CACHE, which signal + * that we should reset or write the cache, respectively. * @param $name - * The name of the resource, or NULL if either of the REGISTRY_* constants - * is passed in. + * (optional) The name of the resource, or NULL if either of the REGISTRY_* + * constants is passed in. Defaults to NULL. + * * @return - * TRUE if the resource was found, FALSE if not. - * NULL if either of the REGISTRY_* constants is passed in as $type. + * TRUE if the resource was found, FALSE if not. NULL if either of the + * REGISTRY_* constants is passed in as $type. */ function _registry_check_code($type, $name = NULL) { static $lookup_cache, $cache_update_needed; @@ -2637,8 +2765,8 @@ function _registry_check_code($type, $na } } - // When we rebuild the registry, we need to reset this cache so - // we don't keep lookups for resources that changed during the rebuild. + // When we rebuild the registry, we need to reset this cache so we don't keep + // lookups for resources that changed during the rebuild. if ($type == REGISTRY_RESET_LOOKUP_CACHE) { $cache_update_needed = TRUE; $lookup_cache = NULL; @@ -2665,8 +2793,8 @@ function _registry_check_code($type, $na } // This function may get called when the default database is not active, but - // there is no reason we'd ever want to not use the default database for - // this query. + // there is no reason we'd ever want to not use the default database for this + // query. $file = Database::getConnection('default', 'default')->query("SELECT filename FROM {registry} WHERE name = :name AND type = :type", array( ':name' => $name, ':type' => $type, @@ -2676,8 +2804,8 @@ function _registry_check_code($type, $na // Flag that we've run a lookup query and need to update the cache. $cache_update_needed = TRUE; - // Misses are valuable information worth caching, so cache even if - // $file is FALSE. + // Misses are valuable information worth caching, so cache even if $file is + // FALSE. $lookup_cache[$cache_key] = $file; if ($file) { @@ -2690,7 +2818,7 @@ function _registry_check_code($type, $na } /** - * Rescan all enabled modules and rebuild the registry. + * Rescans all enabled modules and rebuilds the registry. * * Rescans all code in modules or includes directories, storing the location of * each interface or class in the database. @@ -2701,7 +2829,7 @@ function registry_rebuild() { } /** - * Update the registry based on the latest files listed in the database. + * Updates the registry based on the latest files listed in the database. * * This function should be used when system_rebuild_module_data() does not need * to be called, because it is already known that the list of files in the @@ -2719,14 +2847,14 @@ function registry_update() { */ /** - * Central static variable storage. + * Stores static variables centrally * - * All functions requiring a static variable to persist or cache data within - * a single page request are encouraged to use this function unless it is + * All functions requiring a static variable to persist or cache data within a + * single page request are encouraged to use this function unless it is * absolutely certain that the static variable will not need to be reset during * the page request. By centralizing static variable storage through this - * function, other functions can rely on a consistent API for resetting any - * other function's static variables. + * function, other functions can rely on a consistent API for resetting any other + * function's static variables. * * Example: * @code @@ -2744,14 +2872,14 @@ function registry_update() { * // available in $languages by the desired field. * ... * } - * // Subsequent invocations of this function for a particular index field - * // skip the above two code blocks and quickly return the already indexed + * // Subsequent invocations of this function for a particular index field skip + * // the above two code blocks and quickly return the already indexed * // information. * return $languages[$field]; * } * function locale_translate_overview_screen() { - * // When building the content for the translations overview page, make - * // sure to get completely fresh information about the supported languages. + * // When building the content for the translations overview page, make sure + * // to get completely fresh information about the supported languages. * drupal_static_reset('language_list'); * ... * } @@ -2762,8 +2890,8 @@ function registry_update() { * because when writing a function, it's hard to forecast all the situations in * which it will be used. A guideline is that if a function's static variable * does not depend on any information outside of the function that might change - * during a single page request, then it's ok to use the "static" keyword - * instead of the drupal_static() function. + * during a single page request, then it's ok to use the "static" keyword instead + * of the drupal_static() function. * * Example: * @code @@ -2781,13 +2909,13 @@ function registry_update() { * @endcode * * In a few cases, a function needs a resettable static variable, but the - * function is called many times (100+) during a single page request, so - * every microsecond of execution time that can be removed from the function - * counts. These functions can use a more cumbersome, but faster variant of - * calling drupal_static(). It works by storing the reference returned by - * drupal_static() in the calling function's own static variable, thereby - * removing the need to call drupal_static() for each iteration of the function. - * Conceptually, it replaces: + * function is called many times (100+) during a single page request, so every + * microsecond of execution time that can be removed from the function counts. + * These functions can use a more cumbersome, but faster variant of calling + * drupal_static(). It works by storing the reference returned by drupal_static() + * in the calling function's own static variable, thereby removing the need to + * call drupal_static() for each iteration of the function. Conceptually, it + * replaces: * @code * $foo = &drupal_static(__FUNCTION__); * @endcode @@ -2807,7 +2935,8 @@ function registry_update() { * Example: * @code * function user_access($string, $account = NULL) { - * // Use the advanced drupal_static() pattern, since this is called very often. + * // Use the advanced drupal_static() pattern, since this is called very + // often. * static $drupal_static_fast; * if (!isset($drupal_static_fast)) { * $drupal_static_fast['perm'] = &drupal_static(__FUNCTION__); @@ -2823,13 +2952,13 @@ function registry_update() { * is recommended. For a function with multiple static variables add a * distinguishing suffix to the function name for each one. * @param $default_value - * Optional default value. + * (optional) The default value. * @param $reset - * TRUE to reset a specific named variable, or all variables if $name is NULL. - * Resetting every variable should only be used, for example, for running - * unit tests with a clean environment. Should be used only though via - * function drupal_static_reset() and the return value should not be used in - * this case. + * (optional) TRUE to reset a specific named variable, or all variables if + * $name is NULL. Resetting every variable should only be used, for example, + * for running unit tests with a clean environment. Should be used only though + * via function drupal_static_reset() and the return value should not be used + * in this case. Defaults to FALSE. * * @return * Returns a variable by reference. @@ -2864,23 +2993,27 @@ function &drupal_static($name, $default_ foreach ($default as $name => $value) { $data[$name] = $value; } - // As the function returns a reference, the return should always be a - // variable. + // As the function returns a reference, the return should always be a variable. return $data; } /** - * Reset one or all centrally stored static variable(s). + * Resets one or all centrally stored static variable(s). * * @param $name - * Name of the static variable to reset. Omit to reset all variables. + * (optional) Name of the static variable to reset. Omit to reset all + * variables. */ function drupal_static_reset($name = NULL) { drupal_static($name, NULL, TRUE); } /** - * Detect whether the current script is running in a command-line environment. + * Detects whether the current script is running in a command-line environment. + * + * @return + * A boolean indicating whether the current script is running in a command-line + * environment. */ function drupal_is_cli() { return (!isset($_SERVER['SERVER_SOFTWARE']) && (php_sapi_name() == 'cli' || (is_numeric($_SERVER['argc']) && $_SERVER['argc'] > 0))); @@ -2888,26 +3021,27 @@ function drupal_is_cli() { /** * Formats text for emphasized display in a placeholder inside a sentence. + * * Used automatically by t(). * * @param $text * The text to format (plain-text). * * @return - * The formatted text (html). + * The formatted text (HTML). */ function drupal_placeholder($text) { return '' . check_plain($text) . ''; } /** - * Register a function for execution on shutdown. + * Registers a function for execution on shutdown. * * Wrapper for register_shutdown_function() that catches thrown exceptions to * avoid "Exception thrown without a stack frame in Unknown". * * @param $callback - * The shutdown function to register. + * (optional) The shutdown function to register. * @param ... * Additional arguments to pass to the shutdown function. * @@ -2936,13 +3070,13 @@ function &drupal_register_shutdown_funct } /** - * Internal function used to execute registered shutdown functions. + * Executes registered shutdown functions. */ function _drupal_shutdown_function() { $callbacks = &drupal_register_shutdown_function(); - // Set the CWD to DRUPAL_ROOT as it is not guaranteed to be the same as it - // was in the normal context of execution. + // Set the CWD to DRUPAL_ROOT as it is not guaranteed to be the same as it was + // in the normal context of execution. chdir(DRUPAL_ROOT); try { @@ -2951,11 +3085,13 @@ function _drupal_shutdown_function() { } } catch (Exception $exception) { - // If we are displaying errors, then do so with no possibility of a further uncaught exception being thrown. - require_once DRUPAL_ROOT . '/includes/errors.inc'; - if (error_displayable()) { + // If we are displaying errors, then do so with no possibility of a further + // uncaught exception being thrown. + require_once DRUPAL_ROOT . '/includes/errors.inc'; + if (error_displayable()) { print '

Uncaught exception thrown in shutdown function.

'; print '

' . _drupal_render_exception_safe($exception) . '

'; } } } + Index: modules/aggregator/aggregator.info =================================================================== RCS file: /cvs/drupal/drupal/modules/aggregator/aggregator.info,v retrieving revision 1.15 diff -u -p -r1.15 aggregator.info --- modules/aggregator/aggregator.info 20 Dec 2010 19:59:40 -0000 1.15 +++ modules/aggregator/aggregator.info 24 Feb 2011 16:51:31 -0000 @@ -7,3 +7,5 @@ core = 7.x files[] = aggregator.test configure = admin/config/services/aggregator/settings stylesheets[all][] = aggregator.css +tags[] = Core +tags[] = Web services Index: modules/block/block.info =================================================================== RCS file: /cvs/drupal/drupal/modules/block/block.info,v retrieving revision 1.16 diff -u -p -r1.16 block.info --- modules/block/block.info 20 Dec 2010 19:59:40 -0000 1.16 +++ modules/block/block.info 24 Feb 2011 16:51:31 -0000 @@ -6,3 +6,4 @@ version = VERSION core = 7.x files[] = block.test configure = admin/structure/block +tags[] = Core