From 45b8138b9757972d1f71e782aa126c324e601b3e Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Thu, 24 Sep 2015 18:51:13 +0000 Subject: [PATCH] Docs: Improve the summary and description for the `pre_http_request` filter docs to better illustrate expected values. The filter explicitly expects one of three passed value types: * An array containing 'headers', 'body', 'response', 'cookies', and 'filename' elements * A `WP_Error` instance * Boolean false (to avoid short-circuiting the response) Props johnbillion. Fixes #33995. git-svn-id: https://develop.svn.wordpress.org/trunk@34509 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/class-http.php | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/src/wp-includes/class-http.php b/src/wp-includes/class-http.php index 886020ae26..ac6e27a914 100644 --- a/src/wp-includes/class-http.php +++ b/src/wp-includes/class-http.php @@ -159,18 +159,25 @@ class WP_Http { $r['_redirection'] = $r['redirection']; /** - * Filter whether to preempt an HTTP request's return. + * Filter whether to preempt an HTTP request's return value. * - * Returning a truthy value to the filter will short-circuit - * the HTTP request and return early with that value. + * Returning a non-false value from the filter will short-circuit the HTTP request and return + * early with that value. A filter should return either: + * + * - An array containing 'headers', 'body', 'response', 'cookies', and 'filename' elements + * - A WP_Error instance + * - boolean false (to avoid short-circuiting the response) + * + * Returning any other value may result in unexpected behaviour. * * @since 2.9.0 * - * @param bool $preempt Whether to preempt an HTTP request return. Default false. - * @param array $r HTTP request arguments. - * @param string $url The request URL. + * @param false|array|WP_Error $preempt Whether to preempt an HTTP request's return value. Default false. + * @param array $r HTTP request arguments. + * @param string $url The request URL. */ $pre = apply_filters( 'pre_http_request', false, $r, $url ); + if ( false !== $pre ) return $pre;