From 3cee52b3622cd6eab054db09074f220270a09243 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 3 Nov 2020 17:36:09 +0000
Subject: [PATCH] Docs: Add more information about how to use filters that run
 before WordPress initialises.

Fixes #50134

Built from https://develop.svn.wordpress.org/trunk@49489


git-svn-id: http://core.svn.wordpress.org/trunk@49248 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/class-wp-hook.php    | 23 ++++++++++++++++++++++-
 wp-includes/error-protection.php | 21 +++++++++++++++++++++
 wp-includes/version.php          |  2 +-
 3 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/wp-includes/class-wp-hook.php b/wp-includes/class-wp-hook.php
index e2c9cf2368..5f9fa2fb83 100644
--- a/wp-includes/class-wp-hook.php
+++ b/wp-includes/class-wp-hook.php
@@ -356,9 +356,30 @@ final class WP_Hook implements Iterator, ArrayAccess {
 	/**
 	 * Normalizes filters set up before WordPress has initialized to WP_Hook objects.
 	 *
+	 * 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.
+	 * @param array $filters Filters to normalize. See documentation above for details.
 	 * @return WP_Hook[] Array of normalized filters.
 	 */
 	public static function build_preinitialized_hooks( $filters ) {
diff --git a/wp-includes/error-protection.php b/wp-includes/error-protection.php
index c1393045be..379b470171 100644
--- a/wp-includes/error-protection.php
+++ b/wp-includes/error-protection.php
@@ -111,6 +111,27 @@ function wp_is_fatal_error_handler_enabled() {
 	/**
 	 * 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
 	 *
 	 * @param bool $enabled True if the fatal error handler is enabled, false otherwise.
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 3826fba349..3597ff7a1c 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.6-beta3-49488';
+$wp_version = '5.6-beta3-49489';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.