Changeset 49489

Timestamp:

11/03/2020 05:34:20 PM (6 years ago)

Author:

johnbillion

Message:

Docs: Add more information about how to use filters that run before WordPress initialises.

Fixes #50134

Location:

trunk/src/wp-includes

Files:

• class-wp-hook.php (modified) (1 diff)
• error-protection.php (modified) (1 diff)

trunk/src/wp-includes/class-wp-hook.php

@@ -357 +357 @@
          * Normalizes filters set up before WordPress has initialized to WP_Hook objects.
          *
-         * @since 4.7.0
-         *
-         * @param array $filters Filters to normalize.
+         * The `$filters` parameter should be an array keyed by hook name, with values
+         * containing either:
+         *
+         *  - A `WP_Hook` instance
+         *  - An array of callbacks keyed by their priorities
+         *
+         * Examples:
+         *
+         *     $filters = array(
+         *         'wp_fatal_error_handler_enabled' => array(
+         *             10 => array(
+         *                 array(
+         *                     'accepted_args' => 0,
+         *                     'function'      => function() {
+         *                         return false;
+         *                     },
+         *                 ),
+         *             ),
+         *         ),
+         *     );
+         *
+         * @since 4.7.0
+         *
+         * @param array $filters Filters to normalize. See documentation above for details.
          * @return WP_Hook[] Array of normalized filters.
          */

trunk/src/wp-includes/error-protection.php

@@ -112 +112 @@
          * Filters whether the fatal error handler is enabled.
          *
+         * **Important:** This filter runs before it can be used by plugins. It cannot
+         * be used by plugins, mu-plugins, or themes. To use this filter you must define
+         * a `$wp_filter` global before WordPress loads, usually in `wp-config.php`.
+         *
+         * Example:
+         *
+         *     $GLOBALS['wp_filter'] = array(
+         *         'wp_fatal_error_handler_enabled' => array(
+         *             10 => array(
+         *                 array(
+         *                     'accepted_args' => 0,
+         *                     'function'      => function() {
+         *                         return false;
+         *                     },
+         *                 ),
+         *             ),
+         *         ),
+         *     );
+         *
+         * Alternatively you can use the `WP_DISABLE_FATAL_ERROR_HANDLER` constant.
+         *
          * @since 5.2.0
          *