Changeset 34509

Timestamp:

09/24/2015 06:51:13 PM (9 years ago)

Author:

DrewAPicture

Message:

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.

File:

• trunk/src/wp-includes/class-http.php (modified) (1 diff)

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

@@ -160 +160 @@
 
         /**
-         * Filter whether to preempt an HTTP request's return.
-         *
-         * Returning a truthy value to the filter will short-circuit
-         * the HTTP request and return early with that value.
+         * Filter whether to preempt an HTTP request's return 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;