Allow integers as cookie names (#847)

Modify data validation checks, exception messages, and docblocks to allow cookie names to be integers. This affects both the constructor and the parse() method.
Also modified unit tests to allow strings and integers, and to validate the updated exception messages.

---------

Co-authored-by: Alain Schlesser <alain.schlesser@gmail.com>
Co-authored-by: jrfnl <jrfnl@users.noreply.github.com>

Author: 3 people

src/Cookie.php

@@ -67,23 +67,23 @@ class Cookie {
 	/**
 	 * Create a new cookie object
 	 *
-	 * @param string                                                  $name           The name of the cookie.
+	 * @param int|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          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 $name argument is not an integer or string that conforms to RFC 2616.
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $value argument is not a string.
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $attributes argument is not an array or iterable object with array access.
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $flags argument is not an array.
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $reference_time argument is not an integer or null.
 	 */
 	public function __construct($name, $value, $attributes = [], $flags = [], $reference_time = null) {
-		if (is_string($name) === false) {
-			throw InvalidArgument::create(1, '$name', 'string', gettype($name));
+		if ($name !== '' && InputValidator::is_valid_rfc2616_token($name) === false) {
+			throw InvalidArgument::create(1, '$name', 'integer|string and conform to RFC 2616', gettype($name));
 		}
 
 		if (is_string($value) === false) {
@@ -102,7 +102,7 @@ public function __construct($name, $value, $attributes = [], $flags = [], $refer
 			throw InvalidArgument::create(5, '$reference_time', 'integer|null', gettype($reference_time));
 		}
 
-		$this->name       = $name;
+		$this->name       = (string) $name;
 		$this->value      = $value;
 		$this->attributes = $attributes;
 		$default_flags    = [
@@ -426,9 +426,9 @@ public function format_for_set_cookie() {
 	 * is an intentional deviation from RFC 2109 and RFC 2616. RFC 6265
 	 * specifies some of this handling, but not in a thorough manner.
 	 *
-	 * @param string   $cookie_header  Cookie header value (from a Set-Cookie header)
-	 * @param string   $name
-	 * @param int|null $reference_time
+	 * @param int|string $cookie_header  Cookie header value (from a Set-Cookie header)
+	 * @param string     $name
+	 * @param int|null   $reference_time
 	 * @return \WpOrg\Requests\Cookie Parsed cookie object
 	 *
 	 * @throws \WpOrg\Requests\Exception\InvalidArgument When the passed $cookie_header argument is not a string.
@@ -439,8 +439,12 @@ public static function parse($cookie_header, $name = '', $reference_time = null)
 			throw InvalidArgument::create(1, '$cookie_header', 'string', gettype($cookie_header));
 		}
 
-		if (is_string($name) === false) {
-			throw InvalidArgument::create(2, '$name', 'string', gettype($name));
+		if (is_string($name)) {
+			$name = trim($name);
+		}
+
+		if ($name !== '' && InputValidator::is_valid_rfc2616_token($name) === false) {
+			throw InvalidArgument::create(2, '$name', 'integer|string and conform to RFC 2616', gettype($name));
 		}
 
 		$parts   = explode(';', $cookie_header);
@@ -463,6 +467,10 @@ public static function parse($cookie_header, $name = '', $reference_time = null)
 		$name  = trim($name);
 		$value = trim($value);
 
+		if ($name !== '' && InputValidator::is_valid_rfc2616_token($name) === false) {
+			throw InvalidArgument::create(2, '$name', 'integer|string and conform to RFC 2616', gettype($name));
+		}
+
 		// Attribute keys are handled case-insensitively
 		$attributes = new CaseInsensitiveDictionary();
 

tests/Cookie/ConstructorTest.php

@@ -16,19 +16,30 @@ final class ConstructorTest extends TestCase {
 	/**
 	 * Tests receiving an exception when the constructor received an invalid input type as `$name`.
 	 *
-	 * @dataProvider dataInvalidStringInput
+	 * @dataProvider dataInvalidName
 	 *
 	 * @param mixed $input Invalid parameter input.
 	 *
 	 * @return void
 	 */
 	public function testInvalidName($input) {
 		$this->expectException(InvalidArgument::class);
-		$this->expectExceptionMessage('Argument #1 ($name) must be of type string');
+		$this->expectExceptionMessage('Argument #1 ($name) must be of type integer|string and conform to RFC 2616');
 
 		new Cookie($input, 'value');
 	}
 
+	/**
+	 * Data Provider.
+	 *
+	 * @return array
+	 */
+	public static function dataInvalidName() {
+		$data = TypeProviderHelper::getAllExcept(TypeProviderHelper::GROUP_INT, TypeProviderHelper::GROUP_STRING);
+		$data['Valid string, but not a valid RFC 2616 token'] = ["some\ntext\rwith\tcontrol\echaracters\fin\vit"];
+		return $data;
+	}
+
 	/**
 	 * Tests receiving an exception when the constructor received an invalid input type as `$value`.
 	 *

tests/Cookie/ParseTest.php

@@ -32,10 +32,19 @@ public function testParseInvalidCookieHeader($input) {
 		Cookie::parse($input);
 	}
 
+	/**
+	 * Data Provider.
+	 *
+	 * @return array
+	 */
+	public static function dataInvalidStringInput() {
+		return TypeProviderHelper::getAllExcept(TypeProviderHelper::GROUP_STRING);
+	}
+
 	/**
 	 * Tests receiving an exception when the parse() method received an invalid input type as `$name`.
 	 *
-	 * @dataProvider dataInvalidStringInput
+	 * @dataProvider dataParseInvalidName
 	 *
 	 * @covers ::parse
 	 *
@@ -45,7 +54,7 @@ public function testParseInvalidCookieHeader($input) {
 	 */
 	public function testParseInvalidName($input) {
 		$this->expectException(InvalidArgument::class);
-		$this->expectExceptionMessage('Argument #2 ($name) must be of type string');
+		$this->expectExceptionMessage('Argument #2 ($name) must be of type integer|string and conform to RFC 2616');
 
 		Cookie::parse('test', $input);
 	}
@@ -55,8 +64,10 @@ public function testParseInvalidName($input) {
 	 *
 	 * @return array
 	 */
-	public static function dataInvalidStringInput() {
-		return TypeProviderHelper::getAllExcept(TypeProviderHelper::GROUP_STRING);
+	public static function dataParseInvalidName() {
+		$data = TypeProviderHelper::getAllExcept(TypeProviderHelper::GROUP_INT, TypeProviderHelper::GROUP_STRING);
+		$data['Valid string, but not a valid RFC 2616 token'] = ["some\ntext\rwith\tcontrol\echaracters\fin\vit"];
+		return $data;
 	}
 
 	/**