Add withCookie() & getCookie()

These methods provide cookie methods that better match the PSR7
conventions.

src/Network/Response.php

@@ -1912,6 +1912,7 @@ class Response implements ResponseInterface
      * @param array|null $options Either null to get all cookies, string for a specific cookie
      *  or array to set cookie.
      * @return mixed
+     * @deprecated 3.4.0 Use getCookie() and withCookie() instead.
      */
     public function cookie($options = null)
     {
@@ -1942,6 +1943,53 @@ class Response implements ResponseInterface
     }
 
     /**
+     * Create a new response with a cookie set.
+     *
+     * @param string $name The name of the cookie to set.
+     * @param array|string $data Either a string value, or an array of cookie data.
+     * @return static
+     */
+    public function withCookie($name, $data = '')
+    {
+        if (!is_array($data)) {
+            $data = ['value' => $data];
+        }
+        $defaults = [
+            'value' => '',
+            'expire' => 0,
+            'path' => '/',
+            'domain' => '',
+            'secure' => false,
+            'httpOnly' => false
+        ];
+        $data += $defaults;
+        $data['name'] = $name;
+
+        $new = clone $this;
+        $new->_cookies[$name] = $data;
+
+        return $new;
+    }
+
+    /**
+     * Read a single cookie from the response.
+     *
+     * This method provides read access to pending cookies. It will
+     * not read the `Set-Cookie` header if set.
+     *
+     * @param string $name The cookie name you want to read.
+     * @return array|null Either the cookie data or null
+     */
+    public function getCookie($name)
+    {
+        if (isset($this->_cookies[$name])) {
+            return $this->_cookies[$name];
+        }
+
+        return null;
+    }
+
+    /**
      * Setup access for origin and methods on cross origin requests
      *
      * This method allow multiple ways to setup the domains, see the examples

tests/TestCase/Network/ResponseTest.php

@@ -1360,6 +1360,80 @@ class ResponseTest extends TestCase
     }
 
     /**
+     * Test setting cookies with no value
+     *
+     * @return void
+     */
+    public function testWithCookieEmpty()
+    {
+        $response = new Response();
+        $new = $response->withCookie('testing');
+        $this->assertNull($response->getCookie('testing'), 'withCookie does not mutate');
+
+        $expected = [
+            'name' => 'testing',
+            'value' => '',
+            'expire' => 0,
+            'path' => '/',
+            'domain' => '',
+            'secure' => false,
+            'httpOnly' => false];
+        $result = $new->getCookie('testing');
+        $this->assertEquals($expected, $result);
+    }
+
+    /**
+     * Test setting cookies with scalar values
+     *
+     * @return void
+     */
+    public function testWithCookieScalar()
+    {
+        $response = new Response();
+        $new = $response->withCookie('testing', 'abc123');
+        $this->assertNull($response->getCookie('testing'), 'withCookie does not mutate');
+        $this->assertEquals('abc123', $new->getCookie('testing')['value']);
+
+        $new = $response->withCookie('testing', 99);
+        $this->assertEquals(99, $new->getCookie('testing')['value']);
+
+        $new = $response->withCookie('testing', false);
+        $this->assertFalse($new->getCookie('testing')['value']);
+
+        $new = $response->withCookie('testing', true);
+        $this->assertTrue($new->getCookie('testing')['value']);
+    }
+
+    /**
+     * Test withCookie() and array data.
+     *
+     * @return void
+     */
+    public function testWithCookieArray()
+    {
+        $response = new Response();
+        $cookie = [
+            'name' => 'ignored key',
+            'value' => '[a,b,c]',
+            'expire' => 1000,
+            'path' => '/test',
+            'secure' => true
+        ];
+        $new = $response->withCookie('testing', $cookie);
+        $this->assertNull($response->getCookie('testing'), 'withCookie does not mutate');
+        $expected = [
+            'name' => 'testing',
+            'value' => '[a,b,c]',
+            'expire' => 1000,
+            'path' => '/test',
+            'domain' => '',
+            'secure' => true,
+            'httpOnly' => false
+        ];
+        $this->assertEquals($expected, $new->getCookie('testing'));
+    }
+
+    /**
      * Test CORS
      *
      * @dataProvider corsData