Add parameter $encodeValue to Cookie constructor and Cookie::withRawValue() method

CHANGELOG.md

@@ -3,7 +3,8 @@
 
 ## 1.1.1 under development
 
-- no changes in this release.
+- Add #27: Add the parameter `$encodeValue` to the `Cookie` constructor and the `Cookie::withRawValue()` method 
+ that creates a cookie copy with a new value that will not be encoded (vjik)
 
 
 ## 1.1.0 May 05, 2021

README.md

@@ -140,6 +140,13 @@ $middleware = new \Yiisoft\Cookies\CookieMiddleware(
 $response = $middleware->process($request, $handler);
 ```
 
+Create cookie with raw value that will not be encoded:
+
+```php
+$cookie = (new \Yiisoft\Cookies\Cookie('cookieName'))
+ ->withRawValue('ebaKUq90PhiHck_MR7st-E1SxhbYWiTsLo82mCTbNuAh7rgflx5LVsYfJJseyQCrODuVcJkTSYhm1WKte-l5lQ==')
+```
+
 See [Yii guide to cookies](https://github.com/yiisoft/docs/blob/master/guide/en/runtime/cookies.md) for more info.
 
 ## Testing

src/Cookie.php

@@ -70,6 +70,11 @@ final class Cookie
  */
  private string $value;
 
+ /**
+ * @var bool Whether cookie value should be encoded.
+ */
+ private bool $encodeValue;
+
  /**
  * @var DateTimeInterface|null The maximum lifetime of the cookie.
  * If unspecified, the cookie becomes a session cookie, which will be removed
@@ -127,6 +132,7 @@ final class Cookie
  * @param bool|null $secure Whether the client should send back the cookie only over HTTPS connection.
  * @param bool|null $httpOnly Whether the cookie should be accessible only through the HTTP protocol.
  * @param string|null $sameSite Whether the cookie should be available for cross-site requests.
+ * @param bool $encodeValue Whether cookie value should be encoded.
  *
  * @throws InvalidArgumentException When one or more arguments are not valid.
  */
@@ -138,14 +144,16 @@ public function __construct(
  ?string $path = '/',
  ?bool $secure = true,
  ?bool $httpOnly = true,
- ?string $sameSite = self::SAME_SITE_LAX
+ ?string $sameSite = self::SAME_SITE_LAX,
+ bool $encodeValue = true
  ) {
  if (!preg_match(self::PATTERN_TOKEN, $name)) {
  throw new InvalidArgumentException("The cookie name \"$name\" contains invalid characters or is empty.");
  }
 
  $this->name = $name;
- $this->setValue($value);
+ $this->value = $value;
+ $this->encodeValue = $encodeValue;
  $this->expires = $expires !== null ? clone $expires : null;
  $this->domain = $domain;
  $this->setPath($path);
@@ -176,7 +184,21 @@ public function getName(): string
  public function withValue(string $value): self
  {
  $new = clone $this;
- $new->setValue($value);
+ $new->value = $value;
+ $new->encodeValue = true;
+ return $new;
+ }
+
+ /**
+ * Creates a cookie copy with a new value that will not be encoded.
+ *
+ * @param $value string Value of the cookie.
+ */
+ public function withRawValue(string $value): self
+ {
+ $new = clone $this;
+ $new->value = $value;
+ $new->encodeValue = false;
  return $new;
  }
 
@@ -190,11 +212,6 @@ public function getValue(): string
  return $this->value;
  }
 
- private function setValue(string $value): void
- {
- $this->value = $value;
- }
-
  /**
  * Creates a cookie copy with a new time the cookie expires.
  *
@@ -450,7 +467,7 @@ public function addToResponse(ResponseInterface $response): ResponseInterface
  public function __toString(): string
  {
  $cookieParts = [
- $this->name . '=' . urlencode($this->value),
+ $this->name . '=' . ($this->encodeValue ? urlencode($this->value) : $this->value),
  ];
 
  if ($this->expires !== null) {

tests/CookieTest.php

@@ -292,6 +292,14 @@ public function testGetters(): void
  $this->assertEquals(Cookie::SAME_SITE_LAX, $cookie->getSameSite());
  }
 
+ public function testRawValue(): void
+ {
+ $cookie = (new Cookie('test'))->withRawValue('Q==');
+
+ $this->assertSame('Q==', $cookie->getValue());
+ $this->assertSame('test=Q==; Path=/; Secure; HttpOnly; SameSite=Lax', (string)$cookie);
+ }
+
  public function testImmutability(): void
  {
  $expires = new DateTime();
@@ -310,6 +318,7 @@ public function testImmutability(): void
  $this->assertNotSame($original, $original->withSameSite(Cookie::SAME_SITE_LAX));
  $this->assertNotSame($original, $original->withSecure(true));
  $this->assertNotSame($original, $original->withValue('value'));
+ $this->assertNotSame($original, $original->withRawValue('value'));
  $this->assertNotSame($original, $original->expire());
  $this->assertNotSame($original, $original->expireWhenBrowserIsClosed());
  }