HTTP API: Various improvements to the docblocks for HTTP functions.

See #63166


git-svn-id: https://develop.svn.wordpress.org/trunk@60652 602fd350-edb4-49c9-b593-d223f7449a82

Author: johnbillion

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

@@ -264,7 +264,7 @@ public function request( $url, $args = array() ) {
 		 *
 		 *  - An array containing 'headers', 'body', 'response', 'cookies', and 'filename' elements
 		 *  - A WP_Error instance
-		 *  - boolean false to avoid short-circuiting the response
+		 *  - Boolean false to avoid short-circuiting the response
 		 *
 		 * Returning any other value may result in unexpected behavior.
 		 *

src/wp-includes/http.php

@@ -33,6 +33,8 @@ function _wp_http_get_object() {
  * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
  * to avoid Server Side Request Forgery attacks (SSRF).
  *
+ * The only supported protocols are `http` and `https`.
+ *
  * @since 3.6.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -60,6 +62,8 @@ function wp_safe_remote_request( $url, $args = array() ) {
  * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
  * to avoid Server Side Request Forgery attacks (SSRF).
  *
+ * The only supported protocols are `http` and `https`.
+ *
  * @since 3.6.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -87,6 +91,8 @@ function wp_safe_remote_get( $url, $args = array() ) {
  * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
  * to avoid Server Side Request Forgery attacks (SSRF).
  *
+ * The only supported protocols are `http` and `https`.
+ *
  * @since 3.6.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -114,6 +120,8 @@ function wp_safe_remote_post( $url, $args = array() ) {
  * URL. The URL, and every URL it redirects to, are validated with wp_http_validate_url()
  * to avoid Server Side Request Forgery attacks (SSRF).
  *
+ * The only supported protocols are `http` and `https`.
+ *
  * @since 3.6.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -143,6 +151,8 @@ function wp_safe_remote_head( $url, $args = array() ) {
  *  - Default 'POST' for wp_remote_post()
  *  - Default 'HEAD' for wp_remote_head()
  *
+ * Important: If the URL is user-controlled, use `wp_safe_remote_request()` instead.
+ *
  * @since 2.7.0
  *
  * @see WP_Http::request() For information on default arguments.
@@ -161,6 +171,8 @@ function wp_remote_request( $url, $args = array() ) {
 /**
  * Performs an HTTP request using the GET method and returns its response.
  *
+ * Important: If the URL is user-controlled, use `wp_safe_remote_get()` instead.
+ *
  * @since 2.7.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -180,6 +192,8 @@ function wp_remote_get( $url, $args = array() ) {
 /**
  * Performs an HTTP request using the POST method and returns its response.
  *
+ * Important: If the URL is user-controlled, use `wp_safe_remote_post()` instead.
+ *
  * @since 2.7.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -199,6 +213,8 @@ function wp_remote_post( $url, $args = array() ) {
 /**
  * Performs an HTTP request using the HEAD method and returns its response.
  *
+ * Important: If the URL is user-controlled, use `wp_safe_remote_head()` instead.
+ *
  * @since 2.7.0
  *
  * @see wp_remote_request() For more information on the response array format.
@@ -421,7 +437,7 @@ function get_http_origin() {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string $origin The original origin for the request.
+	 * @param string $origin The HTTP origin for the request.
 	 */
 	return apply_filters( 'http_origin', $origin );
 }
@@ -452,14 +468,7 @@ function get_allowed_http_origins() {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param string[] $allowed_origins {
-	 *     Array of default allowed HTTP origins.
-	 *
-	 *     @type string $0 Non-secure URL for admin origin.
-	 *     @type string $1 Secure URL for admin origin.
-	 *     @type string $2 Non-secure URL for home origin.
-	 *     @type string $3 Secure URL for home origin.
-	 * }
+	 * @param string[] $allowed_origins Array of allowed HTTP origins.
 	 */
 	return apply_filters( 'allowed_http_origins', $allowed_origins );
 }
@@ -528,26 +537,28 @@ function send_origin_headers() {
 }
 
 /**
- * Validates a URL for safe use in the HTTP API.
+ * Validates a URL as safe for use in the HTTP API.
+ *
+ * The only supported protocols are `http` and `https`.
  *
  * Examples of URLs that are considered unsafe:
  *
- * - ftp://example.com/caniload.php - Invalid protocol - only http and https are allowed.
- * - http:///example.com/caniload.php - Malformed URL.
- * - http://user:[email protected]/caniload.php - Login information.
- * - http://example.invalid/caniload.php - Invalid hostname, as the IP cannot be looked up in DNS.
+ * - `ftp://example.com/caniload.php` - Invalid protocol - only http and https are allowed.
+ * - `http:///example.com/caniload.php` - Malformed URL.
+ * - `http://user:[email protected]/caniload.php` - Login information.
+ * - `http://example.invalid/caniload.php` - Invalid hostname, as the IP cannot be looked up in DNS.
  *
- * Examples of URLs that are considered unsafe by default:
+ * Examples of URLs that are considered unsafe by default but can be allowed with filters:
  *
- * - http://192.168.0.1/caniload.php - IPs from LAN networks.
+ * - `http://192.168.0.1/caniload.php` - IP address from LAN network.
  *   This can be changed with the {@see 'http_request_host_is_external'} filter.
- * - http://198.143.164.252:81/caniload.php - By default, only 80, 443, and 8080 ports are allowed.
+ * - `http://198.143.164.252:81/caniload.php` - By default, only ports 80, 443, and 8080 are allowed.
  *   This can be changed with the {@see 'http_allowed_safe_ports'} filter.
  *
  * @since 3.5.2
  *
  * @param string $url Request URL.
- * @return string|false URL or false on failure.
+ * @return string|false Returns false if the URL is not safe, or the original URL if it is safe.
  */
 function wp_http_validate_url( $url ) {
 	if ( ! is_string( $url ) || '' === $url || is_numeric( $url ) ) {
@@ -624,7 +635,8 @@ function wp_http_validate_url( $url ) {
 	 *
 	 * @since 5.9.0
 	 *
-	 * @param int[]  $allowed_ports Array of integers for valid ports.
+	 * @param int[]  $allowed_ports Array of integers for valid ports. Default allowed ports
+	 *                              are 80, 443, and 8080.
 	 * @param string $host          Host name of the requested URL.
 	 * @param string $url           Requested URL.
 	 */