External Libraries: Update the Requests library to version 2.0.6.

This is a maintenance release with minor changes:
* Fix typo in deprecation notice.
* Minor internal improvements for passing the correct type to function calls.
* Confirmed compatibility with PHP 8.2. No changes were needed, so Requests 2.0.1 and higher can be considered compatible with PHP 8.2.
* Various documentation improvements and other general housekeeping.

References:
* [https://github.com/WordPress/Requests/releases/tag/v2.0.6 Requests 2.0.6 release notes]
* [WordPress/Requests@v2.0.5...v2.0.6 Full list of changes in Requests 2.0.6]

Follow-up to [54997], [55007], [55046], [55225], [55296].

Props jrf, costdev.
Fixes #58079.

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

Author: SergeyBiryukov

src/wp-includes/Requests/src/Autoload.php

@@ -166,7 +166,7 @@ public static function load($class_name) {
 				if (!defined('REQUESTS_SILENCE_PSR0_DEPRECATIONS') || REQUESTS_SILENCE_PSR0_DEPRECATIONS !== true) {
 					// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_trigger_error
 					trigger_error(
-						'The PSR-0 `Requests_...` class names in the Request library are deprecated.'
+						'The PSR-0 `Requests_...` class names in the Requests library are deprecated.'
 						. ' Switch to the PSR-4 `WpOrg\Requests\...` class names at your earliest convenience.',
 						E_USER_DEPRECATED
 					);

src/wp-includes/Requests/src/Capability.php

@@ -28,7 +28,7 @@ interface Capability {
 	 *
 	 * Note: this does not automatically mean that the capability will be supported for your chosen transport!
 	 *
-	 * @var array<string>
+	 * @var string[]
 	 */
 	const ALL = [
 		self::SSL,

src/wp-includes/Requests/src/Cookie.php

@@ -36,8 +36,8 @@ class Cookie {
 	/**
 	 * Cookie attributes
 	 *
-	 * Valid keys are (currently) path, domain, expires, max-age, secure and
-	 * httponly.
+	 * Valid keys are `'path'`, `'domain'`, `'expires'`, `'max-age'`, `'secure'` and
+	 * `'httponly'`.
 	 *
 	 * @var \WpOrg\Requests\Utility\CaseInsensitiveDictionary|array Array-like object
 	 */
@@ -46,8 +46,7 @@ class Cookie {
 	/**
 	 * Cookie flags
 	 *
-	 * Valid keys are (currently) creation, last-access, persistent and
-	 * host-only.
+	 * Valid keys are `'creation'`, `'last-access'`, `'persistent'` and `'host-only'`.
 	 *
 	 * @var array
 	 */
@@ -66,11 +65,13 @@ class Cookie {
 	/**
 	 * Create a new cookie object
 	 *
-	 * @param string $name
-	 * @param string $value
+	 * @param string                                                  $name           The name of the cookie.
+	 * @param string                                                  $value          The value for the cookie.
 	 * @param array|\WpOrg\Requests\Utility\CaseInsensitiveDictionary $attributes Associative array of attribute data
-	 * @param array $flags
-	 * @param int|null $reference_time
+	 * @param array                                                   $flags          The flags for the cookie.
+	 *                                                                                Valid keys are `'creation'`, `'last-access'`,
+	 *                                                                                `'persistent'` and `'host-only'`.
+	 * @param int|null                                                $reference_time Reference time for relative calculations.
 	 *
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $name argument is not a string.
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $value argument is not a string.
@@ -279,7 +280,11 @@ public function path_matches($request_path) {
 	public function normalize() {
 		foreach ($this->attributes as $key => $value) {
 			$orig_value = $value;
-			$value      = $this->normalize_attribute($key, $value);
+
+			if (is_string($key)) {
+				$value = $this->normalize_attribute($key, $value);
+			}
+
 			if ($value === null) {
 				unset($this->attributes[$key]);
 				continue;
@@ -299,7 +304,7 @@ public function normalize() {
 	 * Handles parsing individual attributes from the cookie values.
 	 *
 	 * @param string $name Attribute name
-	 * @param string|boolean $value Attribute value (string value, or true if empty/flag)
+	 * @param string|int|bool $value Attribute value (string/integer value, or true if empty/flag)
 	 * @return mixed Value if available, or null if the attribute value is invalid (and should be skipped)
 	 */
 	protected function normalize_attribute($name, $value) {

src/wp-includes/Requests/src/Cookie/Jar.php

@@ -49,7 +49,8 @@ public function __construct($cookies = []) {
 	/**
 	 * Normalise cookie data into a \WpOrg\Requests\Cookie
 	 *
-	 * @param string|\WpOrg\Requests\Cookie $cookie
+	 * @param string|\WpOrg\Requests\Cookie $cookie Cookie header value, possibly pre-parsed (object).
+	 * @param string                        $key    Optional. The name for this cookie.
 	 * @return \WpOrg\Requests\Cookie
 	 */
 	public function normalize_cookie($cookie, $key = '') {
@@ -106,7 +107,7 @@ public function offsetSet($offset, $value) {
 	/**
 	 * Unset the given header
 	 *
-	 * @param string $offset
+	 * @param string $offset The key for the item to unset.
 	 */
 	#[ReturnTypeWillChange]
 	public function offsetUnset($offset) {
@@ -171,7 +172,7 @@ public function before_request($url, &$headers, &$data, &$type, &$options) {
 	/**
 	 * Parse all cookies from a response and attach them to the response
 	 *
-	 * @param \WpOrg\Requests\Response $response
+	 * @param \WpOrg\Requests\Response $response Response as received.
 	 */
 	public function before_redirect_check(Response $response) {
 		$url = $response->url;

src/wp-includes/Requests/src/IdnaEncoder.php

@@ -137,7 +137,7 @@ public static function to_ascii($text) {
 	 *
 	 * @internal (Testing found regex was the fastest implementation)
 	 *
-	 * @param string $text
+	 * @param string $text Text to examine.
 	 * @return bool Is the text string ASCII-only?
 	 */
 	protected static function is_ascii($text) {
@@ -148,7 +148,7 @@ protected static function is_ascii($text) {
 	 * Prepare a text string for use as an IDNA name
 	 *
 	 * @todo Implement this based on RFC 3491 and the newer 5891
-	 * @param string $text
+	 * @param string $text Text to prepare.
 	 * @return string Prepared string
 	 */
 	protected static function nameprep($text) {
@@ -160,7 +160,7 @@ protected static function nameprep($text) {
 	 *
 	 * Based on \WpOrg\Requests\Iri::replace_invalid_with_pct_encoding()
 	 *
-	 * @param string $input
+	 * @param string $input Text to convert.
 	 * @return array Unicode code points
 	 *
 	 * @throws \WpOrg\Requests\Exception Invalid UTF-8 codepoint (`idna.invalidcodepoint`)
@@ -329,10 +329,10 @@ public static function punycode_encode($input) {
 						}
 
 						// output the code point for digit t + ((q - t) mod (base - t))
-						$digit   = $t + (($q - $t) % (self::BOOTSTRAP_BASE - $t));
+						$digit   = (int) ($t + (($q - $t) % (self::BOOTSTRAP_BASE - $t)));
 						$output .= self::digit_to_char($digit);
 						// let q = (q - t) div (base - t)
-						$q = floor(($q - $t) / (self::BOOTSTRAP_BASE - $t));
+						$q = (int) floor(($q - $t) / (self::BOOTSTRAP_BASE - $t));
 					} // end
 					// output the code point for digit q
 					$output .= self::digit_to_char($q);
@@ -381,7 +381,7 @@ protected static function digit_to_char($digit) {
 	 * @param int $delta
 	 * @param int $numpoints
 	 * @param bool $firsttime
-	 * @return int New bias
+	 * @return int|float New bias
 	 *
 	 * function adapt(delta,numpoints,firsttime):
 	 */

src/wp-includes/Requests/src/Iri.php

@@ -395,11 +395,11 @@ protected function remove_dot_segments($input) {
 			// preceding "/" (if any) from the output buffer; otherwise,
 			elseif (strpos($input, '/../') === 0) {
 				$input = substr($input, 3);
-				$output = substr_replace($output, '', strrpos($output, '/'));
+				$output = substr_replace($output, '', (strrpos($output, '/') ?: 0));
 			}
 			elseif ($input === '/..') {
 				$input = '/';
-				$output = substr_replace($output, '', strrpos($output, '/'));
+				$output = substr_replace($output, '', (strrpos($output, '/') ?: 0));
 			}
 			// D: if the input buffer consists only of "." or "..", then remove
 			// that from the input buffer; otherwise,
@@ -824,7 +824,8 @@ protected function set_authority($authority) {
 		else {
 			$iuserinfo = null;
 		}
-		if (($port_start = strpos($remaining, ':', strpos($remaining, ']'))) !== false) {
+
+		if (($port_start = strpos($remaining, ':', (strpos($remaining, ']') ?: 0))) !== false) {
 			$port = substr($remaining, $port_start + 1);
 			if ($port === false || $port === '') {
 				$port = null;

src/wp-includes/Requests/src/Requests.php

@@ -148,7 +148,7 @@ class Requests {
 	 *
 	 * @var string
 	 */
-	const VERSION = '2.0.5';
+	const VERSION = '2.0.6';
 
 	/**
 	 * Selected transport name
@@ -642,12 +642,14 @@ public static function set_certificate_path($path) {
 	/**
 	 * Set the default values
 	 *
+	 * The $options parameter is updated with the results.
+	 *
 	 * @param string $url URL to request
 	 * @param array $headers Extra headers to send with the request
 	 * @param array|null $data Data to send either as a query string for GET/HEAD requests, or in the body for POST requests
 	 * @param string $type HTTP request type
 	 * @param array $options Options for the request
-	 * @return void $options is updated with the results
+	 * @return void
 	 *
 	 * @throws \WpOrg\Requests\Exception When the $url is not an http(s) URL.
 	 */
@@ -824,9 +826,11 @@ protected static function parse_response($headers, $url, $req_headers, $req_data
 	 * Internal use only. Converts a raw HTTP response to a \WpOrg\Requests\Response
 	 * while still executing a multiple request.
 	 *
+	 * `$response` is either set to a \WpOrg\Requests\Response instance, or a \WpOrg\Requests\Exception object
+	 *
 	 * @param string $response Full response text including headers and body (will be overwritten with Response instance)
 	 * @param array $request Request data as passed into {@see \WpOrg\Requests\Requests::request_multiple()}
-	 * @return void `$response` is either set to a \WpOrg\Requests\Response instance, or a \WpOrg\Requests\Exception object
+	 * @return void
 	 */
 	public static function parse_multiple(&$response, $request) {
 		try {

src/wp-includes/Requests/src/Response.php

@@ -137,16 +137,16 @@ public function throw_for_status($allow_redirects = true) {
 	 *
 	 * @link https://php.net/json-decode
 	 *
-	 * @param ?bool $associative Optional. When `true`, JSON objects will be returned as associative arrays;
-	 *                           When `false`, JSON objects will be returned as objects.
-	 *                           When `null`, JSON objects will be returned as associative arrays
-	 *                           or objects depending on whether `JSON_OBJECT_AS_ARRAY` is set in the flags.
-	 *                           Defaults to `true` (in contrast to the PHP native default of `null`).
-	 * @param int   $depth       Optional. Maximum nesting depth of the structure being decoded.
-	 *                           Defaults to `512`.
-	 * @param int   $options     Optional. Bitmask of JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE,
-	 *                           JSON_INVALID_UTF8_SUBSTITUTE, JSON_OBJECT_AS_ARRAY, JSON_THROW_ON_ERROR.
-	 *                           Defaults to `0` (no options set).
+	 * @param bool|null $associative Optional. When `true`, JSON objects will be returned as associative arrays;
+	 *                               When `false`, JSON objects will be returned as objects.
+	 *                               When `null`, JSON objects will be returned as associative arrays
+	 *                               or objects depending on whether `JSON_OBJECT_AS_ARRAY` is set in the flags.
+	 *                               Defaults to `true` (in contrast to the PHP native default of `null`).
+	 * @param int       $depth       Optional. Maximum nesting depth of the structure being decoded.
+	 *                               Defaults to `512`.
+	 * @param int       $options     Optional. Bitmask of JSON_BIGINT_AS_STRING, JSON_INVALID_UTF8_IGNORE,
+	 *                               JSON_INVALID_UTF8_SUBSTITUTE, JSON_OBJECT_AS_ARRAY, JSON_THROW_ON_ERROR.
+	 *                               Defaults to `0` (no options set).
 	 *
 	 * @return array
 	 *

src/wp-includes/Requests/src/Response/Headers.php

@@ -27,7 +27,7 @@ class Headers extends CaseInsensitiveDictionary {
 	 * Avoid using this where commas may be used unquoted in values, such as
 	 * Set-Cookie headers.
 	 *
-	 * @param string $offset
+	 * @param string $offset Name of the header to retrieve.
 	 * @return string|null Header value
 	 */
 	public function offsetGet($offset) {
@@ -69,7 +69,7 @@ public function offsetSet($offset, $value) {
 	/**
 	 * Get all values for a given header
 	 *
-	 * @param string $offset
+	 * @param string $offset Name of the header to retrieve.
 	 * @return array|null Header values
 	 *
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed argument is not valid as an array key.
@@ -79,7 +79,10 @@ public function getValues($offset) {
 			throw InvalidArgument::create(1, '$offset', 'string|int', gettype($offset));
 		}
 
-		$offset = strtolower($offset);
+		if (is_string($offset)) {
+			$offset = strtolower($offset);
+		}
+
 		if (!isset($this->data[$offset])) {
 			return null;
 		}

src/wp-includes/Requests/src/Transport/Curl.php

@@ -465,7 +465,7 @@ private function setup_handle($url, $headers, $data, $options) {
 	 * @param string $response Response data from the body
 	 * @param array $options Request options
 	 * @return string|false HTTP response data including headers. False if non-blocking.
-	 * @throws \WpOrg\Requests\Exception
+	 * @throws \WpOrg\Requests\Exception If the request resulted in a cURL error.
 	 */
 	public function process_response($response, $options) {
 		if ($options['blocking'] === false) {
@@ -561,7 +561,7 @@ public function stream_body($handle, $data) {
 	/**
 	 * Format a URL given GET data
 	 *
-	 * @param string $url
+	 * @param string       $url  Original URL.
 	 * @param array|object $data Data to build query using, see {@link https://www.php.net/http_build_query}
 	 * @return string URL with data
 	 */