Index: src/wp-includes/load.php =================================================================== --- src/wp-includes/load.php (revision 28655) +++ src/wp-includes/load.php (working copy) @@ -34,8 +34,11 @@ /** * Fix $_SERVER variables for various setups. * + * @since 3.0.0 * @access private - * @since 3.0.0 + * + * @global string $PHP_SELF The filename of the currently executing script, + * relative to the document root. */ function wp_fix_server_vars() { global $PHP_SELF; @@ -92,16 +95,21 @@ } /** - * Check for the required PHP version, and the MySQL extension or a database drop-in. + * Check for the required PHP version, and the MySQL extension or + * a database drop-in. * * Dies if requirements are not met. * + * @since 3.0.0 * @access private - * @since 3.0.0 + * + * @global string $required_php_version The required PHP version string. + * @global string $wp_version The WordPress version string. */ function wp_check_php_mysql_versions() { global $required_php_version, $wp_version; $php_version = phpversion(); + if ( version_compare( $required_php_version, $php_version, '>' ) ) { wp_load_translations_early(); header( 'Content-Type: text/html; charset=utf-8' ); @@ -117,6 +125,7 @@ /** * Don't load all of WordPress when handling a favicon.ico request. + * * Instead, send the headers for a zero-length favicon and bail. * * @since 3.0.0 @@ -130,7 +139,7 @@ } /** - * Dies with a maintenance message when conditions are met. + * Die with a maintenance message when conditions are met. * * Checks for a file in the WordPress root directory named ".maintenance". * This file will contain the variable $upgrading, set to the time the file @@ -140,8 +149,10 @@ * The default message can be replaced by using a drop-in (maintenance.php in * the wp-content directory). * + * @since 3.0.0 * @access private - * @since 3.0.0 + * + * @global int $upgrading the unix timestamp marking when upgrading WordPress began */ function wp_maintenance() { if ( !file_exists( ABSPATH . '.maintenance' ) || defined( 'WP_INSTALLING' ) ) @@ -184,11 +195,14 @@ } /** - * PHP 5 standard microtime start capture. + * Start the WordPress microtimer. * + * @since 0.71 * @access private - * @since 0.71 - * @global float $timestart Seconds from when function is called. + * + * @global float $timestart Unix timestamp set at the beginning of the page load. + * @see timer_stop() + * * @return bool Always returns true. */ function timer_start() { @@ -223,33 +237,34 @@ } /** - * Sets PHP error handling and handles WordPress debug mode. + * Set PHP error reporting based on WordPress debug settings. * - * Uses three constants: WP_DEBUG, WP_DEBUG_DISPLAY, and WP_DEBUG_LOG. All three can be - * defined in wp-config.php. Example: define( 'WP_DEBUG', true ); + * Uses three constants: `WP_DEBUG`, `WP_DEBUG_DISPLAY`, and `WP_DEBUG_LOG`. + * All three can be defined in wp-config.php, and by default are set to false. * - * WP_DEBUG_DISPLAY and WP_DEBUG_LOG perform no function unless WP_DEBUG is true. - * WP_DEBUG defaults to false. + * When `WP_DEBUG` is true, all PHP notices are reported. WordPress will also + * display internal notices: when a deprecated WordPress function, function + * argument, or file is used. Deprecated code may be removed from a later + * version. * - * When WP_DEBUG is true, all PHP notices are reported. WordPress will also display - * notices, including one when a deprecated WordPress function, function argument, - * or file is used. Deprecated code may be removed from a later version. + * It is strongly recommended that plugin and theme developers use `WP_DEBUG` + * in their development environments. * - * It is strongly recommended that plugin and theme developers use WP_DEBUG in their - * development environments. + * `WP_DEBUG_DISPLAY` and `WP_DEBUG_LOG` perform no function unless `WP_DEBUG` + * is true. * - * When WP_DEBUG_DISPLAY is true, WordPress will force errors to be displayed. - * WP_DEBUG_DISPLAY defaults to true. Defining it as null prevents WordPress from - * changing the global configuration setting. Defining WP_DEBUG_DISPLAY as false - * will force errors to be hidden. + * When `WP_DEBUG_DISPLAY` is true, WordPress will force errors to be displayed. + * `WP_DEBUG_DISPLAY` defaults to true. Defining it as null prevents WordPress + * from changing the global configuration setting. Defining `WP_DEBUG_DISPLAY` + * as false will force errors to be hidden. * - * When WP_DEBUG_LOG is true, errors will be logged to wp-content/debug.log. - * WP_DEBUG_LOG defaults to false. + * When `WP_DEBUG_LOG` is true, errors will be logged to debug.log in the content + * directory. * * Errors are never displayed for XML-RPC requests. * + * @since 3.0.0 * @access private - * @since 3.0.0 */ function wp_debug_mode() { if ( WP_DEBUG ) { @@ -272,29 +287,37 @@ } /** - * Sets the location of the language directory. + * Set the location of the language directory. * - * To set directory manually, define WP_LANG_DIR in wp-config.php. + * To set directory manually, define the `WP_LANG_DIR` constant + * in wp-config.php. * - * If the language directory exists within WP_CONTENT_DIR, that is used. - * Otherwise if the language directory exists within WPINC, that's used. - * Finally, if neither of the preceding directories are found, - * WP_CONTENT_DIR/languages is used. + * If the language directory exists within WP_CONTENT_DIR, it + * is used. Otherwise the language directory is assumed to live + * in WPINC. * - * The WP_LANG_DIR constant was introduced in 2.1.0. - * + * @since 3.0.0 * @access private - * @since 3.0.0 */ function wp_set_lang_dir() { if ( !defined( 'WP_LANG_DIR' ) ) { if ( file_exists( WP_CONTENT_DIR . '/languages' ) && @is_dir( WP_CONTENT_DIR . '/languages' ) || !@is_dir(ABSPATH . WPINC . '/languages') ) { + /** + * Server path of the language directory. + * + * @since 2.1.0 + */ define( 'WP_LANG_DIR', WP_CONTENT_DIR . '/languages' ); // no leading slash, no trailing slash, full path, not relative to ABSPATH if ( !defined( 'LANGDIR' ) ) { // Old static relative path maintained for limited backwards compatibility - won't work in some cases define( 'LANGDIR', 'wp-content/languages' ); } } else { + /** + * Server path of the language directory. + * + * @since 2.1.0 + */ define( 'WP_LANG_DIR', ABSPATH . WPINC . '/languages' ); // no leading slash, no trailing slash, full path, not relative to ABSPATH if ( !defined( 'LANGDIR' ) ) { // Old relative path maintained for backwards compatibility @@ -305,14 +328,11 @@ } /** - * Load the correct database class file. + * Load the database class file and instantiate the `$wpdb` global. * - * This function is used to load the database class file either at runtime or by - * wp-admin/setup-config.php. We must globalize $wpdb to ensure that it is - * defined globally by the inline code in wp-db.php. + * @since 2.5.0 * - * @since 2.5.0 - * @global $wpdb WordPress Database Object + * @global wpdb $wpdb The WordPress database class. */ function require_wp_db() { global $wpdb; @@ -328,18 +348,16 @@ } /** - * Sets the database table prefix and the format specifiers for database table columns. + * Set the database table prefix and the format specifiers for database table columns. * * Columns not listed here default to %s. * - * @see wpdb::$field_types Since 2.8.0 - * @see wpdb::prepare() - * @see wpdb::insert() - * @see wpdb::update() - * @see wpdb::set_prefix() + * @since 3.0.0 + * @access private * - * @access private - * @since 3.0.0 + * @see wpdb + * @global mixed $wpdb The WordPress database class + * @global string $table_prefix the database table prefix */ function wp_set_wpdb_vars() { global $wpdb, $table_prefix; @@ -381,13 +399,16 @@ } /** - * Starts the WordPress object cache. + * Start the WordPress object cache. * * If an object-cache.php file exists in the wp-content directory, * it uses that drop-in as an external object cache. * + * @since 3.0.0 * @access private - * @since 3.0.0 + * + * @global bool $_wp_using_ext_object_cache + * @global int $blog_id the blog ID */ function wp_start_object_cache() { global $blog_id; @@ -426,12 +447,12 @@ } /** - * Redirects to the installer if WordPress is not installed. + * Redirect to the installer if WordPress is not installed. * * Dies with an error message when multisite is enabled. * + * @since 3.0.0 * @access private - * @since 3.0.0 */ function wp_not_installed() { if ( is_multisite() ) { @@ -450,15 +471,16 @@ } /** - * Returns array of must-use plugin files to be included in global scope. + * Retrieve an array of must-use plugin files. * - * The default directory is wp-content/mu-plugins. To change the default directory - * manually, define WPMU_PLUGIN_DIR and WPMU_PLUGIN_URL + * The default directory is wp-content/mu-plugins. To change the default + * directory manually, define `WPMU_PLUGIN_DIR` and `WPMU_PLUGIN_URL` * in wp-config.php. * + * @since 3.0.0 * @access private - * @since 3.0.0 - * @return array Files to include + * + * @return array Files to include. */ function wp_get_mu_plugins() { $mu_plugins = array(); @@ -477,15 +499,18 @@ } /** - * Returns array of plugin files to be included in global scope. + * Retrieve an array of active and valid plugin files. * - * The default directory is wp-content/plugins. To change the default directory - * manually, define WP_PLUGIN_DIR and WP_PLUGIN_URL + * While upgrading or installing WordPress, no plugins are returned. + * + * The default directory is wp-content/plugins. To change the default + * directory manually, define `WP_PLUGIN_DIR` and `WP_PLUGIN_URL` * in wp-config.php. * + * @since 3.0.0 * @access private - * @since 3.0.0 - * @return array Files to include + * + * @return array Files. */ function wp_get_active_and_valid_plugins() { $plugins = array(); @@ -515,13 +540,13 @@ } /** - * Sets internal encoding using mb_internal_encoding(). + * Set internal encoding. * - * In most cases the default internal encoding is latin1, which is of no use, - * since we want to use the mb_ functions for utf-8 strings. + * In most cases the default internal encoding is latin1, which is + * of no use, since we want to use the mb_ functions for utf-8 strings. * + * @since 3.0.0 * @access private - * @since 3.0.0 */ function wp_set_internal_encoding() { if ( function_exists( 'mb_internal_encoding' ) ) { @@ -532,13 +557,13 @@ } /** - * Add magic quotes to $_GET, $_POST, $_COOKIE, and $_SERVER. + * Add magic quotes to `$_GET`, `$_POST`, `$_COOKIE`, and `$_SERVER`. * - * Also forces $_REQUEST to be $_GET + $_POST. If $_SERVER, $_COOKIE, - * or $_ENV are needed, use those superglobals directly. + * Also forces `$_REQUEST` to be `$_GET + $_POST`. If `$_SERVER`, + * `$_COOKIE`, or `$_ENV` are needed, use those superglobals directly. * + * @since 3.0.0 * @access private - * @since 3.0.0 */ function wp_magic_quotes() { // If already slashed, strip. @@ -561,8 +586,8 @@ /** * Runs just before PHP shuts down execution. * + * @since 1.2.0 * @access private - * @since 1.2.0 */ function shutdown_action_hook() { /** @@ -571,6 +596,7 @@ * @since 1.2.0 */ do_action( 'shutdown' ); + wp_cache_close(); } @@ -578,26 +604,25 @@ * Copy an object. * * @since 2.7.0 - * @deprecated 3.2 + * @deprecated 3.2.0 * - * @param object $object The object to clone - * @return object The cloned object + * @param object $object The object to clone. + * @return object The cloned object. */ - function wp_clone( $object ) { // Use parens for clone to accommodate PHP 4. See #17880 return clone( $object ); } /** - * Whether the current request is for a network or blog admin page + * Whether the current request is for an administrative interface page. * - * Does not inform on whether the user is an admin! Use capability checks to - * tell if the user should be accessing a section or not. + * Does not check if the user is an administrator; {@see current_user_can()} + * for checking roles and capabilities. * * @since 1.5.1 * - * @return bool True if inside WordPress administration pages. + * @return bool True if inside WordPress administration interface, false otherwise. */ function is_admin() { if ( isset( $GLOBALS['current_screen'] ) ) @@ -609,14 +634,16 @@ } /** - * Whether the current request is for a blog admin screen /wp-admin/ + * Whether the current request is for a site's admininstrative interface. * - * Does not inform on whether the user is a blog admin! Use capability checks to - * tell if the user should be accessing a section or not. + * e.g. /wp-admin/ * + * Does not check if the user is an administrator; {@see current_user_can()} + * for checking roles and capabilities. + * * @since 3.1.0 * - * @return bool True if inside WordPress network administration pages. + * @return bool True if inside WordPress blog administration pages. */ function is_blog_admin() { if ( isset( $GLOBALS['current_screen'] ) ) @@ -628,11 +655,13 @@ } /** - * Whether the current request is for a network admin screen /wp-admin/network/ + * Whether the current request is for the network administrative interface. * - * Does not inform on whether the user is a network admin! Use capability checks to - * tell if the user should be accessing a section or not. + * e.g. /wp-admin/network/ * + * Does not check if the user is an administrator; {@see current_user_can()} + * for checking roles and capabilities. + * * @since 3.1.0 * * @return bool True if inside WordPress network administration pages. @@ -647,11 +676,14 @@ } /** - * Whether the current request is for a user admin screen /wp-admin/user/ + * Whether the current request is for a user admin screen. * - * Does not inform on whether the user is an admin! Use capability checks to - * tell if the user should be accessing a section or not. + * e.g. /wp-admin/user/ * + * Does not inform on whether the user is an admin! Use capability + * checks to tell if the user should be accessing a section or not + * {@see current_user_can()}. + * * @since 3.1.0 * * @return bool True if inside WordPress user administration pages. @@ -666,11 +698,11 @@ } /** - * Whether Multisite support is enabled + * If Multisite is enabled. * * @since 3.0.0 * - * @return bool True if multisite is enabled, false otherwise. + * @return bool True if Multisite is enabled, false otherwise. */ function is_multisite() { if ( defined( 'MULTISITE' ) ) @@ -683,7 +715,7 @@ } /** - * Retrieve the current blog id + * Retrieve the current blog ID. * * @since 3.1.0 * @@ -695,16 +727,19 @@ } /** - * Attempts an early load of translations. + * Attempt an early load of translations. * - * Used for errors encountered during the initial loading process, before the locale has been - * properly detected and loaded. + * Used for errors encountered during the initial loading process, before + * the locale has been properly detected and loaded. * - * Designed for unusual load sequences (like setup-config.php) or for when the script will then - * terminate with an error, otherwise there is a risk that a file can be double-included. + * Designed for unusual load sequences (like setup-config.php) or for when + * the script will then terminate with an error, otherwise there is a risk + * that a file can be double-included. * * @since 3.4.0 * @access private + * + * @global $wp_locale The WordPress date and time locale object. */ function wp_load_translations_early() { global $text_direction, $wp_locale;