diff options
Diffstat (limited to 'includes')
| -rw-r--r-- | includes/ajax.inc | 2 | ||||
| -rw-r--r-- | includes/authorize.inc | 2 | ||||
| -rw-r--r-- | includes/bootstrap.inc | 144 | ||||
| -rw-r--r-- | includes/common.inc | 174 | ||||
| -rw-r--r-- | includes/database/database.inc | 4 | ||||
| -rw-r--r-- | includes/database/log.inc | 10 | ||||
| -rw-r--r-- | includes/database/pgsql/database.inc | 11 | ||||
| -rw-r--r-- | includes/database/sqlite/query.inc | 12 | ||||
| -rw-r--r-- | includes/entity.inc | 19 | ||||
| -rw-r--r-- | includes/errors.inc | 15 | ||||
| -rw-r--r-- | includes/file.inc | 8 | ||||
| -rw-r--r-- | includes/filetransfer/filetransfer.inc | 2 | ||||
| -rw-r--r-- | includes/form.inc | 159 | ||||
| -rw-r--r-- | includes/image.inc | 19 | ||||
| -rw-r--r-- | includes/install.core.inc | 91 | ||||
| -rw-r--r-- | includes/install.inc | 63 | ||||
| -rw-r--r-- | includes/iso.inc | 2 | ||||
| -rw-r--r-- | includes/language.inc | 17 | ||||
| -rw-r--r-- | includes/mail.inc | 28 | ||||
| -rw-r--r-- | includes/menu.inc | 159 | ||||
| -rw-r--r-- | includes/module.inc | 43 | ||||
| -rw-r--r-- | includes/session.inc | 20 | ||||
| -rw-r--r-- | includes/stream_wrappers.inc | 6 | ||||
| -rw-r--r-- | includes/theme.inc | 6 | ||||
| -rw-r--r-- | includes/unicode.inc | 4 | ||||
| -rw-r--r-- | includes/update.inc | 33 |
26 files changed, 619 insertions, 434 deletions
diff --git a/includes/ajax.inc b/includes/ajax.inc index fb07477d6..4107029fe 100644 --- a/includes/ajax.inc +++ b/includes/ajax.inc @@ -168,7 +168,7 @@ * displayed while awaiting a response from the callback, and add an optional * message. Possible keys: 'type', 'message', 'url', 'interval'. * More information is available in the - * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7 Form API Reference @endlink + * @link forms_api_reference.html Form API Reference @endlink * * In addition to using Form API for doing in-form modification, Ajax may be * enabled by adding classes to buttons and links. By adding the 'use-ajax' diff --git a/includes/authorize.inc b/includes/authorize.inc index da6918ca7..8360e132c 100644 --- a/includes/authorize.inc +++ b/includes/authorize.inc @@ -18,7 +18,7 @@ function authorize_filetransfer_form($form, &$form_state) { global $base_url, $is_https; $form = array(); - // If possible, we want to post this form securely via https. + // If possible, we want to post this form securely via HTTPS. $form['#https'] = TRUE; // CSS we depend on lives in modules/system/maintenance.css, which is loaded diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc index 5eb592441..d9ad8563a 100644 --- a/includes/bootstrap.inc +++ b/includes/bootstrap.inc @@ -8,7 +8,7 @@ /** * The current system version. */ -define('VERSION', '7.16'); +define('VERSION', '7.17-dev'); /** * Core API compatibility. @@ -26,6 +26,21 @@ define('DRUPAL_MINIMUM_PHP', '5.2.4'); define('DRUPAL_MINIMUM_PHP_MEMORY_LIMIT', '32M'); /** + * Error reporting level: display no errors. + */ +define('ERROR_REPORTING_HIDE', 0); + +/** + * Error reporting level: display errors and warnings. + */ +define('ERROR_REPORTING_DISPLAY_SOME', 1); + +/** + * Error reporting level: display all messages. + */ +define('ERROR_REPORTING_DISPLAY_ALL', 2); + +/** * Indicates that the item should never be removed unless explicitly selected. * * The item may be removed using cache_clear_all() with a cache ID. @@ -498,56 +513,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 +531,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 +704,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(); @@ -752,7 +725,7 @@ function drupal_settings_initialize() { $base_root = substr($base_url, 0, strlen($base_url) - strlen($parts['path'])); } else { - // Create base URL + // Create base URL. $http_protocol = $is_https ? 'https' : 'http'; $base_root = $http_protocol . '://' . $_SERVER['HTTP_HOST']; @@ -778,7 +751,7 @@ function drupal_settings_initialize() { } else { // Otherwise use $base_url as session name, without the protocol - // to use the same session identifiers across http and https. + // 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(). @@ -1732,7 +1705,8 @@ function watchdog($type, $message, $variables = array(), $severity = WATCHDOG_NO 'request_uri' => $base_root . request_uri(), 'referer' => isset($_SERVER['HTTP_REFERER']) ? $_SERVER['HTTP_REFERER'] : '', 'ip' => ip_address(), - 'timestamp' => REQUEST_TIME, + // Request time isn't accurate for long processes, use time() instead. + 'timestamp' => time(), ); // Call the logging hooks to log/process the message @@ -1798,18 +1772,29 @@ function drupal_set_message($message = NULL, $type = 'status', $repeat = TRUE) { } /** - * Returns all messages that have been set. + * Returns all messages that have been set with drupal_set_message(). * - * @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 + * @param string $type + * (optional) Limit the messages returned by type. Defaults to NULL, meaning + * all types. These values are supported: + * - NULL + * - 'status' + * - 'warning' + * - 'error' + * @param bool $clear_queue + * (optional) If this is TRUE, the queue will be cleared of messages of the + * type specified in the $type parameter. Otherwise the queue will be left + * intact. Defaults to TRUE. * - * @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. + * @return array + * A multidimensional array with keys corresponding to the set message types. + * The indexed array values of each contain the set messages for that type. + * The messages returned are limited to the type specified in the $type + * parameter. If there are no messages of the specified type, an empty array + * is returned. + * + * @see drupal_set_message() + * @see theme_status_messages() */ function drupal_get_messages($type = NULL, $clear_queue = TRUE) { if ($messages = drupal_set_message()) { @@ -2115,14 +2100,26 @@ function drupal_anonymous_user() { /** * Ensures Drupal is bootstrapped to the specified phase. * - * The bootstrap phase is an integer constant identifying a phase of Drupal - * to load. Each phase adds to the previous one, so invoking a later phase - * automatically runs the earlier phases as well. To access the Drupal - * database from a script without loading anything else, include bootstrap.inc - * and call drupal_bootstrap(DRUPAL_BOOTSTRAP_DATABASE). + * In order to bootstrap Drupal from another PHP script, you can use this code: + * @code + * define('DRUPAL_ROOT', '/path/to/drupal'); + * require_once DRUPAL_ROOT . '/includes/bootstrap.inc'; + * drupal_bootstrap(DRUPAL_BOOTSTRAP_FULL); + * @endcode * * @param $phase - * A constant. Allowed values are the DRUPAL_BOOTSTRAP_* constants. + * A constant telling which phase to bootstrap to. When you bootstrap to a + * particular phase, all earlier phases are run automatically. Possible + * values: + * - DRUPAL_BOOTSTRAP_CONFIGURATION: Initializes configuration. + * - DRUPAL_BOOTSTRAP_PAGE_CACHE: Tries to serve a cached page. + * - DRUPAL_BOOTSTRAP_DATABASE: Initializes the database layer. + * - DRUPAL_BOOTSTRAP_VARIABLES: Initializes the variable system. + * - DRUPAL_BOOTSTRAP_SESSION: Initializes session handling. + * - DRUPAL_BOOTSTRAP_PAGE_HEADER: Sets up the page header. + * - DRUPAL_BOOTSTRAP_LANGUAGE: Finds out the language of the page. + * - DRUPAL_BOOTSTRAP_FULL: Fully loads Drupal. Validates and fixes input + * data. * @param $new_phase * A boolean, set to FALSE if calling drupal_bootstrap from inside a * function called from drupal_bootstrap (recursion). @@ -2614,6 +2611,9 @@ function drupal_language_types() { /** * Returns TRUE if there is more than one language enabled. + * + * @return + * TRUE if more than one language is enabled. */ function drupal_multilingual() { // The "language_count" variable stores the number of enabled languages to @@ -2624,6 +2624,10 @@ function drupal_multilingual() { /** * Returns an array of the available language types. + * + * @return + * An array of all language types where the keys of each are the language type + * name and its value is its configurability (TRUE/FALSE). */ function language_types() { return array_keys(variable_get('language_types', drupal_language_types())); diff --git a/includes/common.inc b/includes/common.inc index f80496bf8..5c6d86d7e 100644 --- a/includes/common.inc +++ b/includes/common.inc @@ -92,14 +92,20 @@ define('JS_THEME', 100); define('HTTP_REQUEST_TIMEOUT', -1); /** - * Constants defining cache granularity for blocks and renderable arrays. - * - * Modules specify the caching patterns for their blocks using binary - * combinations of these constants in their hook_block_info(): - * $block[delta]['cache'] = DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE; - * DRUPAL_CACHE_PER_ROLE is used as a default when no caching pattern is - * specified. Use DRUPAL_CACHE_CUSTOM to disable standard block cache and - * implement + * @defgroup block_caching Block Caching + * @{ + * Constants that define each block's caching state. + * + * Modules specify how their blocks can be cached in their hook_block_info() + * implementations. Caching can be turned off (DRUPAL_NO_CACHE), managed by the + * module declaring the block (DRUPAL_CACHE_CUSTOM), or managed by the core + * Block module. If the Block module is managing the cache, you can specify that + * the block is the same for every page and user (DRUPAL_CACHE_GLOBAL), or that + * it can change depending on the page (DRUPAL_CACHE_PER_PAGE) or by user + * (DRUPAL_CACHE_PER_ROLE or DRUPAL_CACHE_PER_USER). Page and user settings can + * be combined with a bitwise-binary or operator; for example, + * DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE means that the block can change + * depending on the user role or page it is on. * * The block cache is cleared in cache_clear_all(), and uses the same clearing * policy than page cache (node, comment, user, taxonomy added or updated...). @@ -123,9 +129,8 @@ define('DRUPAL_NO_CACHE', -1); /** * The block is handling its own caching in its hook_block_view(). * - * From the perspective of the block cache system, this is equivalent to - * DRUPAL_NO_CACHE. Useful when time based expiration is needed or a site uses - * a node access which invalidates standard block cache. + * This setting is useful when time based expiration is needed or a site uses a + * node access which invalidates standard block cache. */ define('DRUPAL_CACHE_CUSTOM', -2); @@ -156,6 +161,10 @@ define('DRUPAL_CACHE_PER_PAGE', 0x0004); define('DRUPAL_CACHE_GLOBAL', 0x0008); /** + * @} End of "defgroup block_caching". + */ + +/** * Adds content to a specified region. * * @param $region @@ -199,7 +208,7 @@ function drupal_get_region_content($region = NULL, $delimiter = ' ') { } /** - * Gets the name of the currently active install profile. + * Gets the name of the currently active installation profile. * * When this function is called during Drupal's initial installation process, * the name of the profile that's about to be installed is stored in the global @@ -208,7 +217,7 @@ function drupal_get_region_content($region = NULL, $delimiter = ' ') { * variable_get() to determine what one is active. * * @return $profile - * The name of the install profile. + * The name of the installation profile. */ function drupal_get_profile() { global $install_state; @@ -443,7 +452,7 @@ function drupal_get_query_parameters(array $query = NULL, array $exclude = array * The query string to split. * * @return - * An array of url decoded couples $param_name => $value. + * An array of URL decoded couples $param_name => $value. */ function drupal_get_query_array($query) { $result = array(); @@ -505,6 +514,12 @@ function drupal_http_build_query(array $query, $parent = '') { * previous request, that destination is returned. As such, a destination can * persist across multiple pages. * + * @return + * An associative array containing the key: + * - destination: The path provided via the destination query string or, if + * not available, the current path. + * + * @see current_path() * @see drupal_goto() */ function drupal_get_destination() { @@ -798,10 +813,51 @@ function drupal_http_request($url, array $options = array()) { 'timeout' => 30.0, 'context' => NULL, ); + + // Merge the default headers. + $options['headers'] += array( + 'User-Agent' => 'Drupal (+http://drupal.org/)', + ); + // stream_socket_client() requires timeout to be a float. $options['timeout'] = (float) $options['timeout']; + // Use a proxy if one is defined and the host is not on the excluded list. + $proxy_server = variable_get('proxy_server', ''); + if ($proxy_server && _drupal_http_use_proxy($uri['host'])) { + // Set the scheme so we open a socket to the proxy server. + $uri['scheme'] = 'proxy'; + // Set the path to be the full URL. + $uri['path'] = $url; + // Since the URL is passed as the path, we won't use the parsed query. + unset($uri['query']); + + // Add in username and password to Proxy-Authorization header if needed. + if ($proxy_username = variable_get('proxy_username', '')) { + $proxy_password = variable_get('proxy_password', ''); + $options['headers']['Proxy-Authorization'] = 'Basic ' . base64_encode($proxy_username . (!empty($proxy_password) ? ":" . $proxy_password : '')); + } + // Some proxies reject requests with any User-Agent headers, while others + // require a specific one. + $proxy_user_agent = variable_get('proxy_user_agent', ''); + // The default value matches neither condition. + if ($proxy_user_agent === NULL) { + unset($options['headers']['User-Agent']); + } + elseif ($proxy_user_agent) { + $options['headers']['User-Agent'] = $proxy_user_agent; + } + } + switch ($uri['scheme']) { + case 'proxy': + // Make the socket connection to a proxy server. + $socket = 'tcp://' . $proxy_server . ':' . variable_get('proxy_port', 8080); + // The Host header still needs to match the real request. + $options['headers']['Host'] = $uri['host']; + $options['headers']['Host'] .= isset($uri['port']) && $uri['port'] != 80 ? ':' . $uri['port'] : ''; + break; + case 'http': case 'feed': $port = isset($uri['port']) ? $uri['port'] : 80; @@ -811,12 +867,14 @@ function drupal_http_request($url, array $options = array()) { // checking the host that do not take into account the port number. $options['headers']['Host'] = $uri['host'] . ($port != 80 ? ':' . $port : ''); break; + case 'https': // Note: Only works when PHP is compiled with OpenSSL support. $port = isset($uri['port']) ? $uri['port'] : 443; $socket = 'ssl://' . $uri['host'] . ':' . $port; $options['headers']['Host'] = $uri['host'] . ($port != 443 ? ':' . $port : ''); break; + default: $result->error = 'invalid schema ' . $uri['scheme']; $result->code = -1003; @@ -853,11 +911,6 @@ function drupal_http_request($url, array $options = array()) { $path .= '?' . $uri['query']; } - // Merge the default headers. - $options['headers'] += array( - 'User-Agent' => 'Drupal (+http://drupal.org/)', - ); - // Only add Content-Length if we actually have any content or if it is a POST // or PUT request. Some non-standard servers get confused by Content-Length in // at least HEAD/GET requests, and Squid always requires Content-Length in @@ -1028,6 +1081,18 @@ function drupal_http_request($url, array $options = array()) { return $result; } + +/** + * Helper function for determining hosts excluded from needing a proxy. + * + * @return + * TRUE if a proxy should be used for this host. + */ +function _drupal_http_use_proxy($host) { + $proxy_exceptions = variable_get('proxy_exceptions', array('localhost', '127.0.0.1')); + return !in_array(strtolower($host), $proxy_exceptions, TRUE); +} + /** * @} End of "HTTP handling". */ @@ -1701,7 +1766,7 @@ function format_xml_elements($array) { * $output = format_plural($update_count, * 'Changed the content type of 1 post from %old-type to %new-type.', * 'Changed the content type of @count posts from %old-type to %new-type.', - * array('%old-type' => $info->old_type, '%new-type' => $info->new_type))); + * array('%old-type' => $info->old_type, '%new-type' => $info->new_type)); * @endcode * * @param $count @@ -2079,7 +2144,7 @@ function format_username($account) { * for the URL. If $options['language'] is omitted, the global $language_url * will be used. * - 'https': Whether this URL should point to a secure location. If not - * defined, the current scheme is used, so the user stays on http or https + * defined, the current scheme is used, so the user stays on HTTP or HTTPS * respectively. TRUE enforces HTTPS and FALSE enforces HTTP, but HTTPS can * only be enforced when the variable 'https' is set to TRUE. * - 'base_url': Only used internally, to modify the base URL when a language @@ -2309,21 +2374,22 @@ function drupal_attributes(array $attributes = array()) { /** * Formats an internal or external URL link as an HTML anchor tag. * - * This function correctly handles aliased paths, and adds an 'active' class + * This function correctly handles aliased paths and adds an 'active' class * attribute to links that point to the current page (for theming), so all * internal links output by modules should be generated by this function if * possible. * - * @param $text - * The link text for the anchor tag. - * @param $path + * @param string $text + * The translated link text for the anchor tag. + * @param string $path * The internal path or external URL being linked to, such as "node/34" or * "http://example.com/foo". After the url() function is called to construct * the URL from $path and $options, the resulting URL is passed through * check_plain() before it is inserted into the HTML anchor tag, to ensure * well-formed HTML. See url() for more information and notes. * @param array $options - * An associative array of additional options, with the following elements: + * An associative array of additional options. Defaults to an empty array. It + * may contain the following elements. * - 'attributes': An associative array of HTML attributes to apply to the * anchor tag. If element 'class' is included, it must be an array; 'title' * must be a string; other elements are more flexible, as they just need @@ -2339,8 +2405,10 @@ function drupal_attributes(array $attributes = array()) { * well as the path must match). This element is also used by url(). * - Additional $options elements used by the url() function. * - * @return + * @return string * An HTML string containing a link to the given path. + * + * @see url() */ function l($text, $path, array $options = array()) { global $language_url; @@ -5114,6 +5182,7 @@ function drupal_cron_run() { @ignore_user_abort(TRUE); // Prevent session information from being saved while cron is running. + $original_session_saving = drupal_save_session(); drupal_save_session(FALSE); // Force the current user to anonymous to ensure consistent permissions on @@ -5176,7 +5245,7 @@ function drupal_cron_run() { } // Restore the user. $GLOBALS['user'] = $original_user; - drupal_save_session(TRUE); + drupal_save_session($original_session_saving); return $return; } @@ -5208,7 +5277,7 @@ function drupal_cron_cleanup() { * drupal_system_listing("/\.module$/", "modules", 'name', 0); * @endcode * this function will search the site-wide modules directory (i.e., /modules/), - * your install profile's directory (i.e., + * your installation profile's directory (i.e., * /profiles/your_site_profile/modules/), the all-sites directory (i.e., * /sites/all/modules/), and your site-specific directory (i.e., * /sites/your_site_dir/modules/), in that order, and return information about @@ -7449,12 +7518,12 @@ function drupal_check_incompatibility($v, $current_version) { /** * Get the entity info array of an entity type. * - * @see hook_entity_info() - * @see hook_entity_info_alter() - * * @param $entity_type * The entity type, e.g. node, for which the info shall be returned, or NULL * to return an array with info about all types. + * + * @see hook_entity_info() + * @see hook_entity_info_alter() */ function entity_get_info($entity_type = NULL) { global $language; @@ -7542,12 +7611,13 @@ function entity_info_cache_clear() { * The entity type; e.g. 'node' or 'user'. * @param $entity * The entity from which to extract values. + * * @return * A numerically indexed array (not a hash table) containing these * elements: - * 0: primary id of the entity - * 1: revision id of the entity, or NULL if $entity_type is not versioned - * 2: bundle name of the entity + * - 0: Primary ID of the entity. + * - 1: Revision ID of the entity, or NULL if $entity_type is not versioned. + * - 2: Bundle name of the entity, or NULL if $entity_type has no bundles. */ function entity_extract_ids($entity_type, $entity) { $info = entity_get_info($entity_type); @@ -7580,13 +7650,12 @@ function entity_extract_ids($entity_type, $entity) { * @param $entity_type * The entity type; e.g. 'node' or 'user'. * @param $ids - * A numerically indexed array, as returned by entity_extract_ids(), - * containing these elements: - * 0: primary id of the entity - * 1: revision id of the entity, or NULL if $entity_type is not versioned - * 2: bundle name of the entity, or NULL if $entity_type has no bundles + * A numerically indexed array, as returned by entity_extract_ids(). + * * @return * An entity structure, initialized with the ids provided. + * + * @see entity_extract_ids() */ function entity_create_stub_entity($entity_type, $ids) { $entity = new stdClass(); @@ -7616,11 +7685,6 @@ function entity_create_stub_entity($entity_type, $ids) { * DrupalDefaultEntityController class. See node_entity_info() and the * NodeController in node.module as an example. * - * @see hook_entity_info() - * @see DrupalEntityControllerInterface - * @see DrupalDefaultEntityController - * @see EntityFieldQuery - * * @param $entity_type * The entity type to load, e.g. node or user. * @param $ids @@ -7638,6 +7702,11 @@ function entity_create_stub_entity($entity_type, $ids) { * found, an empty array is returned. * * @todo Remove $conditions in Drupal 8. + * + * @see hook_entity_info() + * @see DrupalEntityControllerInterface + * @see DrupalDefaultEntityController + * @see EntityFieldQuery */ function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = FALSE) { if ($reset) { @@ -7657,7 +7726,7 @@ function entity_load($entity_type, $ids = FALSE, $conditions = array(), $reset = * @param $entity_type * The entity type to load, e.g. node or user. * @param $id - * The id of the entity to load. + * The ID of the entity to load. * * @return * The unchanged entity, or FALSE if the entity cannot be loaded. @@ -7694,7 +7763,6 @@ function entity_get_controller($entity_type) { * recursion. By convention, entity_prepare_view() is called after * field_attach_prepare_view() to allow entity level hooks to act on content * loaded by field API. - * @see hook_entity_prepare_view() * * @param $entity_type * The type of entity, i.e. 'node', 'user'. @@ -7703,6 +7771,8 @@ function entity_get_controller($entity_type) { * @param $langcode * (optional) A language code to be used for rendering. Defaults to the global * content language of the current request. + * + * @see hook_entity_prepare_view() */ function entity_prepare_view($entity_type, $entities, $langcode = NULL) { if (!isset($langcode)) { @@ -7729,16 +7799,16 @@ function entity_prepare_view($entity_type, $entities, $langcode = NULL) { } /** - * Returns the uri elements of an entity. + * Returns the URI elements of an entity. * * @param $entity_type * The entity type; e.g. 'node' or 'user'. * @param $entity * The entity for which to generate a path. * @return - * An array containing the 'path' and 'options' keys used to build the uri of + * An array containing the 'path' and 'options' keys used to build the URI of * the entity, and matching the signature of url(). NULL if the entity has no - * uri of its own. + * URI of its own. */ function entity_uri($entity_type, $entity) { $info = entity_get_info($entity_type); @@ -7833,7 +7903,7 @@ function entity_language($entity_type, $entity) { } /** - * Helper function for attaching field API validation to entity forms. + * Attaches field API validation to entity forms. */ function entity_form_field_validate($entity_type, $form, &$form_state) { // All field attach API functions act on an entity object, but during form @@ -7846,7 +7916,7 @@ function entity_form_field_validate($entity_type, $form, &$form_state) { } /** - * Helper function for copying submitted values to entity properties for simple entity forms. + * Copies submitted values to entity properties for simple entity forms. * * During the submission handling of an entity form's "Save", "Preview", and * possibly other buttons, the form state's entity needs to be updated with the diff --git a/includes/database/database.inc b/includes/database/database.inc index 5bcae67a3..cae50fb87 100644 --- a/includes/database/database.inc +++ b/includes/database/database.inc @@ -167,7 +167,7 @@ * } * @endcode * - * @link http://drupal.org/developing/api/database + * @link http://drupal.org/developing/api/database @endlink */ @@ -2769,7 +2769,7 @@ function _db_create_keys_sql($spec) { * Renames a table. * * @param $table - * The table to be renamed. + * The current name of the table to be renamed. * @param $new_name * The new name for the table. */ diff --git a/includes/database/log.inc b/includes/database/log.inc index ec27ef8e6..27eae62cd 100644 --- a/includes/database/log.inc +++ b/includes/database/log.inc @@ -128,9 +128,10 @@ class DatabaseLog { * Determine the routine that called this query. * * We define "the routine that called this query" as the first entry in - * the call stack that is not inside includes/database. That makes the - * climbing logic very simple, and handles the variable stack depth caused - * by the query builders. + * the call stack that is not inside includes/database and does have a file + * (which excludes call_user_func_array(), anonymous functions and similar). + * That makes the climbing logic very simple, and handles the variable stack + * depth caused by the query builders. * * @link http://www.php.net/debug_backtrace * @return @@ -144,7 +145,8 @@ class DatabaseLog { $stack = debug_backtrace(); $stack_count = count($stack); for ($i = 0; $i < $stack_count; ++$i) { - if (strpos($stack[$i]['file'], 'includes' . DIRECTORY_SEPARATOR . 'database') === FALSE) { + if (!empty($stack[$i]['file']) && strpos($stack[$i]['file'], 'includes' . DIRECTORY_SEPARATOR . 'database') === FALSE) { + $stack[$i] += array('args' => array()); return array( 'file' => $stack[$i]['file'], 'line' => $stack[$i]['line'], diff --git a/includes/database/pgsql/database.inc b/includes/database/pgsql/database.inc index 79c16b212..00ed7990e 100644 --- a/includes/database/pgsql/database.inc +++ b/includes/database/pgsql/database.inc @@ -74,6 +74,17 @@ class DatabaseConnection_pgsql extends DatabaseConnection { } } + public function prepareQuery($query) { + // mapConditionOperator converts LIKE operations to ILIKE for consistency + // with MySQL. However, Postgres does not support ILIKE on bytea (blobs) + // fields. + // To make the ILIKE operator work, we type-cast bytea fields into text. + // @todo This workaround only affects bytea fields, but the involved field + // types involved in the query are unknown, so there is no way to + // conditionally execute this for affected queries only. + return parent::prepareQuery(preg_replace('/ ([^ ]+) +(I*LIKE|NOT +I*LIKE) /i', ' ${1}::text ${2} ', $query)); + } + public function query($query, array $args = array(), $options = array()) { $options += $this->defaultOptions(); diff --git a/includes/database/sqlite/query.inc b/includes/database/sqlite/query.inc index 74ff9ba20..f0ff10d7d 100644 --- a/includes/database/sqlite/query.inc +++ b/includes/database/sqlite/query.inc @@ -72,11 +72,13 @@ class UpdateQuery_sqlite extends UpdateQuery { */ protected function removeFieldsInCondition(&$fields, QueryConditionInterface $condition) { foreach ($condition->conditions() as $child_condition) { - if ($child_condition['field'] instanceof QueryConditionInterface) { - $this->removeFieldsInCondition($fields, $child_condition['field']); - } - else { - unset($fields[$child_condition['field']]); + if (isset($child_condition['field'])) { + if ($child_condition['field'] instanceof ConditionInterface) { + $this->removeFieldsInCondition($fields, $child_condition['field']); + } + else { + unset($fields[$child_condition['field']]); + } } } } diff --git a/includes/entity.inc b/includes/entity.inc index 832abe2fd..2fefd5904 100644 --- a/includes/entity.inc +++ b/includes/entity.inc @@ -296,6 +296,7 @@ class DrupalDefaultEntityController implements DrupalEntityControllerInterface { /** * Attaches data to entities upon loading. + * * This will attach fields, if the entity is fieldable. It calls * hook_entity_load() for modules which need to add data to all entities. * It also calls hook_TYPE_load() on the loaded entities. For example @@ -415,13 +416,14 @@ class EntityFieldQueryException extends Exception {} * an EntityFieldQueryException will be raised if an unsupported condition is * specified or if the query has field conditions or sorts that are stored in * different field storage engines. However, this logic can be overridden in - * hook_entity_query(). + * hook_entity_query_alter(). * * Also note that this query does not automatically respect entity access * restrictions. Node access control is performed by the SQL storage engine but * other storage engines might not do this. */ class EntityFieldQuery { + /** * Indicates that both deleted and non-deleted fields should be returned. * @@ -594,9 +596,7 @@ class EntityFieldQuery { * * 'bundle', 'revision_id' and 'entity_id' have no such restrictions. * - * Note: The "comment" and "taxonomy_term" entity types don't support bundle - * conditions. For "taxonomy_term", propertyCondition('vid') can be used - * instead. + * Note: The "comment" entity type does not support bundle conditions. * * @param $name * 'entity_type', 'bundle', 'revision_id' or 'entity_id'. @@ -958,7 +958,7 @@ class EntityFieldQuery { } /** - * Enable a pager for the query. + * Enables a pager for the query. * * @param $limit * An integer specifying the number of elements per page. If passed a false @@ -986,10 +986,11 @@ class EntityFieldQuery { } /** - * Enable sortable tables for this query. + * Enables sortable tables for this query. * * @param $headers - * An EFQ Header array based on which the order clause is added to the query. + * An EFQ Header array based on which the order clause is added to the + * query. * * @return EntityFieldQuery * The called object. @@ -1272,7 +1273,7 @@ class EntityFieldQuery { } /** - * Get the total number of results and initialize a pager for the query. + * Gets the total number of results and initializes a pager for the query. * * The pager can be disabled by either setting the pager limit to 0, or by * setting this query to be a count query. @@ -1359,6 +1360,6 @@ class EntityFieldQuery { } /** - * Exception thrown when a malformed entity is passed. + * Defines an exception thrown when a malformed entity is passed. */ class EntityMalformedException extends Exception { } diff --git a/includes/errors.inc b/includes/errors.inc index 9d0df0544..7fd2de2fb 100644 --- a/includes/errors.inc +++ b/includes/errors.inc @@ -6,21 +6,6 @@ */ /** - * Error reporting level: display no errors. - */ -define('ERROR_REPORTING_HIDE', 0); - -/** - * Error reporting level: display errors and warnings. - */ -define('ERROR_REPORTING_DISPLAY_SOME', 1); - -/** - * Error reporting level: display all messages. - */ -define('ERROR_REPORTING_DISPLAY_ALL', 2); - -/** * Maps PHP error constants to watchdog severity levels. * * The error constants are documented at diff --git a/includes/file.inc b/includes/file.inc index c5e5cf07d..1e256c634 100644 --- a/includes/file.inc +++ b/includes/file.inc @@ -398,8 +398,8 @@ function file_create_url($uri) { } } elseif ($scheme == 'http' || $scheme == 'https') { - // Check for http so that we don't have to implement getExternalUrl() for - // the http wrapper. + // Check for HTTP so that we don't have to implement getExternalUrl() for + // the HTTP wrapper. return $uri; } else { @@ -2236,7 +2236,7 @@ function drupal_realpath($uri) { if ($wrapper = file_stream_wrapper_get_instance_by_uri($uri)) { return $wrapper->realpath(); } - // Check that the uri has a value. There is a bug in PHP 5.2 on *BSD systems + // Check that the URI has a value. There is a bug in PHP 5.2 on *BSD systems // that makes realpath not return FALSE as expected when passing an empty // variable. // @todo Remove when Drupal drops support for PHP 5.2. @@ -2489,7 +2489,7 @@ function file_get_content_headers($file) { } return array( - 'Content-Type' => $type . '; name="' . $name . '"', + 'Content-Type' => $type, 'Content-Length' => $file->filesize, 'Content-Disposition' => $disposition . '; filename="' . $name . '"', 'Cache-Control' => 'private', diff --git a/includes/filetransfer/filetransfer.inc b/includes/filetransfer/filetransfer.inc index bd2057cdd..023b866e3 100644 --- a/includes/filetransfer/filetransfer.inc +++ b/includes/filetransfer/filetransfer.inc @@ -381,7 +381,7 @@ interface FileTransferChmodInterface { * @param string $path * Path to change permissions of. * @param long $mode - * @see http://php.net/chmod + * The new file permission mode to be passed to chmod(). * @param boolean $recursive * Pass TRUE to recursively chmod the entire directory specified in $path. */ diff --git a/includes/form.inc b/includes/form.inc index d7350b3e2..826b6777b 100644 --- a/includes/form.inc +++ b/includes/form.inc @@ -78,7 +78,7 @@ * the elements and properties of the form. For information on the array * components and format, and more detailed explanations of the Form API * workflow, see the - * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html Form API reference @endlink + * @link forms_api_reference.html Form API reference @endlink * and the * @link http://drupal.org/node/37775 Form API documentation section. @endlink * In addition, there is a set of Form API tutorials in @@ -215,17 +215,15 @@ function drupal_get_form($form_id) { * set. * - values: An associative array of values submitted to the form. The * validation functions and submit functions use this array for nearly all - * their decision making. (Note that - * @link http://api.drupal.org/api/drupal/developer--topics--forms_api_reference.html/7#tree #tree @endlink - * determines whether the values are a flat array or an array whose - * structure parallels the $form array.) - * - input: The array of values as they were submitted by the user. These are - * raw and unvalidated, so should not be used without a thorough - * understanding of security implications. In almost all cases, code should - * use the data in the 'values' array exclusively. The most common use of - * this key is for multi-step forms that need to clear some of the user - * input when setting 'rebuild'. The values correspond to $_POST or $_GET, - * depending on the 'method' chosen. + * their decision making. (Note that #tree determines whether the values are + * a flat array or an array whose structure parallels the $form array. See + * @link forms_api_reference.html Form API reference @endlink for more + * information.) These are raw and unvalidated, so should not be used + * without a thorough understanding of security implications. In almost all + * cases, code should use the data in the 'values' array exclusively. The + * most common use of this key is for multi-step forms that need to clear + * some of the user input when setting 'rebuild'. The values correspond to + * $_POST or $_GET, depending on the 'method' chosen. * - always_process: If TRUE and the method is GET, a form_id is not * necessary. This should only be used on RESTful GET forms that do NOT * write data, as this could lead to security issues. It is useful so that @@ -730,7 +728,7 @@ function drupal_retrieve_form($form_id, &$form_state) { // the form builder callbacks can be loaded when the form is being rebuilt // from cache on a different path (such as 'system/ajax'). See // form_get_cache(). - // $menu_get_item() is not available at installation time. + // $menu_get_item() is not available during installation. if (!isset($form_state['build_info']['files']['menu']) && !defined('MAINTENANCE_MODE')) { $item = menu_get_item(); if (!empty($item['include_file'])) { @@ -1177,18 +1175,23 @@ function drupal_validate_form($form_id, &$form, &$form_state) { /** * Redirects the user to a URL after a form has been processed. * - * After a form was executed, the data in $form_state controls whether the form - * is redirected. By default, we redirect to a new destination page. The path - * of the destination page can be set in $form_state['redirect'], as either a - * string containing the destination or an array of arguments compatible with - * drupal_goto(). If that is not set, the user is redirected to the current - * page to display a fresh, unpopulated copy of the form. + * After a form is submitted and processed, normally the user should be + * redirected to a new destination page. This function figures out what that + * destination should be, based on the $form_state array and the 'destination' + * query string in the request URL, and redirects the user there. * - * For example, to redirect to 'node': + * Usually (for exceptions, see below) $form_state['redirect'] determines where + * to redirect the user. This can be set either to a string (the path to + * redirect to), or an array of arguments for drupal_goto(). If + * $form_state['redirect'] is missing, the user is usually (again, see below for + * exceptions) redirected back to the page they came from, where they should see + * a fresh, unpopulated copy of the form. + * + * Here is an example of how to set up a form to redirect to the path 'node': * @code * $form_state['redirect'] = 'node'; * @endcode - * Or to redirect to 'node/123?foo=bar#baz': + * And here is an example of how to redirect to 'node/123?foo=bar#baz': * @code * $form_state['redirect'] = array( * 'node/123', @@ -1201,29 +1204,27 @@ function drupal_validate_form($form_id, &$form, &$form_state) { * ); * @endcode * - * There are several triggers that may prevent a redirection though: - * - If $form_state['redirect'] is FALSE, a form builder function or form - * validation/submit handler does not want a user to be redirected, which - * means that drupal_goto() is not invoked. For most forms, the redirection - * logic will be the same regardless of whether $form_state['redirect'] is - * undefined or FALSE. However, in case it was not defined and the current - * request contains a 'destination' query string, drupal_goto() will redirect - * to that given destination instead. Only setting $form_state['redirect'] to - * FALSE will prevent any redirection. - * - If $form_state['no_redirect'] is TRUE, then the callback that originally - * built the form explicitly disallows any redirection, regardless of the - * redirection value in $form_state['redirect']. For example, ajax_get_form() - * defines $form_state['no_redirect'] when building a form in an Ajax - * callback to prevent any redirection. $form_state['no_redirect'] should NOT - * be altered by form builder functions or form validation/submit handlers. + * There are several exceptions to the "usual" behavior described above: * - If $form_state['programmed'] is TRUE, the form submission was usually * invoked via drupal_form_submit(), so any redirection would break the script - * that invoked drupal_form_submit(). - * - If $form_state['rebuild'] is TRUE, the form needs to be rebuilt without - * redirection. + * that invoked drupal_form_submit() and no redirection is done. + * - If $form_state['rebuild'] is TRUE, the form is being rebuilt, and no + * redirection is done. + * - If $form_state['no_redirect'] is TRUE, redirection is disabled. This is + * set, for instance, by ajax_get_form() to prevent redirection in Ajax + * callbacks. $form_state['no_redirect'] should never be set or altered by + * form builder functions or form validation/submit handlers. + * - If $form_state['redirect'] is set to FALSE, redirection is disabled. + * - If none of the above conditions has prevented redirection, then the + * redirect is accomplished by calling drupal_goto(), passing in the value of + * $form_state['redirect'] if it is set, or the current path if it is + * not. drupal_goto() preferentially uses the value of $_GET['destination'] + * (the 'destination' URL query string) if it is present, so this will + * override any values set by $form_state['redirect']. Note that during + * installation, install_goto() is called in place of drupal_goto(). * * @param $form_state - * A keyed array containing the current state of the form. + * An associative array containing the current state of the form. * * @see drupal_process_form() * @see drupal_build_form() @@ -1255,7 +1256,7 @@ function drupal_redirect_form($form_state) { $function($form_state['redirect']); } } - drupal_goto($_GET['q']); + drupal_goto(current_path(), array('query' => drupal_get_query_parameters())); } } @@ -3251,21 +3252,6 @@ function theme_container($variables) { /** * Returns HTML for a table with radio buttons or checkboxes. * - * An example of per-row options: - * @code - * $options = array(); - * $options[0]['title'] = "A red row" - * $options[0]['#attributes'] = array ('class' => array('red-row')); - * $options[1]['title'] = "A blue row" - * $options[1]['#attributes'] = array ('class' => array('blue-row')); - * - * $form['myselector'] = array ( - * '#type' => 'tableselect', - * '#title' => 'My Selector' - * '#options' => $options, - * ); - * @endcode - * * @param $variables * An associative array containing: * - element: An associative array containing the properties and children of @@ -3273,7 +3259,35 @@ function theme_container($variables) { * and #js_select. The #options property is an array of selection options; * each array element of #options is an array of properties. These * properties can include #attributes, which is added to the - * table row's HTML attributes; see theme_table(). + * table row's HTML attributes; see theme_table(). An example of per-row + * options: + * @code + * $options = array( + * array( + * 'title' => 'How to Learn Drupal', + * 'content_type' => 'Article', + * 'status' => 'published', + * '#attributes' => array('class' => array('article-row')), + * ), + * array( + * 'title' => 'Privacy Policy', + * 'content_type' => 'Page', + * 'status' => 'published', + * '#attributes' => array('class' => array('page-row')), + * ), + * ); + * $header = array( + * 'title' => t('Title'), + * 'content_type' => t('Content type'), + * 'status' => t('Status'), + * ); + * $form['table'] = array( + * '#type' => 'tableselect', + * '#header' => $header, + * '#options' => $options, + * '#empty' => t('No content available.'), + * ); + * @endcode * * @ingroup themeable */ @@ -3645,6 +3659,35 @@ function form_pre_render_fieldset($element) { /** * Creates a group formatted as vertical tabs. * + * Note that autocomplete callbacks should include special handling as the + * user's input may contain forward slashes. If the user-submitted string has a + * '/' in the text that is sent in the autocomplete request, the menu system + * will split the text and pass it to the callback as multiple arguments. + * + * Suppose your autocomplete path in the menu system is 'mymodule_autocomplete.' + * In your form you have: + * @code + * '#autocomplete_path' => 'mymodule_autocomplete/' . $some_key . '/' . $some_id, + * @endcode + * The user types in "keywords" so the full path called is: + * 'mymodule_autocomplete/$some_key/$some_id/keywords' + * + * You should include code similar to the following to handle slashes in the + * input: + * @code + * function mymodule_autocomplete_callback($arg1, $arg2, $keywords) { + * $args = func_get_args(); + * // We need to remove $arg1 and $arg2 from the beginning of the array so we + * // are left with the keywords. + * array_shift($args); + * array_shift($args); + * // We store the user's original input in $keywords, including any slashes. + * $keywords = implode('/', $args); + * + * // Your code here. + * } + * @endcode + * * @param $element * An associative array containing the properties and children of the * fieldset. @@ -4363,7 +4406,7 @@ function batch_set($batch_definition) { } // Base and default properties for the batch set. - // Use get_t() to allow batches at install time. + // Use get_t() to allow batches during installation. $t = get_t(); $init = array( 'sandbox' => array(), diff --git a/includes/image.inc b/includes/image.inc index f6ae7f19b..ee5a086de 100644 --- a/includes/image.inc +++ b/includes/image.inc @@ -34,7 +34,7 @@ */ /** - * Return a list of available toolkits. + * Gets a list of available toolkits. * * @return * An array with the toolkit names as keys and the descriptions as values. @@ -55,7 +55,7 @@ function image_get_available_toolkits() { } /** - * Retrieve the name of the currently used toolkit. + * Gets the name of the currently used toolkit. * * @return * String containing the name of the selected toolkit, or FALSE on error. @@ -101,7 +101,7 @@ function image_toolkit_invoke($method, stdClass $image, array $params = array()) } /** - * Get details about an image. + * Gets details about an image. * * Drupal supports GIF, JPG and PNG file formats when used with the GD * toolkit, and may support others, depending on which toolkits are @@ -261,7 +261,7 @@ function image_scale(stdClass $image, $width = NULL, $height = NULL, $upscale = } /** - * Resize an image to the given dimensions (ignoring aspect ratio). + * Resizes an image to the given dimensions (ignoring aspect ratio). * * @param $image * An image object returned by image_load(). @@ -284,7 +284,7 @@ function image_resize(stdClass $image, $width, $height) { } /** - * Rotate an image by the given number of degrees. + * Rotates an image by the given number of degrees. * * @param $image * An image object returned by image_load(). @@ -308,7 +308,7 @@ function image_rotate(stdClass $image, $degrees, $background = NULL) { } /** - * Crop an image to the rectangle specified by the given rectangle. + * Crops an image to a rectangle specified by the given dimensions. * * @param $image * An image object returned by image_load(). @@ -340,7 +340,7 @@ function image_crop(stdClass $image, $x, $y, $width, $height) { } /** - * Convert an image to grayscale. + * Converts an image to grayscale. * * @param $image * An image object returned by image_load(). @@ -355,9 +355,8 @@ function image_desaturate(stdClass $image) { return image_toolkit_invoke('desaturate', $image); } - /** - * Load an image file and return an image object. + * Loads an image file and returns an image object. * * Any changes to the file are not saved until image_save() is called. * @@ -400,7 +399,7 @@ function image_load($file, $toolkit = FALSE) { } /** - * Close the image and save the changes to a file. + * Closes the image and saves the changes to a file. * * @param $image * An image object returned by image_load(). The object's 'info' property diff --git a/includes/install.core.inc b/includes/install.core.inc index 7bcd026ae..9805e1c88 100644 --- a/includes/install.core.inc +++ b/includes/install.core.inc @@ -6,8 +6,7 @@ */ /** - * Global flag to indicate that a task should not be run during the current - * installation request. + * Do not run the task during the current installation request. * * This can be used to skip running an installation task when certain * conditions are met, even though the task may still show on the list of @@ -20,8 +19,7 @@ define('INSTALL_TASK_SKIP', 1); /** - * Global flag to indicate that a task should be run on each installation - * request that reaches it. + * Run the task on each installation request until the database is set up. * * This is primarily used by the Drupal installer for bootstrap-related tasks. */ @@ -200,7 +198,7 @@ function install_state_defaults() { } /** - * Begin an installation request, modifying the installation state as needed. + * Begins an installation request, modifying the installation state as needed. * * This function performs commands that must run at the beginning of every page * request. It throws an exception if the installation should not proceed. @@ -524,7 +522,7 @@ function install_tasks($install_state) { $needs_translations = count($install_state['locales']) > 1 && !empty($install_state['parameters']['locale']) && $install_state['parameters']['locale'] != 'en'; // Start with the core installation tasks that run before handing control - // to the install profile. + // to the installation profile. $tasks = array( 'install_select_profile' => array( 'display_name' => st('Choose profile'), @@ -708,7 +706,7 @@ function install_display_output($output, $install_state) { } /** - * Installation task; verify the requirements for installing Drupal. + * Verifies the requirements for installing Drupal. * * @param $install_state * An array of information about the current installation state. @@ -776,7 +774,7 @@ function install_system_module(&$install_state) { // variable_set() can be used now that system.module is installed. $modules = $install_state['profile_info']['dependencies']; - // The install profile is also a module, which needs to be installed + // The installation profile is also a module, which needs to be installed // after all the dependencies have been installed. $modules[] = drupal_get_profile(); @@ -785,7 +783,7 @@ function install_system_module(&$install_state) { } /** - * Verify and return the last installation task that was completed. + * Verifies and returns the last installation task that was completed. * * @return * The last completed task, if there is one. An exception is thrown if Drupal @@ -829,7 +827,7 @@ function install_verify_settings() { } /** - * Verify PDO library. + * Verifies the PDO library. */ function install_verify_pdo() { // PDO was moved to PHP core in 5.2.0, but the old extension (targeting 5.0 @@ -841,15 +839,14 @@ function install_verify_pdo() { } /** - * Installation task; define a form to configure and rewrite settings.php. + * Form constructor for a form to configure and rewrite settings.php. * - * @param $form_state - * An associative array containing the current state of the form. * @param $install_state * An array of information about the current installation state. * - * @return - * The form API definition for the database configuration form. + * @see install_settings_form_validate() + * @see install_settings_form_submit() + * @ingroup forms */ function install_settings_form($form, &$form_state, &$install_state) { global $databases; @@ -912,7 +909,9 @@ function install_settings_form($form, &$form_state, &$install_state) { } /** - * Form API validate for install_settings form. + * Form validation handler for install_settings_form(). + * + * @see install_settings_form_submit() */ function install_settings_form_validate($form, &$form_state) { $driver = $form_state['values']['driver']; @@ -969,7 +968,9 @@ function install_database_errors($database, $settings_file) { } /** - * Form API submit for install_settings form. + * Form submission handler for install_settings_form(). + * + * @see install_settings_form_validate() */ function install_settings_form_submit($form, &$form_state) { global $install_state; @@ -1000,7 +1001,7 @@ function install_find_profiles() { } /** - * Installation task; select which profile to install. + * Selects which profile to install. * * @param $install_state * An array of information about the current installation state. The chosen @@ -1040,8 +1041,7 @@ function install_select_profile(&$install_state) { } /** - * Helper function for automatically selecting an installation profile from a - * list or from a selection passed in via $_POST. + * Selects an installation profile from a list or from a $_POST submission. */ function _install_select_profile($profiles) { if (sizeof($profiles) == 0) { @@ -1064,12 +1064,14 @@ function _install_select_profile($profiles) { } /** - * Form API array definition for the profile selection form. + * Form constructor for the profile selection form. * * @param $form_state * Array of metadata about state of form processing. * @param $profile_files * Array of .profile files, as returned from file_scan_directory(). + * + * @ingroup forms */ function install_select_profile_form($form, &$form_state, $profile_files) { $profiles = array(); @@ -1246,7 +1248,9 @@ function install_select_locale(&$install_state) { } /** - * Form API array definition for language selection. + * Form constructor for the language selection form. + * + * @ingroup forms */ function install_select_locale_form($form, &$form_state, $locales, $profilename) { include_once DRUPAL_ROOT . '/includes/iso.inc'; @@ -1296,7 +1300,7 @@ function install_already_done_error() { } /** - * Installation task; load information about the chosen profile. + * Loads information about the chosen profile during installation. * * @param $install_state * An array of information about the current installation state. The loaded @@ -1315,7 +1319,7 @@ function install_load_profile(&$install_state) { } /** - * Installation task; perform a full bootstrap of Drupal. + * Performs a full bootstrap of Drupal during installation. * * @param $install_state * An array of information about the current installation state. @@ -1325,7 +1329,7 @@ function install_bootstrap_full(&$install_state) { } /** - * Installation task; install required modules via a batch process. + * Installs required modules via a batch process. * * @param $install_state * An array of information about the current installation state. @@ -1378,7 +1382,7 @@ function install_profile_modules(&$install_state) { } /** - * Installation task; import languages via a batch process. + * Imports languages via a batch process during installation. * * @param $install_state * An array of information about the current installation state. @@ -1412,15 +1416,14 @@ function install_import_locales(&$install_state) { } /** - * Installation task; configure settings for the new site. + * Form constructor for a form to configure the new site. * - * @param $form_state - * An associative array containing the current state of the form. * @param $install_state * An array of information about the current installation state. * - * @return - * The form API definition for the site configuration form. + * @see install_configure_form_validate() + * @see install_configure_form_submit() + * @ingroup forms */ function install_configure_form($form, &$form_state, &$install_state) { drupal_set_title(st('Configure site')); @@ -1443,7 +1446,7 @@ function install_configure_form($form, &$form_state, &$install_state) { // Add JavaScript time zone detection. drupal_add_js('misc/timezone.js'); // We add these strings as settings because JavaScript translation does not - // work on install time. + // work during installation. drupal_add_js(array('copyFieldValue' => array('edit-site-mail' => array('edit-account-mail'))), 'setting'); drupal_add_js('jQuery(function () { Drupal.cleanURLsInstallCheck(); });', 'inline'); // Add JS to show / hide the 'Email administrator about site updates' elements @@ -1486,7 +1489,7 @@ function install_import_locales_remaining(&$install_state) { } /** - * Installation task; perform final steps and display a 'finished' page. + * Finishes importing files at end of installation. * * @param $install_state * An array of information about the current installation state. @@ -1502,13 +1505,13 @@ function install_finished(&$install_state) { // Flush all caches to ensure that any full bootstraps during the installer // do not leave stale cached data, and that any content types or other items - // registered by the install profile are registered correctly. + // registered by the installation profile are registered correctly. drupal_flush_all_caches(); // Remember the profile which was used. variable_set('install_profile', drupal_get_profile()); - // Install profiles are always loaded last + // Installation profiles are always loaded last db_update('system') ->fields(array('weight' => 1000)) ->condition('type', 'module') @@ -1673,7 +1676,15 @@ function install_check_requirements($install_state) { } /** - * Forms API array definition for site configuration. + * Form constructor for a site configuration form. + * + * @param $install_state + * An array of information about the current installation state. + * + * @see install_configure_form() + * @see install_configure_form_validate() + * @see install_configure_form_submit() + * @ingroup forms */ function _install_configure_form($form, &$form_state, &$install_state) { include_once DRUPAL_ROOT . '/includes/locale.inc'; @@ -1786,7 +1797,9 @@ function _install_configure_form($form, &$form_state, &$install_state) { } /** - * Forms API validate for the site configuration form. + * Form validation handler for install_configure_form(). + * + * @see install_configure_form_submit() */ function install_configure_form_validate($form, &$form_state) { if ($error = user_validate_name($form_state['values']['account']['name'])) { @@ -1801,7 +1814,9 @@ function install_configure_form_validate($form, &$form_state) { } /** - * Forms API submit for the site configuration form. + * Form submission handler for install_configure_form(). + * + * @see install_configure_form_validate() */ function install_configure_form_submit($form, &$form_state) { global $user; diff --git a/includes/install.inc b/includes/install.inc index 6411f8f19..0372483b6 100644 --- a/includes/install.inc +++ b/includes/install.inc @@ -1,6 +1,11 @@ <?php /** +* @file +* API functions for installing modules and themes. +*/ + +/** * Indicates that a module has not been installed yet. */ define('SCHEMA_UNINSTALLED', -1); @@ -71,7 +76,7 @@ define('FILE_NOT_WRITABLE', 64); define('FILE_NOT_EXECUTABLE', 128); /** - * Initialize the update system by loading all installed module's .install files. + * Loads .install files for installed modules to initialize the update system. */ function drupal_load_updates() { foreach (drupal_get_installed_schema_version(NULL, FALSE, TRUE) as $module => $schema_version) { @@ -180,11 +185,11 @@ function drupal_set_installed_schema_version($module, $version) { } /** - * Loads the install profile, extracting its defined distribution name. + * Loads the installation profile, extracting its defined distribution name. * * @return * The distribution name defined in the profile's .info file. Defaults to - * "Drupal" if none is explicitly provided by the install profile. + * "Drupal" if none is explicitly provided by the installation profile. * * @see install_profile_info() */ @@ -204,11 +209,12 @@ function drupal_install_profile_distribution_name() { } /** - * Auto detect the base_url with PHP predefined variables. + * Detects the base URL using the PHP $_SERVER variables. * * @param $file * The name of the file calling this function so we can strip it out of * the URI when generating the base_url. + * * @return * The auto-detected $base_url that should be configured in settings.php */ @@ -223,7 +229,7 @@ function drupal_detect_baseurl($file = 'install.php') { } /** - * Detect all supported databases that are compiled into PHP. + * Detects all supported databases that are compiled into PHP. * * @return * An array of database types compiled into PHP. @@ -239,7 +245,7 @@ function drupal_detect_database_types() { } /** - * Return all supported database installer objects that are compiled into PHP. + * Returns all supported database installer objects that are compiled into PHP. * * @return * An array of database installer objects compiled into PHP. @@ -576,7 +582,7 @@ class DatabaseTaskException extends Exception { } /** - * Replace values in settings.php with values in the submitted array. + * Replaces values in settings.php with values in the submitted array. * * @param $settings * An array of settings that need to be updated. @@ -654,10 +660,11 @@ function drupal_rewrite_settings($settings = array(), $prefix = '') { } /** - * Verify an install profile for installation. + * Verifies an installation profile for installation. * * @param $install_state * An array of information about the current installation state. + * * @return * The list of modules to install. */ @@ -681,8 +688,8 @@ function drupal_verify_profile($install_state) { $present_modules[] = $present_module->name; } - // The install profile is also a module, which needs to be installed after all the other dependencies - // have been installed. + // The installation profile is also a module, which needs to be installed + // after all the other dependencies have been installed. $present_modules[] = drupal_get_profile(); // Verify that all of the profile's required modules are present. @@ -706,7 +713,7 @@ function drupal_verify_profile($install_state) { } /** - * Callback to install the system module. + * Installs the system module. * * Separated from the installation of other modules so core system * functions can be made available while other modules are installed. @@ -800,7 +807,7 @@ function drupal_uninstall_modules($module_list = array(), $uninstall_dependents } /** - * Verify the state of the specified file. + * Verifies the state of the specified file. * * @param $file * The file to check for. @@ -808,6 +815,7 @@ function drupal_uninstall_modules($module_list = array(), $uninstall_dependents * An optional bitmask created from various FILE_* constants. * @param $type * The type of file. Can be file (default), dir, or link. + * * @return * TRUE on success or FALSE on failure. A message is set for the latter. */ @@ -879,7 +887,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') { } /** - * Create a directory with specified permissions. + * Creates a directory with the specified permissions. * * @param $file * The name of the directory to create; @@ -887,6 +895,7 @@ function drupal_verify_install_file($file, $mask = NULL, $type = 'file') { * The permissions of the directory to create. * @param $message * (optional) Whether to output messages. Defaults to TRUE. + * * @return * TRUE/FALSE whether or not the directory was successfully created. */ @@ -918,7 +927,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) { } /** - * Attempt to fix file permissions. + * Attempts to fix file permissions. * * The general approach here is that, because we do not know the security * setup of the webserver, we apply our permission changes to all three @@ -935,6 +944,7 @@ function drupal_install_mkdir($file, $mask, $message = TRUE) { * The desired permissions for the file. * @param $message * (optional) Whether to output messages. Defaults to TRUE. + * * @return * TRUE/FALSE whether or not we were able to fix the file's permissions. */ @@ -1000,7 +1010,7 @@ function drupal_install_fix_file($file, $mask, $message = TRUE) { } /** - * Send the user to a different installer page. + * Sends the user to a different installer page. * * This issues an on-site HTTP redirect. Messages (and errors) are erased. * @@ -1078,7 +1088,7 @@ function drupal_requirements_url($severity) { } /** - * Functional equivalent of t(), used when some systems are not available. + * Translates a string when some systems are not available. * * Used during the install process, when database, theme, and localization * system is possibly not yet available. @@ -1138,12 +1148,12 @@ function st($string, array $args = array(), array $options = array()) { } /** - * Check an install profile's requirements. + * Checks an installation profile's requirements. * * @param $profile - * Name of install profile to check. + * Name of installation profile to check. * @return - * Array of the install profile's requirements. + * Array of the installation profile's requirements. */ function drupal_check_profile($profile) { include_once DRUPAL_ROOT . '/includes/file.inc'; @@ -1169,11 +1179,12 @@ function drupal_check_profile($profile) { } /** - * Extract highest severity from requirements array. + * Extracts the highest severity from the requirements array. * * @param $requirements * An array of requirements, in the same format as is returned by * hook_requirements(). + * * @return * The highest severity in the array. */ @@ -1188,12 +1199,13 @@ function drupal_requirements_severity(&$requirements) { } /** - * Check a module's requirements. + * Checks a module's requirements. * * @param $module * Machine name of module to check. + * * @return - * TRUE/FALSE depending on the requirements are in place. + * TRUE or FALSE, depending on whether the requirements are met. */ function drupal_check_module($module) { module_load_install($module); @@ -1218,13 +1230,14 @@ function drupal_check_module($module) { } /** - * Retrieve info about an install profile from its .info file. + * Retrieves information about an installation profile from its .info file. * * The information stored in a profile .info file is similar to that stored in * a normal Drupal module .info file. For example: - * - name: The real name of the install profile for display purposes. + * - name: The real name of the installation profile for display purposes. * - description: A brief description of the profile. - * - dependencies: An array of shortnames of other modules this install profile requires. + * - dependencies: An array of shortnames of other modules that this install + * profile requires. * * Additional, less commonly-used information that can appear in a profile.info * file but not in a normal Drupal module .info file includes: diff --git a/includes/iso.inc b/includes/iso.inc index a88de57e9..6c66c569f 100644 --- a/includes/iso.inc +++ b/includes/iso.inc @@ -461,7 +461,7 @@ function _locale_get_predefined_list() { 'tt' => array('Tatar', 'Tatarça'), 'tw' => array('Twi'), 'ty' => array('Tahitian'), - 'ug' => array('Uighur'), + 'ug' => array('Uyghur'), 'uk' => array('Ukrainian', 'Українська'), 'ur' => array('Urdu', /* Left-to-right marker "" */ 'اردو', LANGUAGE_RTL), 'uz' => array('Uzbek', "o'zbek"), diff --git a/includes/language.inc b/includes/language.inc index 20909f5a6..d0ea83113 100644 --- a/includes/language.inc +++ b/includes/language.inc @@ -190,6 +190,11 @@ function language_negotiation_get_switch_links($type, $path) { $links = FALSE; $negotiation = variable_get("language_negotiation_$type", array()); + // Only get the languages if we have more than one. + if (count(language_list()) >= 2) { + $language = language_initialize($type); + } + foreach ($negotiation as $id => $provider) { if (isset($provider['callbacks']['switcher'])) { if (isset($provider['file'])) { @@ -199,6 +204,12 @@ function language_negotiation_get_switch_links($type, $path) { $callback = $provider['callbacks']['switcher']; $result = $callback($type, $path); + // Add support for WCAG 2.0's Language of Parts to add language identifiers. + // http://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html + foreach ($result as $langcode => $link) { + $result[$langcode]['attributes']['lang'] = $langcode; + } + if (!empty($result)) { // Allow modules to provide translations for specific links. drupal_alter('language_switch_links', $result, $type, $path); @@ -408,7 +419,7 @@ function language_from_default() { } /** - * Split the given path into prefix and actual path. + * Splits the given path into prefix and actual path. * * Parse the given path and return the language object identified by the * prefix and the actual path. @@ -440,10 +451,10 @@ function language_url_split_prefix($path, $languages) { } /** - * Return the possible fallback languages ordered by language weight. + * Returns the possible fallback languages ordered by language weight. * * @param - * The language type. + * (optional) The language type. Defaults to LANGUAGE_TYPE_CONTENT. * * @return * An array of language codes. diff --git a/includes/mail.inc b/includes/mail.inc index 13a6f4643..8479d8e9b 100644 --- a/includes/mail.inc +++ b/includes/mail.inc @@ -13,7 +13,7 @@ define('MAIL_LINE_ENDINGS', isset($_SERVER['WINDIR']) || strpos($_SERVER['SERVER_SOFTWARE'], 'Win32') !== FALSE ? "\r\n" : "\n"); /** - * Compose and optionally send an e-mail message. + * Composes and optionally sends an e-mail message. * * Sending an e-mail works with defining an e-mail template (subject, text * and possibly e-mail headers) and the replacement values to use in the @@ -191,7 +191,7 @@ function drupal_mail($module, $key, $to, $language, $params = array(), $from = N } /** - * Returns an object that implements the MailSystemInterface. + * Returns an object that implements the MailSystemInterface interface. * * Allows for one or more custom mail backends to format and send mail messages * composed using drupal_mail(). @@ -328,7 +328,7 @@ interface MailSystemInterface { } /** - * Perform format=flowed soft wrapping for mail (RFC 3676). + * Performs format=flowed soft wrapping for mail (RFC 3676). * * We use delsp=yes wrapping, but only break non-spaced languages when * absolutely necessary to avoid compatibility issues. @@ -340,6 +340,9 @@ interface MailSystemInterface { * @param $indent (optional) * A string to indent the text with. Only '>' characters are repeated on * subsequent wrapped lines. Others are replaced by spaces. + * + * @return + * The content of the email as a string with formatting applied. */ function drupal_wrap_mail($text, $indent = '') { // Convert CRLF into LF. @@ -371,8 +374,7 @@ function drupal_wrap_mail($text, $indent = '') { } /** - * Transform an HTML string into plain text, preserving the structure of the - * markup. Useful for preparing the body of a node to be sent by e-mail. + * Transforms an HTML string into plain text, preserving its structure. * * The output will be suitable for use as 'format=flowed; delsp=yes' text * (RFC 3676) and can be passed directly to drupal_mail() for sending. @@ -551,9 +553,9 @@ function drupal_html_to_text($string, $allowed_tags = NULL) { } /** - * Helper function for array_walk in drupal_wrap_mail(). - * * Wraps words on a single line. + * + * Callback for array_walk() winthin drupal_wrap_mail(). */ function _drupal_wrap_mail_line(&$line, $key, $values) { // Use soft-breaks only for purely quoted or unindented text. @@ -563,9 +565,9 @@ function _drupal_wrap_mail_line(&$line, $key, $values) { } /** - * Helper function for drupal_html_to_text(). - * * Keeps track of URLs and replaces them with placeholder tokens. + * + * Callback for preg_replace_callback() within drupal_html_to_text(). */ function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) { global $base_url, $base_path; @@ -590,18 +592,18 @@ function _drupal_html_to_mail_urls($match = NULL, $reset = FALSE) { } /** - * Helper function for drupal_wrap_mail() and drupal_html_to_text(). + * Replaces non-quotation markers from a given piece of indentation with spaces. * - * Replace all non-quotation markers from a given piece of indentation with spaces. + * Callback for array_map() within drupal_html_to_text(). */ function _drupal_html_to_text_clean($indent) { return preg_replace('/[^>]/', ' ', $indent); } /** - * Helper function for drupal_html_to_text(). + * Pads the last line with the given character. * - * Pad the last line with the given character. + * @see drupal_html_to_text() */ function _drupal_html_to_text_pad($text, $pad, $prefix = '') { // Remove last line break. diff --git a/includes/menu.inc b/includes/menu.inc index b25a374ac..0cb9d23b8 100644 --- a/includes/menu.inc +++ b/includes/menu.inc @@ -417,9 +417,9 @@ function menu_unserialize($data, $map) { * @param $path * The path. * @param $router_item - * The router item. Usually you take a router entry from menu_get_item and - * set it back either modified or to a different path. This lets you modify the - * navigation block, the page title, the breadcrumb and the page help in one + * The router item. Usually a router entry from menu_get_item() is either + * modified or set to a different path. This allows the navigation block, + * the page title, the breadcrumb, and the page help to be modified in one * call. */ function menu_set_item($path, $router_item) { @@ -427,7 +427,7 @@ function menu_set_item($path, $router_item) { } /** - * Get a router item. + * Gets a router item. * * @param $path * The path, for example node/5. The function will find the corresponding @@ -436,12 +436,13 @@ function menu_set_item($path, $router_item) { * Internal use only. * * @return - * The router item, an associate array corresponding to one row in the - * menu_router table. The value of key map holds the loaded objects. The - * value of key access is TRUE if the current user can access this page. - * The values for key title, page_arguments, access_arguments, and - * theme_arguments will be filled in based on the database values and the - * objects loaded. + * The router item or, if an error occurs in _menu_translate(), FALSE. A + * router item is an associative array corresponding to one row in the + * menu_router table. The value corresponding to the key 'map' holds the + * loaded objects. The value corresponding to the key 'access' is TRUE if the + * current user can access this page. The values corresponding to the keys + * 'title', 'page_arguments', 'access_arguments', and 'theme_arguments' will + * be filled in based on the database values and the objects loaded. */ function menu_get_item($path = NULL, $router_item = NULL) { $router_items = &drupal_static(__FUNCTION__); @@ -606,7 +607,7 @@ function _menu_load_objects(&$item, &$map) { } /** - * Check access to a menu item using the access callback + * Checks access to a menu item using the access callback. * * @param $item * A menu router or menu link item @@ -638,7 +639,7 @@ function _menu_check_access(&$item, $map) { } /** - * Localize the router item title using t() or another callback. + * Localizes the router item title using t() or another callback. * * Translate the title and description to allow storage of English title * strings in the database, yet display of them in the language required @@ -746,7 +747,7 @@ function _menu_item_localize(&$item, $map, $link_translate = FALSE) { * $item['load_functions']. $item['access'] becomes TRUE if the item is * accessible, FALSE otherwise. $item['href'] is set according to the map. * If an error occurs during calling the load_functions (like trying to load - * a non existing node) then this function return FALSE. + * a non-existent node) then this function returns FALSE. */ function _menu_translate(&$router_item, $map, $to_arg = FALSE) { if ($to_arg && !empty($router_item['to_arg_functions'])) { @@ -796,14 +797,14 @@ function _menu_translate(&$router_item, $map, $to_arg = FALSE) { } /** - * This function translates the path elements in the map using any to_arg - * helper function. These functions take an argument and return an object. - * See http://drupal.org/node/109153 for more information. + * Translates the path elements in the map using any to_arg helper function. * * @param $map * An array of path arguments (ex: array('node', '5')) * @param $to_arg_functions * An array of helper function (ex: array(2 => 'menu_tail_to_arg')) + * + * @see hook_menu() */ function _menu_link_map_translate(&$map, $to_arg_functions) { $to_arg_functions = unserialize($to_arg_functions); @@ -820,14 +821,14 @@ function _menu_link_map_translate(&$map, $to_arg_functions) { } /** - * Returns path as one string from the argument we are currently at. + * Returns a string containing the path relative to the current index. */ function menu_tail_to_arg($arg, $map, $index) { return implode('/', array_slice($map, $index)); } /** - * Loads path as one string from the argument we are currently at. + * Loads the path as one string relative to the current index. * * To use this load function, you must specify the load arguments * in the router item as: @@ -844,8 +845,10 @@ function menu_tail_load($arg, &$map, $index) { } /** - * This function is similar to _menu_translate() but does link-specific - * preparation such as always calling to_arg functions + * Provides menu link access control, translation, and argument handling. + * + * This function is similar to _menu_translate(), but it also does + * link-specific preparation (such as always calling to_arg() functions). * * @param $item * A menu link. @@ -939,7 +942,7 @@ function _menu_link_translate(&$item, $translate = FALSE) { } /** - * Get a loaded object from a router item. + * Gets a loaded object from a router item. * * menu_get_object() provides access to objects loaded by the current router * item. For example, on the page node/%node, the router loads the %node object, @@ -1079,7 +1082,7 @@ function menu_tree_output($tree) { } /** - * Get the data structure representing a named menu tree. + * Gets the data structure representing a named menu tree. * * Since this can be the full tree including hidden items, the data returned * may be used for generating an an admin interface or a select. @@ -1147,7 +1150,7 @@ function menu_tree_all_data($menu_name, $link = NULL, $max_depth = NULL) { } /** - * Set the path for determining the active trail of the specified menu tree. + * Sets the path for determining the active trail of the specified menu tree. * * This path will also affect the breadcrumbs under some circumstances. * Breadcrumbs are built using the preferred link returned by @@ -1172,7 +1175,7 @@ function menu_tree_set_path($menu_name, $path = NULL) { } /** - * Get the path for determining the active trail of the specified menu tree. + * Gets the path for determining the active trail of the specified menu tree. * * @param $menu_name * The menu name of the requested tree. @@ -1186,7 +1189,7 @@ function menu_tree_get_path($menu_name) { } /** - * Get the data structure representing a named menu tree, based on the current page. + * Gets the data structure for a named menu tree, based on the current page. * * The tree order is maintained by storing each parent in an individual * field, see http://drupal.org/node/141866 for more. @@ -1320,7 +1323,7 @@ function menu_tree_page_data($menu_name, $max_depth = NULL, $only_active_trail = } /** - * Build a menu tree, translate links, and check access. + * Builds a menu tree, translates links, and checks access. * * @param $menu_name * The name of the menu. @@ -1335,8 +1338,8 @@ function menu_tree_page_data($menu_name, $max_depth = NULL, $only_active_trail = * trail. This option is ignored, if 'expanded' is non-empty. Internally * used for breadcrumbs. * - min_depth: The minimum depth of menu links in the resulting tree. - * Defaults to 1, which is the default to build a whole tree for a menu, i.e. - * excluding menu container itself. + * Defaults to 1, which is the default to build a whole tree for a menu + * (excluding menu container itself). * - max_depth: The maximum depth of menu links in the resulting tree. * - conditions: An associative array of custom database select query * condition key/value pairs; see _menu_build_tree() for the actual query. @@ -1353,7 +1356,7 @@ function menu_build_tree($menu_name, array $parameters = array()) { } /** - * Build a menu tree. + * Builds a menu tree. * * This function may be used build the data for a menu tree only, for example * to further massage the data manually before further processing happens. @@ -1449,7 +1452,7 @@ function _menu_build_tree($menu_name, array $parameters = array()) { } /** - * Recursive helper function - collect node links. + * Collects node links from a given menu tree recursively. * * @param $tree * The menu tree you wish to collect node links from. @@ -1472,7 +1475,7 @@ function menu_tree_collect_node_links(&$tree, &$node_links) { } /** - * Check access and perform other dynamic operations for each link in the tree. + * Checks access and performs dynamic operations for each link in the tree. * * @param $tree * The menu tree you wish to operate on. @@ -1499,7 +1502,7 @@ function menu_tree_check_access(&$tree, $node_links = array()) { } /** - * Recursive helper function for menu_tree_check_access() + * Sorts the menu tree and recursively checks access for each item. */ function _menu_tree_check_access(&$tree) { $new_tree = array(); @@ -1522,7 +1525,7 @@ function _menu_tree_check_access(&$tree) { } /** - * Builds the data representing a menu tree. + * Sorts and returns the built data representing a menu tree. * * @param $links * A flat array of menu links that are part of the menu. Each array element @@ -1554,7 +1557,7 @@ function menu_tree_data(array $links, array $parents = array(), $depth = 1) { } /** - * Recursive helper function to build the data representing a menu tree. + * Builds the data representing a menu tree. * * The function is a bit complex because the rendering of a link depends on * the next menu link. @@ -1589,7 +1592,7 @@ function _menu_tree_data(&$links, $parents, $depth) { } /** - * Preprocesses the rendered tree for theme_menu_tree(). + * Implements template_preprocess_HOOK() for theme_menu_tree(). */ function template_preprocess_menu_tree(&$variables) { $variables['tree'] = $variables['tree']['#children']; @@ -1783,7 +1786,7 @@ function menu_get_names() { } /** - * Return an array containing the names of system-defined (default) menus. + * Returns an array containing the names of system-defined (default) menus. */ function menu_list_system_menus() { return array( @@ -1795,14 +1798,14 @@ function menu_list_system_menus() { } /** - * Return an array of links to be rendered as the Main menu. + * Returns an array of links to be rendered as the Main menu. */ function menu_main_menu() { return menu_navigation_links(variable_get('menu_main_links_source', 'main-menu')); } /** - * Return an array of links to be rendered as the Secondary links. + * Returns an array of links to be rendered as the Secondary links. */ function menu_secondary_menu() { @@ -1817,7 +1820,7 @@ function menu_secondary_menu() { } /** - * Return an array of links for a navigation menu. + * Returns an array of links for a navigation menu. * * @param $menu_name * The name of the menu. @@ -2109,14 +2112,12 @@ function menu_local_tasks($level = 0) { } /** - * Retrieve contextual links for a system object based on registered local tasks. + * Retrieves contextual links for a path based on registered local tasks. * * This leverages the menu system to retrieve the first layer of registered * local tasks for a given system path. All local tasks of the tab type * MENU_CONTEXT_INLINE are taken into account. * - * @see hook_menu() - * * For example, when considering the following registered local tasks: * - node/%node/view (default local task) with no 'context' defined * - node/%node/edit with context: MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE @@ -2144,6 +2145,7 @@ function menu_local_tasks($level = 0) { * A list of menu router items that are local tasks for the passed-in path. * * @see contextual_links_preprocess() + * @see hook_menu() */ function menu_contextual_links($module, $parent_path, $args) { static $path_empty = array(); @@ -2237,7 +2239,7 @@ function menu_local_actions() { } /** - * Returns the router path, or the path of the parent tab of a default local task. + * Returns the router path, or the path for a default local task's parent. */ function menu_tab_root_path() { $links = menu_local_tasks(); @@ -2258,7 +2260,13 @@ function menu_local_tabs() { /** * Returns HTML for primary and secondary local tasks. * + * @param $variables + * An associative array containing: + * - primary: (optional) An array of local tasks (tabs). + * - secondary: (optional) An array of local tasks (tabs). + * * @ingroup themeable + * @see menu_local_tasks() */ function theme_menu_local_tasks(&$variables) { $output = ''; @@ -2280,7 +2288,9 @@ function theme_menu_local_tasks(&$variables) { } /** - * Set (or get) the active menu for the current page - determines the active trail. + * Sets (or gets) the active menu for the current page. + * + * The active menu for the page determines the active trail. * * @return * An array of menu machine names, in order of preference. The @@ -2302,17 +2312,17 @@ function menu_set_active_menu_names($menu_names = NULL) { } /** - * Get the active menu for the current page - determines the active trail. + * Gets the active menu for the current page. */ function menu_get_active_menu_names() { return menu_set_active_menu_names(); } /** - * Set the active path, which determines which page is loaded. + * Sets the active path, which determines which page is loaded. * * Note that this may not have the desired effect unless invoked very early - * in the page load, such as during hook_boot, or unless you call + * in the page load, such as during hook_boot(), or unless you call * menu_execute_active_handler() to generate your page output. * * @param $path @@ -2326,7 +2336,7 @@ function menu_set_active_item($path) { } /** - * Sets the active trail (path to menu tree root) of the current page. + * Sets the active trail (path to the menu tree root) of the current page. * * Any trail set by this function will only be used for functionality that calls * menu_get_active_trail(). Drupal core only uses trails set here for @@ -2416,7 +2426,7 @@ function menu_set_active_trail($new_trail = NULL) { } /** - * Lookup the preferred menu link for a given system path. + * Looks up the preferred menu link for a given system path. * * @param $path * The path, for example 'node/5'. The function will find the corresponding @@ -2536,7 +2546,7 @@ function menu_get_active_trail() { } /** - * Get the breadcrumb for the current page, as determined by the active trail. + * Gets the breadcrumb for the current page, as determined by the active trail. * * @see menu_set_active_trail() */ @@ -2587,7 +2597,7 @@ function menu_get_active_breadcrumb() { } /** - * Get the title of the current page, as determined by the active trail. + * Gets the title of the current page, as determined by the active trail. */ function menu_get_active_title() { $active_trail = menu_get_active_trail(); @@ -2600,7 +2610,7 @@ function menu_get_active_title() { } /** - * Get a menu link by its mlid, access checked and link translated for rendering. + * Gets a translated, access-checked menu link that is ready for rendering. * * This function should never be called from within node_load() or any other * function used as a menu object load function since an infinite recursion may @@ -2651,7 +2661,9 @@ function menu_cache_clear($menu_name = 'navigation') { } /** - * Clears all cached menu data. This should be called any time broad changes + * Clears all cached menu data. + * + * This should be called any time broad changes * might have been made to the router items or menu links. */ function menu_cache_clear_all() { @@ -2672,10 +2684,10 @@ function menu_reset_static_cache() { } /** - * (Re)populate the database tables used by various menu functions. + * Populates the database tables used by various menu functions. * * This function will clear and populate the {menu_router} table, add entries - * to {menu_links} for new router items, then remove stale items from + * to {menu_links} for new router items, and then remove stale items from * {menu_links}. If called from update.php or install.php, it will also * schedule a call to itself on the first real page load from * menu_execute_active_handler(), because the maintenance page environment @@ -2721,7 +2733,7 @@ function menu_rebuild() { } /** - * Collect and alter the menu definitions. + * Collects and alters the menu definitions. */ function menu_router_build() { // We need to manually call each module so that we can know which module @@ -2745,7 +2757,7 @@ function menu_router_build() { } /** - * Helper function to store the menu router if we have it in memory. + * Stores the menu router if we have it in memory. */ function _menu_router_cache($new_menu = NULL) { $menu = &drupal_static(__FUNCTION__); @@ -2757,7 +2769,7 @@ function _menu_router_cache($new_menu = NULL) { } /** - * Get the menu router. + * Gets the menu router. */ function menu_get_router() { // Check first if we have it in memory already. @@ -2794,7 +2806,7 @@ function _menu_link_build($item) { } /** - * Helper function to build menu links for the items in the menu router. + * Builds menu links for the items in the menu router. */ function _menu_navigation_links_rebuild($menu) { // Add normal and suggested items as links. @@ -2894,7 +2906,7 @@ function _menu_navigation_links_rebuild($menu) { } /** - * Clone an array of menu links. + * Clones an array of menu links. * * @param $links * An array of menu links to clone. @@ -2985,12 +2997,14 @@ function menu_link_delete($mlid, $path = NULL) { } /** - * Helper function for menu_link_delete; deletes a single menu link. + * Deletes a single menu link. * * @param $item * Item to be deleted. * @param $force * Forces deletion. Internal use only, setting to TRUE is discouraged. + * + * @see menu_link_delete() */ function _menu_delete_item($item, $force = FALSE) { $item = is_object($item) ? get_object_vars($item) : $item; @@ -3202,7 +3216,7 @@ function menu_link_save(&$item, $existing_item = array(), $parent_candidates = a } /** - * Find a possible parent for a given menu link. + * Finds a possible parent for a given menu link. * * Because the parent of a given link might not exist anymore in the database, * we apply a set of heuristics to determine a proper parent: @@ -3216,6 +3230,7 @@ function menu_link_save(&$item, $existing_item = array(), $parent_candidates = a * A menu link. * @param $parent_candidates * An array of menu links keyed by mlid. + * * @return * A menu link structure of the possible parent or FALSE if no valid parent * has been found. @@ -3281,7 +3296,7 @@ function _menu_link_find_parent($menu_link, $parent_candidates = array()) { } /** - * Helper function to clear the page and block caches at most twice per page load. + * Clears the page and block caches at most twice per page load. */ function _menu_clear_page_cache() { $cache_cleared = &drupal_static(__FUNCTION__, 0); @@ -3303,7 +3318,7 @@ function _menu_clear_page_cache() { } /** - * Helper function to update a list of menus with expanded items + * Updates a list of menus with expanded items. */ function _menu_set_expanded_menus() { $names = db_query("SELECT menu_name FROM {menu_links} WHERE expanded <> 0 GROUP BY menu_name")->fetchCol(); @@ -3311,7 +3326,7 @@ function _menu_set_expanded_menus() { } /** - * Find the router path which will serve this path. + * Finds the router path which will serve this path. * * @param $link_path * The path for we are looking up its router path. @@ -3353,7 +3368,7 @@ function _menu_find_router_path($link_path) { } /** - * Insert, update or delete an uncustomized menu link related to a module. + * Inserts, updates, or deletes an uncustomized menu link related to a module. * * @param $module * The name of the module. @@ -3393,7 +3408,7 @@ function menu_link_maintain($module, $op, $link_path, $link_title) { } /** - * Find the depth of an item's children relative to its depth. + * Finds the depth of an item's children relative to its depth. * * For example, if the item has a depth of 2, and the maximum of any child in * the menu link tree is 5, the relative depth is 3. @@ -3425,7 +3440,7 @@ function menu_link_children_relative_depth($item) { } /** - * Update the children of a menu link that's being moved. + * Updates the children of a menu link that is being moved. * * The menu name, parents (p1 - p6), and depth are updated for all children of * the link, and the has_children status of the previous parent is updated. @@ -3474,7 +3489,7 @@ function _menu_link_move_children($item, $existing_item) { } /** - * Check and update the has_children status for the parent of a link. + * Checks and updates the 'has_children' status for the parent of a link. */ function _menu_update_parental_status($item, $exclude = FALSE) { // If plid == 0, there is nothing to update. @@ -3498,7 +3513,7 @@ function _menu_update_parental_status($item, $exclude = FALSE) { } /** - * Helper function that sets the p1..p9 values for a menu link being saved. + * Sets the p1 through p9 values for a menu link being saved. */ function _menu_link_parents_set(&$item, $parent) { $i = 1; @@ -3516,7 +3531,7 @@ function _menu_link_parents_set(&$item, $parent) { } /** - * Helper function to build the router table based on the data from hook_menu. + * Builds the router table based on the data from hook_menu(). */ function _menu_router_build($callbacks) { // First pass: separate callbacks from paths, making paths ready for @@ -3743,7 +3758,7 @@ function _menu_router_build($callbacks) { } /** - * Helper function to save data from menu_router_build() to the router table. + * Saves data from menu_router_build() to the router table. */ function _menu_router_save($menu, $masks) { // Delete the existing router since we have some data to replace it. diff --git a/includes/module.inc b/includes/module.inc index 28bca2350..d932f07b9 100644 --- a/includes/module.inc +++ b/includes/module.inc @@ -6,7 +6,7 @@ */ /** - * Load all the modules that have been enabled in the system table. + * Loads all the modules that have been enabled in the system table. * * @param $bootstrap * Whether to load only the reduced set of modules loaded in "bootstrap mode" @@ -102,7 +102,7 @@ function module_list($refresh = FALSE, $bootstrap_refresh = FALSE, $sort = FALSE } /** - * Build a list of bootstrap modules and enabled modules and themes. + * Builds a list of bootstrap modules and enabled modules and themes. * * @param $type * The type of list to return: @@ -181,6 +181,7 @@ function system_list($type) { foreach ($lists['theme'] as $key => $theme) { if (!empty($theme->info['base theme'])) { // Make a list of the theme's base themes. + require_once DRUPAL_ROOT . '/includes/theme.inc'; $lists['theme'][$key]->base_themes = drupal_find_base_themes($lists['theme'], $key); // Don't proceed if there was a problem with the root base theme. if (!current($lists['theme'][$key]->base_themes)) { @@ -218,7 +219,7 @@ function system_list($type) { } /** - * Reset all system_list() caches. + * Resets all system_list() caches. */ function system_list_reset() { drupal_static_reset('system_list'); @@ -229,7 +230,7 @@ function system_list_reset() { } /** - * Find dependencies any level deep and fill in required by information too. + * Determines which modules require and are required by each module. * * @param $files * The array of filesystem objects used to rebuild the cache. @@ -262,7 +263,7 @@ function _module_build_dependencies($files) { } /** - * Determine whether a given module exists. + * Determines whether a given module exists. * * @param $module * The name of the module (without the .module extension). @@ -276,7 +277,7 @@ function module_exists($module) { } /** - * Load a module's installation hooks. + * Loads a module's installation hooks. * * @param $module * The name of the module (without the .module extension). @@ -292,7 +293,7 @@ function module_load_install($module) { } /** - * Load a module include file. + * Loads a module include file. * * Examples: * @code @@ -334,8 +335,7 @@ function module_load_include($type, $module, $name = NULL) { } /** - * Load an include file for each of the modules that have been enabled in - * the system table. + * Loads an include file for each module enabled in the {system} table. */ function module_load_all_includes($type, $name = NULL) { $modules = module_list(); @@ -503,7 +503,7 @@ function module_enable($module_list, $enable_dependencies = TRUE) { } /** - * Disable a given set of modules. + * Disables a given set of modules. * * @param $module_list * An array of module names. @@ -614,7 +614,7 @@ function module_disable($module_list, $disable_dependents = TRUE) { */ /** - * Determine whether a module implements a hook. + * Determines whether a module implements a hook. * * @param $module * The name of the module (without the .module extension). @@ -643,7 +643,7 @@ function module_hook($module, $hook) { } /** - * Determine which modules are implementing a hook. + * Determines which modules are implementing a hook. * * @param $hook * The name of the hook (e.g. "help" or "menu"). @@ -744,7 +744,14 @@ function module_implements($hook, $sort = FALSE, $reset = FALSE) { } /** - * Retrieve a list of what hooks are explicitly declared. + * Retrieves a list of hooks that are declared through hook_hook_info(). + * + * @return + * An associative array whose keys are hook names and whose values are an + * associative array containing a group name. The structure of the array + * is the same as the return value of hook_hook_info(). + * + * @see hook_hook_info() */ function module_hook_info() { // This function is indirectly invoked from bootstrap_invoke_all(), in which @@ -806,7 +813,7 @@ function module_implements_write_cache() { } /** - * Invoke a hook in a particular module. + * Invokes a hook in a particular module. * * @param $module * The name of the module (without the .module extension). @@ -828,7 +835,7 @@ function module_invoke($module, $hook) { } /** - * Invoke a hook in all enabled modules that implement it. + * Invokes a hook in all enabled modules that implement it. * * @param $hook * The name of the hook to invoke. @@ -865,13 +872,13 @@ function module_invoke_all($hook) { */ /** - * Array of modules required by core. + * Returns an array of modules required by core. */ function drupal_required_modules() { $files = drupal_system_listing('/^' . DRUPAL_PHP_FUNCTION_PATTERN . '\.info$/', 'modules', 'name', 0); $required = array(); - // An install profile is required and one must always be loaded. + // An installation profile is required and one must always be loaded. $required[] = drupal_get_profile(); foreach ($files as $name => $file) { @@ -885,7 +892,7 @@ function drupal_required_modules() { } /** - * Hands off alterable variables to type-specific *_alter implementations. + * Passes alterable variables to specific hook_TYPE_alter() implementations. * * This dispatch function hands off the passed-in variables to type-specific * hook_TYPE_alter() implementations in modules. It ensures a consistent diff --git a/includes/session.inc b/includes/session.inc index 8f1bcafc4..b04c18eb3 100644 --- a/includes/session.inc +++ b/includes/session.inc @@ -349,6 +349,11 @@ function drupal_session_started($set = NULL) { */ function drupal_session_regenerate() { global $user, $is_https; + // Nothing to do if we are not allowed to change the session. + if (!drupal_save_session()) { + return; + } + if ($is_https && variable_get('https', FALSE)) { $insecure_session_name = substr(session_name(), 1); if (!isset($GLOBALS['lazy_session']) && isset($_COOKIE[$insecure_session_name])) { @@ -418,6 +423,11 @@ function drupal_session_regenerate() { function _drupal_session_destroy($sid) { global $user, $is_https; + // Nothing to do if we are not allowed to change the session. + if (!drupal_save_session()) { + return; + } + // Delete session data. db_delete('sessions') ->condition($is_https ? 'ssid' : 'sid', $sid) @@ -465,6 +475,11 @@ function _drupal_session_delete_cookie($name, $secure = NULL) { * User ID. */ function drupal_session_destroy_uid($uid) { + // Nothing to do if we are not allowed to change the session. + if (!drupal_save_session()) { + return; + } + db_delete('sessions') ->condition('uid', $uid) ->execute(); @@ -507,7 +522,10 @@ function _drupal_session_garbage_collection($lifetime) { * FALSE if writing session data has been disabled. Otherwise, TRUE. */ function drupal_save_session($status = NULL) { - $save_session = &drupal_static(__FUNCTION__, TRUE); + // PHP session ID, session, and cookie handling happens in the global scope. + // This value has to persist across calls to drupal_static_reset(), since a + // potentially wrong or disallowed session would be written otherwise. + static $save_session = TRUE; if (isset($status)) { $save_session = $status; } diff --git a/includes/stream_wrappers.inc b/includes/stream_wrappers.inc index 2af8c9e91..fa401c6b7 100644 --- a/includes/stream_wrappers.inc +++ b/includes/stream_wrappers.inc @@ -553,7 +553,7 @@ abstract class DrupalLocalStreamWrapper implements DrupalStreamWrapperInterface * Support for unlink(). * * @param $uri - * A string containing the uri to the resource to delete. + * A string containing the URI to the resource to delete. * * @return * TRUE if resource was successfully deleted. @@ -569,9 +569,9 @@ abstract class DrupalLocalStreamWrapper implements DrupalStreamWrapperInterface * Support for rename(). * * @param $from_uri, - * The uri to the file to rename. + * The URI to the file to rename. * @param $to_uri - * The new uri for file. + * The new URI for file. * * @return * TRUE if file was successfully renamed. diff --git a/includes/theme.inc b/includes/theme.inc index c4b712271..1f8dfcf9e 100644 --- a/includes/theme.inc +++ b/includes/theme.inc @@ -2112,7 +2112,7 @@ function theme_item_list($variables) { * * @param $variables * An associative array containing: - * - url: The url for the link. + * - url: The URL for the link. */ function theme_more_help_link($variables) { return '<div class="more-help-link">' . l(t('More help'), $variables['url']) . '</div>'; @@ -2128,7 +2128,7 @@ function theme_more_help_link($variables) { * - title: A descriptive title of the feed. */ function theme_feed_icon($variables) { - $text = t('Subscribe to @feed-title', array('@feed-title' => $variables['title'])); + $text = t('Subscribe to !feed-title', array('!feed-title' => $variables['title'])); if ($image = theme('image', array('path' => 'misc/feed.png', 'width' => 16, 'height' => 16, 'alt' => $text))) { return l($image, $variables['url'], array('html' => TRUE, 'attributes' => array('class' => array('feed-icon'), 'title' => $text))); } @@ -2177,7 +2177,7 @@ function theme_html_tag($variables) { * * @param $variables * An associative array containing: - * - url: The url of the main page. + * - url: The URL of the main page. * - title: A descriptive verb for the link, like 'Read more'. */ function theme_more_link($variables) { diff --git a/includes/unicode.inc b/includes/unicode.inc index cd9cd9bf0..81a0a4dfe 100644 --- a/includes/unicode.inc +++ b/includes/unicode.inc @@ -96,7 +96,7 @@ function unicode_check() { * Whether to report any fatal errors with form_set_error(). */ function _unicode_check() { - // Ensure translations don't break at install time + // Ensure translations don't break during installation. $t = get_t(); // Check for mbstring extension @@ -128,7 +128,7 @@ function _unicode_check() { * Return Unicode library status and errors. */ function unicode_requirements() { - // Ensure translations don't break at install time + // Ensure translations don't break during installation. $t = get_t(); $libraries = array( diff --git a/includes/update.inc b/includes/update.inc index f7c7b6668..5f1c2331c 100644 --- a/includes/update.inc +++ b/includes/update.inc @@ -785,12 +785,12 @@ function update_fix_d7_requirements() { /** * Register the currently installed profile in the system table. * - * Install profiles are now treated as modules by Drupal, and have an upgrade - * path based on their schema version in the system table. + * Installation profiles are now treated as modules by Drupal, and have an + * upgrade path based on their schema version in the system table. * - * The install profile will be set to schema_version 0, as it has already been - * installed. Any other hook_update_N functions provided by the install profile - * will be run by update.php. + * The installation profile will be set to schema_version 0, as it has already + * been installed. Any other hook_update_N functions provided by the + * installation profile will be run by update.php. */ function update_fix_d7_install_profile() { $profile = drupal_get_profile(); @@ -828,10 +828,10 @@ function update_fix_d7_install_profile() { 'owner' => '', ); - // Install profile hooks are always executed last by the module system + // Installation profile hooks are always executed last by the module system $values['weight'] = 1000; - // Initializing the system table entry for the install profile + // Initializing the system table entry for the installation profile db_insert('system') ->fields(array_keys($values)) ->values($values) @@ -840,7 +840,8 @@ function update_fix_d7_install_profile() { // Reset the cached schema version. drupal_get_installed_schema_version($profile, TRUE); - // Load the updates again to make sure the install profile updates are loaded + // Load the updates again to make sure the installation profile updates + // are loaded. drupal_load_updates(); } } @@ -895,7 +896,7 @@ function update_get_d6_session_name() { } else { // Otherwise use $base_url as session name, without the protocol - // to use the same session identifiers across http and https. + // to use the same session identifiers across HTTP and HTTPS. list( , $session_name) = explode('://', $base_url, 2); } @@ -1474,17 +1475,3 @@ function update_retrieve_dependencies() { return $return; } - -/** - * @defgroup update-api-6.x-to-7.x Update versions of API functions - * @{ - * Functions similar to normal API function but not firing hooks. - * - * During update, it is impossible to judge the consequences of firing a hook - * as it might hit a module not yet updated. So simplified versions of some - * core APIs are provided. - */ - -/** - * @} End of "defgroup update-api-6.x-to-7.x". - */ |