Changeset 25747 for trunk/src/wp-admin/admin.php

Timestamp:

10/09/2013 09:00:41 PM (11 years ago)

Author:

nacin

Message:

Hook documentation for wp-admin/admin.php.

props DrewAPicture for initial patch.
fixes #25442.

File:

• trunk/src/wp-admin/admin.php (modified) (9 diffs)

trunk/src/wp-admin/admin.php

@@ -37 +37 @@
 
     /**
-     * Runs on the next page load after successful upgrade
-     *
-     * @since 2.8
-     */
-    do_action('after_db_upgrade');
+     * Fires on the next page load after a successful DB upgrade.
+     *
+     * @since 2.8.0
+     */
+    do_action( 'after_db_upgrade' );
 } elseif ( get_option('db_version') != $wp_db_version && empty($_POST) ) {
     if ( !is_multisite() ) {
         wp_redirect( admin_url( 'upgrade.php?_wp_http_referer=' . urlencode( wp_unslash( $_SERVER['REQUEST_URI'] ) ) ) );
         exit;
+
+    /**
+     * Filter whether to attempt to perform the multisite DB upgrade routine.
+     *
+     * In single site, the user would be redirected to wp-admin/upgrade.php.
+     * In multisite, it is automatically fired, but only when this filter
+     * returns true.
+     *
+     * If the network is 50 sites or less, it will run every time. Otherwise,
+     * it will throttle itself to reduce load.
+     *
+     * @since 3.0.0
+     *
+     * @param bool true Whether to perform the Multisite upgrade routine. Default true.
+     */
     } elseif ( apply_filters( 'do_mu_upgrade', true ) ) {
-        /**
-         * On really small MU installs run the upgrader every time,
-         * else run it less often to reduce load.
-         *
-         * @since 2.8.4b
-         */
         $c = get_blog_count();
         // If 50 or fewer sites, run every time. Else, run "about ten percent" of the time. Shh, don't check that math.
@@ -58 +67 @@
             require_once( ABSPATH . WPINC . '/http.php' );
             $response = wp_remote_get( admin_url( 'upgrade.php?step=1' ), array( 'timeout' => 120, 'httpversion' => '1.1' ) );
+            /**
+             * Fires after the multisite DB upgrade is complete.
+             *
+             * @since 3.0.0
+             *
+             * @param array|WP_Error $response The upgrade response array or WP_Error on failure.
+             */
             do_action( 'after_mu_upgrade', $response );
             unset($response);
@@ -104 +120 @@
     require(ABSPATH . 'wp-admin/menu.php');
 
-if ( current_user_can( 'manage_options' ) )
+if ( current_user_can( 'manage_options' ) ) {
+    /**
+     * Filter the maximum memory limit available for administration screens.
+     *
+     * This only applies to administrators, who may require more memory for tasks like updates.
+     * Memory limits when processing images (uploaded or edited by users of any role) are
+     * handled separately.
+     *
+     * The WP_MAX_MEMORY_LIMIT constant specifically defines the maximum memory limit available
+     * when in the administration back-end. The default is 256M, or 256 megabytes of memory.
+     *
+     * @since 3.0.0
+     *
+     * @param string 'WP_MAX_MEMORY_LIMIT' The maximum WordPress memory limit. Default 256M.
+     */
     @ini_set( 'memory_limit', apply_filters( 'admin_memory_limit', WP_MAX_MEMORY_LIMIT ) );
-
-do_action('admin_init');
+}
+
+/**
+ * Fires as an admin screen or script is being initialized.
+ *
+ * Note, this does not just run on user-facing admin screens.
+ * It runs on admin-ajax.php and admin-post.php as well.
+ *
+ * This is roughly analgous to the more general 'init' hook, which fires earlier.
+ *
+ * @since 2.5.0
+ */
+do_action( 'admin_init' );
 
 if ( isset($plugin_page) ) {
@@ -143 +184 @@
 if ( isset($plugin_page) ) {
     if ( $page_hook ) {
-        do_action('load-' . $page_hook);
+        /**
+         * Fires before a particular screen is loaded.
+         *
+         * The load-* hook fires in a number of contexts. This hook is for plugin screens
+         * where a callback is provided when the screen is registered.
+         *
+         * The dynamic portion of the hook name, $page_hook, refers to a mixture of plugin
+         * page information including:
+         * 1. The page type. If the plugin page is registered as a submenu page, such as for
+         *    Settings, the page type would be 'settings'. Otherwise the type is 'toplevel'.
+         * 2. A separator of '_page_'.
+         * 3. The plugin basename minus the file extension.
+         *
+         * Together, the three parts form the $page_hook. Citing the example above,
+         * the hook name used would be 'load-settings_page_pluginbasename'.
+         *
+         * @see get_plugin_page_hook()
+         *
+         * @since 2.1.0
+         */
+        do_action( 'load-' . $page_hook );
         if (! isset($_GET['noheader']))
             require_once(ABSPATH . 'wp-admin/admin-header.php');
 
-        do_action($page_hook);
+        /**
+         * Used to call the registered callback for a plugin screen.
+         *
+         * @access private
+         *
+         * @since 1.5.0
+         */
+        do_action( $page_hook );
     } else {
         if ( validate_file($plugin_page) )
@@ -155 +223 @@
             wp_die(sprintf(__('Cannot load %s.'), htmlentities($plugin_page)));
 
-        do_action('load-' . $plugin_page);
+        /**
+         * Fires before a particular screen is loaded.
+         *
+         * The load-* hook fires in a number of contexts. This hook is for plugin screens
+         * where the file to load is directly included, rather than the use of a function.
+         *
+         * The dynamic portion of the hook name, $plugin_page, refers to the plugin basename.
+         *
+         * @see plugin_basename()
+         *
+         * @since 1.5.0
+         */
+        do_action( 'load-' . $plugin_page );
 
         if ( !isset($_GET['noheader']))
@@ -186 +266 @@
     }
 
+    /**
+     * Fires before an importer screen is loaded.
+     *
+     * The dynamic portion of the hook name, $importer, refers to the importer slug.
+     *
+     * @since 3.5.0
+     */
     do_action( 'load-importer-' . $importer );
 
@@ -199 +286 @@
     define('WP_IMPORTING', true);
 
+    /**
+     * Whether to filter imported data through kses on import.
+     *
+     * Multisite uses this hook to filter all data through kses by default,
+     * as a super administrator may be assisting an untrusted user.
+     *
+     * @since 3.1.0
+     *
+     * @param bool false Whether to force data to be filtered through kses. Default false.
+     */
     if ( apply_filters( 'force_filtered_html_on_import', false ) )
         kses_init_filters();  // Always filter imported data with kses on multisite.
@@ -211 +308 @@
     exit();
 } else {
-    do_action("load-$pagenow");
+    /**
+     * Fires before a particular screen is loaded.
+     *
+     * The load-* hook fires in a number of contexts. This hook is for core screens.
+     *
+     * The dynamic portion of the hook name, $pagenow, is a global variable
+     * referring to the filename of the current page, such as 'admin.php',
+     * 'post-new.php' etc. A complete hook for the latter would be 'load-post-new.php'.
+     *
+     * @since 2.1.0
+     */
+    do_action( 'load-' . $pagenow );
     // Backwards compatibility with old load-page-new.php, load-page.php,
     // and load-categories.php actions.
@@ -227 +335 @@
 }
 
-if ( !empty($_REQUEST['action']) )
-    do_action('admin_action_' . $_REQUEST['action']);
+if ( ! empty( $_REQUEST['action'] ) ) {
+    /**
+     * Fires when an 'action' request variable is sent.
+     *
+     * The dynamic portion of the hook name, $_REQUEST['action'],
+     * refers to the action derived from the GET or POST request.
+     *
+     * @since 2.6.0
+     */
+    do_action( 'admin_action_' . $_REQUEST['action'] );
+}