PHP 8.6 | Make "characters to be trimmed" explicit

build/ghpages/UpdateMarkdown.php

@@ -20,6 +20,7 @@
  *
  * @package Requests\GHPages
  *
+ * @phpcs:disable PHPCompatibility.Classes.NewConstVisibility.Found
  * @phpcs:disable PHPCompatibility.FunctionDeclarations.NewParamTypeDeclarations.stringFound
  * @phpcs:disable PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations.intFound
  * @phpcs:disable PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations.stringFound
@@ -28,6 +29,13 @@
  */
 class UpdateMarkdown {
 
+	/**
+	 * The ASCII whitespace characters and the null byte.
+	 *
+	 * @var string
+	 */
+	private const WHITESPACE_CHARS = " \f\n\r\t\v\x00";
+
 	/**
 	 * Target directory for the updated/transformed files.
 	 *
@@ -282,7 +290,7 @@ private function update_docs_navigation(string $source): void {
 		/*
 		 * Create the docs index file.
 		 */
-		$docs_index = trim($parts[0]);
+		$docs_index = trim($parts[0], self::WHITESPACE_CHARS);
 
 		// Grab the title.
 		$title = $this->get_title_from_contents($contents);
@@ -300,7 +308,7 @@ private function update_docs_navigation(string $source): void {
 		/*
 		 * Create the docs navigation file.
 		 */
-		$navigation = trim($parts[1]);
+		$navigation = trim($parts[1], self::WHITESPACE_CHARS);
 
 		// Write the file.
 		$target = $this->target . '/_includes/navigation.md';
@@ -349,7 +357,7 @@ private function put_contents(string $target, string $contents, string $type = '
 		} // phpcs:enable WordPress
 
 		// Make sure the file always ends on a new line.
-		$contents = rtrim($contents) . "\n";
+		$contents = rtrim($contents, self::WHITESPACE_CHARS) . "\n";
 		if (file_put_contents($target, $contents) === false) {
 			throw new RuntimeException(sprintf('Failed to write %s to target location: %s', $type, $target));
 		}
@@ -363,7 +371,7 @@ private function put_contents(string $target, string $contents, string $type = '
 	 * @return string
 	 */
 	private function get_title_from_contents(string $contents): string {
-		return trim(substr($contents, 0, (strpos($contents, '===') - 1)));
+		return trim(substr($contents, 0, (strpos($contents, '===') - 1)), self::WHITESPACE_CHARS);
 	}
 
 	/**

src/Cookie.php

@@ -14,6 +14,7 @@
 use WpOrg\Requests\Response\Headers;
 use WpOrg\Requests\Utility\CaseInsensitiveDictionary;
 use WpOrg\Requests\Utility\InputValidator;
+use WpOrg\Requests\Utility\Trim;
 
 /**
  * Cookie storage object
@@ -440,7 +441,7 @@ public static function parse($cookie_header, $name = '', $reference_time = null)
 		}
 
 		if (is_string($name)) {
-			$name = trim($name);
+			$name = trim($name, Trim::WHITESPACE_CHARS_NO_FF);
 		}
 
 		if ($name !== '' && InputValidator::is_valid_rfc2616_token($name) === false) {
@@ -464,8 +465,8 @@ public static function parse($cookie_header, $name = '', $reference_time = null)
 			list($name, $value) = explode('=', $kvparts, 2);
 		}
 
-		$name  = trim($name);
-		$value = trim($value);
+		$name  = trim($name, Trim::WHITESPACE_CHARS_NO_FF);
+		$value = trim($value, Trim::WHITESPACE_CHARS_NO_FF);
 
 		if ($name !== '' && InputValidator::is_valid_rfc2616_token($name) === false) {
 			throw InvalidArgument::create(2, '$name', 'integer|string and conform to RFC 2616', gettype($name));
@@ -481,10 +482,10 @@ public static function parse($cookie_header, $name = '', $reference_time = null)
 					$part_value = true;
 				} else {
 					list($part_key, $part_value) = explode('=', $part, 2);
-					$part_value                  = trim($part_value);
+					$part_value                  = trim($part_value, Trim::WHITESPACE_CHARS_NO_FF);
 				}
 
-				$part_key              = trim($part_key);
+				$part_key              = trim($part_key, Trim::WHITESPACE_CHARS_NO_FF);
 				$attributes[$part_key] = $part_value;
 			}
 		}

src/Requests.php

@@ -22,6 +22,7 @@
 use WpOrg\Requests\Transport\Curl;
 use WpOrg\Requests\Transport\Fsockopen;
 use WpOrg\Requests\Utility\InputValidator;
+use WpOrg\Requests\Utility\Trim;
 
 /**
  * Requests for PHP
@@ -762,7 +763,7 @@ protected static function parse_response($headers, $url, $req_headers, $req_data
 
 		foreach ($headers as $header) {
 			list($key, $value) = explode(':', $header, 2);
-			$value             = trim($value);
+			$value             = trim($value, Trim::WHITESPACE_CHARS_NO_FF);
 			preg_replace('#(\s+)#i', ' ', $value);
 			$return->headers[$key] = $value;
 		}
@@ -851,7 +852,7 @@ public static function parse_multiple(&$response, $request) {
 	 * @return string Decoded body
 	 */
 	protected static function decode_chunked($data) {
-		if (!preg_match('/^([0-9a-f]+)(?:;(?:[\w-]*)(?:=(?:(?:[\w-]*)*|"(?:[^\r\n])*"))?)*\r\n/i', trim($data))) {
+		if (!preg_match('/^([0-9a-f]+)(?:;(?:[\w-]*)(?:=(?:(?:[\w-]*)*|"(?:[^\r\n])*"))?)*\r\n/i', trim($data, Trim::WHITESPACE_CHARS_NO_FF))) {
 			return $data;
 		}
 
@@ -865,7 +866,7 @@ protected static function decode_chunked($data) {
 				return $data;
 			}
 
-			$length = hexdec(trim($matches[1]));
+			$length = hexdec(trim($matches[1], Trim::WHITESPACE_CHARS_NO_FF));
 			if ($length === 0) {
 				// Ignore trailer headers
 				return $decoded;
@@ -875,7 +876,7 @@ protected static function decode_chunked($data) {
 			$decoded     .= substr($encoded, $chunk_length, $length);
 			$encoded      = substr($encoded, $chunk_length + $length + 2);
 
-			if (trim($encoded) === '0' || empty($encoded)) {
+			if (trim($encoded, Trim::WHITESPACE_CHARS_NO_FF) === '0' || empty($encoded)) {
 				return $decoded;
 			}
 		}
@@ -922,7 +923,7 @@ public static function decompress($data) {
 			throw InvalidArgument::create(1, '$data', 'string', gettype($data));
 		}
 
-		if (trim($data) === '') {
+		if (trim($data, Trim::WHITESPACE_CHARS_NO_FF) === '') {
 			// Empty body does not need further processing.
 			return $data;
 		}
@@ -989,7 +990,7 @@ public static function compatible_gzinflate($gz_data) {
 			throw InvalidArgument::create(1, '$gz_data', 'string', gettype($gz_data));
 		}
 
-		if (trim($gz_data) === '') {
+		if (trim($gz_data, Trim::WHITESPACE_CHARS_NO_FF) === '') {
 			return false;
 		}
 

src/Ssl.php

@@ -11,6 +11,7 @@
 
 use WpOrg\Requests\Exception\InvalidArgument;
 use WpOrg\Requests\Utility\InputValidator;
+use WpOrg\Requests\Utility\Trim;
 
 /**
  * SSL utilities for Requests
@@ -49,15 +50,15 @@ public static function verify_certificate($host, $cert) {
 		if (!empty($cert['extensions']['subjectAltName'])) {
 			$altnames = explode(',', $cert['extensions']['subjectAltName']);
 			foreach ($altnames as $altname) {
-				$altname = trim($altname);
+				$altname = trim($altname, Trim::WHITESPACE_CHARS_NO_FF);
 				if (strpos($altname, 'DNS:') !== 0) {
 					continue;
 				}
 
 				$has_dns_alt = true;
 
 				// Strip the 'DNS:' prefix and trim whitespace
-				$altname = trim(substr($altname, 4));
+				$altname = trim(substr($altname, 4), Trim::WHITESPACE_CHARS_NO_FF);
 
 				// Check for a match
 				if (self::match_domain($host, $altname) === true) {

src/Transport/Curl.php

@@ -18,6 +18,7 @@
 use WpOrg\Requests\Requests;
 use WpOrg\Requests\Transport;
 use WpOrg\Requests\Utility\InputValidator;
+use WpOrg\Requests\Utility\Trim;
 
 /**
  * HTTP transport using libcurl.
@@ -500,7 +501,7 @@ public function process_response($response, $options) {
 
 		if ($options['filename'] !== false && $this->stream_handle) {
 			fclose($this->stream_handle);
-			$this->headers = trim($this->headers);
+			$this->headers = trim($this->headers, Trim::WHITESPACE_CHARS_NO_FF);
 		} else {
 			$this->headers .= $response;
 		}

src/Transport/Fsockopen.php

@@ -18,6 +18,7 @@
 use WpOrg\Requests\Transport;
 use WpOrg\Requests\Utility\CaseInsensitiveDictionary;
 use WpOrg\Requests\Utility\InputValidator;
+use WpOrg\Requests\Utility\Trim;
 
 /**
  * fsockopen HTTP transport
@@ -182,7 +183,7 @@ public function request($url, $headers = [], $data = [], $options = []) {
 		if (!$socket) {
 			if ($errno === 0) {
 				// Connection issue
-				throw new Exception(rtrim($this->connect_error), 'fsockopen.connect_error');
+				throw new Exception(rtrim($this->connect_error, Trim::WHITESPACE_CHARS), 'fsockopen.connect_error');
 			}
 
 			throw new Exception($errstr, 'fsockopenerror', null, $errno);
@@ -492,7 +493,7 @@ public function verify_certificate_from_context($host, $context) {
 		// If we don't have SSL options, then we couldn't make the connection at
 		// all
 		if (empty($meta) || empty($meta['ssl']) || empty($meta['ssl']['peer_certificate'])) {
-			throw new Exception(rtrim($this->connect_error), 'ssl.connect_error');
+			throw new Exception(rtrim($this->connect_error, Trim::WHITESPACE_CHARS), 'ssl.connect_error');
 		}
 
 		$cert = openssl_x509_parse($meta['ssl']['peer_certificate']);

src/Utility/Trim.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * Requests for PHP, an HTTP library.
+ *
+ * @copyright 2012-2023 Requests Contributors
+ * @license   https://github.com/WordPress/Requests/blob/stable/LICENSE ISC
+ * @link      https://github.com/WordPress/Requests
+ */
+
+namespace WpOrg\Requests\Utility;
+
+/**
+ * Poor person's (backed) enum with the PHP native trim `$characters` defaults to choose from.
+ *
+ * In PHP 8.6, the default value for the `$characters` parameter of the `[rl]trim()` function
+ * changed to include the form feed character.
+ *
+ * This "enum" allows calls to `[rl]trim()` throughout the code to document and make it explicit
+ * which characters should be trimmed from the text string in question.
+ *
+ * @link https://wiki.php.net/rfc/trim_form_feed
+ *
+ * ---------------------------------------------------------------------------------------------
+ * This class is only intended for internal use by Requests and is not part of the public API.
+ * This also means that it has no promise of backward compatibility. Use at your own risk.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * @internal
+ * @package Requests\Utilities
+ * @since   2.1.0
+ */
+final class Trim {
+
+	/**
+	 * The ASCII whitespace characters and the NUL byte, excluding the form feed character.
+	 *
+	 * This is the PHP native default in PHP < 8.6.
+	 *
+	 * @var string
+	 */
+	const WHITESPACE_CHARS_NO_FF = " \n\r\t\v\x00";
+
+	/**
+	 * The ASCII whitespace characters, including the form feed character, and the NUL byte.
+	 *
+	 * This is the PHP native default in PHP >= 8.6.
+	 *
+	 * @var string
+	 */
+	const WHITESPACE_CHARS = " \f\n\r\t\v\x00";
+}