vendor/symfony/http-foundation/Cookie.php line 19

  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\HttpFoundation;
  14. /**
  15.  * Represents a cookie.
  16.  *
  17.  * @author Johannes M. Schmitt <schmittjoh@gmail.com>
  18.  */
  19. class Cookie
  20. {
  21.     public const SAMESITE_NONE = 'none';
  22.     public const SAMESITE_LAX = 'lax';
  23.     public const SAMESITE_STRICT = 'strict';
  25.     protected $name;
  26.     protected $value;
  27.     protected $domain;
  28.     protected $expire;
  29.     protected $path;
  30.     protected $secure;
  31.     protected $httpOnly;
  33.     private bool $raw;
  34.     private ?string $sameSite = null;
  35.     private bool $partitioned = false;
  36.     private bool $secureDefault = false;
  38.     private const RESERVED_CHARS_LIST = "=,; \t\r\n\v\f";
  39.     private const RESERVED_CHARS_FROM = ['=', ',', ';', ' ', "\t", "\r", "\n", "\v", "\f"];
  40.     private const RESERVED_CHARS_TO = ['%3D', '%2C', '%3B', '%20', '%09', '%0D', '%0A', '%0B', '%0C'];
  42.     /**
  43.      * Creates cookie from raw header string.
  44.      */
  45.     public static function fromString(string $cookie, bool $decode = false): static
  46.     {
  47.         $data = [
  48.             'expires' => 0,
  49.             'path' => '/',
  50.             'domain' => null,
  51.             'secure' => false,
  52.             'httponly' => false,
  53.             'raw' => !$decode,
  54.             'samesite' => null,
  55.             'partitioned' => false,
  56.         ];
  58.         $parts = HeaderUtils::split($cookie, ';=');
  59.         $part = array_shift($parts);
  61.         $name = $decode ? urldecode($part[0]) : $part[0];
  62.         $value = isset($part[1]) ? ($decode ? urldecode($part[1]) : $part[1]) : null;
  64.         $data = HeaderUtils::combine($parts) + $data;
  65.         $data['expires'] = self::expiresTimestamp($data['expires']);
  67.         if (isset($data['max-age']) && ($data['max-age'] > 0 || $data['expires'] > time())) {
  68.             $data['expires'] = time() + (int) $data['max-age'];
  69.         }
  71.         return new static($name, $value, $data['expires'], $data['path'], $data['domain'], $data['secure'], $data['httponly'], $data['raw'], $data['samesite'], $data['partitioned']);
  72.     }
  74.     /**
  75.      * @see self::__construct
  76.      *
  77.      * @param self::SAMESITE_*|''|null $sameSite
  78.      * @param bool                     $partitioned
  79.      */
  80.     public static function create(string $name, ?string $value = null, int|string|\DateTimeInterface $expire = 0, ?string $path = '/', ?string $domain = null, ?bool $secure = null, bool $httpOnly = true, bool $raw = false, ?string $sameSite = self::SAMESITE_LAX /* , bool $partitioned = false */): self
  81.     {
  82.         $partitioned = 9 < \func_num_args() ? func_get_arg(9) : false;
  84.         return new self($name, $value, $expire, $path, $domain, $secure, $httpOnly, $raw, $sameSite, $partitioned);
  85.     }
  87.     /**
  88.      * @param string                        $name     The name of the cookie
  89.      * @param string|null                   $value    The value of the cookie
  90.      * @param int|string|\DateTimeInterface $expire   The time the cookie expires
  91.      * @param string|null                   $path     The path on the server in which the cookie will be available on
  92.      * @param string|null                   $domain   The domain that the cookie is available to
  93.      * @param bool|null                     $secure   Whether the client should send back the cookie only over HTTPS or null to auto-enable this when the request is already using HTTPS
  94.      * @param bool                          $httpOnly Whether the cookie will be made accessible only through the HTTP protocol
  95.      * @param bool                          $raw      Whether the cookie value should be sent with no url encoding
  96.      * @param self::SAMESITE_*|''|null      $sameSite Whether the cookie will be available for cross-site requests
  97.      *
  98.      * @throws \InvalidArgumentException
  99.      */
  100.     public function __construct(string $name, ?string $value = null, int|string|\DateTimeInterface $expire = 0, ?string $path = '/', ?string $domain = null, ?bool $secure = null, bool $httpOnly = true, bool $raw = false, ?string $sameSite = self::SAMESITE_LAX, bool $partitioned = false)
  101.     {
  102.         // from PHP source code
  103.         if ($raw && false !== strpbrk($name, self::RESERVED_CHARS_LIST)) {
  104.             throw new \InvalidArgumentException(sprintf('The cookie name "%s" contains invalid characters.', $name));
  105.         }
  107.         if (empty($name)) {
  108.             throw new \InvalidArgumentException('The cookie name cannot be empty.');
  109.         }
  111.         $this->name = $name;
  112.         $this->value = $value;
  113.         $this->domain = $domain;
  114.         $this->expire = self::expiresTimestamp($expire);
  115.         $this->path = empty($path) ? '/' : $path;
  116.         $this->secure = $secure;
  117.         $this->httpOnly = $httpOnly;
  118.         $this->raw = $raw;
  119.         $this->sameSite = $this->withSameSite($sameSite)->sameSite;
  120.         $this->partitioned = $partitioned;
  121.     }
  123.     /**
  124.      * Creates a cookie copy with a new value.
  125.      */
  126.     public function withValue(?string $value): static
  127.     {
  128.         $cookie = clone $this;
  129.         $cookie->value = $value;
  131.         return $cookie;
  132.     }
  134.     /**
  135.      * Creates a cookie copy with a new domain that the cookie is available to.
  136.      */
  137.     public function withDomain(?string $domain): static
  138.     {
  139.         $cookie = clone $this;
  140.         $cookie->domain = $domain;
  142.         return $cookie;
  143.     }
  145.     /**
  146.      * Creates a cookie copy with a new time the cookie expires.
  147.      */
  148.     public function withExpires(int|string|\DateTimeInterface $expire = 0): static
  149.     {
  150.         $cookie = clone $this;
  151.         $cookie->expire = self::expiresTimestamp($expire);
  153.         return $cookie;
  154.     }
  156.     /**
  157.      * Converts expires formats to a unix timestamp.
  158.      */
  159.     private static function expiresTimestamp(int|string|\DateTimeInterface $expire = 0): int
  160.     {
  161.         // convert expiration time to a Unix timestamp
  162.         if ($expire instanceof \DateTimeInterface) {
  163.             $expire = $expire->format('U');
  164.         } elseif (!is_numeric($expire)) {
  165.             $expire = strtotime($expire);
  167.             if (false === $expire) {
  168.                 throw new \InvalidArgumentException('The cookie expiration time is not valid.');
  169.             }
  170.         }
  172.         return 0 < $expire ? (int) $expire : 0;
  173.     }
  175.     /**
  176.      * Creates a cookie copy with a new path on the server in which the cookie will be available on.
  177.      */
  178.     public function withPath(string $path): static
  179.     {
  180.         $cookie = clone $this;
  181.         $cookie->path = '' === $path ? '/' : $path;
  183.         return $cookie;
  184.     }
  186.     /**
  187.      * Creates a cookie copy that only be transmitted over a secure HTTPS connection from the client.
  188.      */
  189.     public function withSecure(bool $secure = true): static
  190.     {
  191.         $cookie = clone $this;
  192.         $cookie->secure = $secure;
  194.         return $cookie;
  195.     }
  197.     /**
  198.      * Creates a cookie copy that be accessible only through the HTTP protocol.
  199.      */
  200.     public function withHttpOnly(bool $httpOnly = true): static
  201.     {
  202.         $cookie = clone $this;
  203.         $cookie->httpOnly = $httpOnly;
  205.         return $cookie;
  206.     }
  208.     /**
  209.      * Creates a cookie copy that uses no url encoding.
  210.      */
  211.     public function withRaw(bool $raw = true): static
  212.     {
  213.         if ($raw && false !== strpbrk($this->name, self::RESERVED_CHARS_LIST)) {
  214.             throw new \InvalidArgumentException(sprintf('The cookie name "%s" contains invalid characters.', $this->name));
  215.         }
  217.         $cookie = clone $this;
  218.         $cookie->raw = $raw;
  220.         return $cookie;
  221.     }
  223.     /**
  224.      * Creates a cookie copy with SameSite attribute.
  225.      *
  226.      * @param self::SAMESITE_*|''|null $sameSite
  227.      */
  228.     public function withSameSite(?string $sameSite): static
  229.     {
  230.         if ('' === $sameSite) {
  231.             $sameSite = null;
  232.         } elseif (null !== $sameSite) {
  233.             $sameSite = strtolower($sameSite);
  234.         }
  236.         if (!\in_array($sameSite, [self::SAMESITE_LAX, self::SAMESITE_STRICT, self::SAMESITE_NONE, null], true)) {
  237.             throw new \InvalidArgumentException('The "sameSite" parameter value is not valid.');
  238.         }
  240.         $cookie = clone $this;
  241.         $cookie->sameSite = $sameSite;
  243.         return $cookie;
  244.     }
  246.     /**
  247.      * Creates a cookie copy that is tied to the top-level site in cross-site context.
  248.      */
  249.     public function withPartitioned(bool $partitioned = true): static
  250.     {
  251.         $cookie = clone $this;
  252.         $cookie->partitioned = $partitioned;
  254.         return $cookie;
  255.     }
  257.     /**
  258.      * Returns the cookie as a string.
  259.      */
  260.     public function __toString(): string
  261.     {
  262.         if ($this->isRaw()) {
  263.             $str = $this->getName();
  264.         } else {
  265.             $str = str_replace(self::RESERVED_CHARS_FROM, self::RESERVED_CHARS_TO, $this->getName());
  266.         }
  268.         $str .= '=';
  270.         if ('' === (string) $this->getValue()) {
  271.             $str .= 'deleted; expires='.gmdate('D, d M Y H:i:s T', time() - 31536001).'; Max-Age=0';
  272.         } else {
  273.             $str .= $this->isRaw() ? $this->getValue() : rawurlencode($this->getValue());
  275.             if (0 !== $this->getExpiresTime()) {
  276.                 $str .= '; expires='.gmdate('D, d M Y H:i:s T', $this->getExpiresTime()).'; Max-Age='.$this->getMaxAge();
  277.             }
  278.         }
  280.         if ($this->getPath()) {
  281.             $str .= '; path='.$this->getPath();
  282.         }
  284.         if ($this->getDomain()) {
  285.             $str .= '; domain='.$this->getDomain();
  286.         }
  288.         if ($this->isSecure()) {
  289.             $str .= '; secure';
  290.         }
  292.         if ($this->isHttpOnly()) {
  293.             $str .= '; httponly';
  294.         }
  296.         if (null !== $this->getSameSite()) {
  297.             $str .= '; samesite='.$this->getSameSite();
  298.         }
  300.         if ($this->isPartitioned()) {
  301.             $str .= '; partitioned';
  302.         }
  304.         return $str;
  305.     }
  307.     /**
  308.      * Gets the name of the cookie.
  309.      */
  310.     public function getName(): string
  311.     {
  312.         return $this->name;
  313.     }
  315.     /**
  316.      * Gets the value of the cookie.
  317.      */
  318.     public function getValue(): ?string
  319.     {
  320.         return $this->value;
  321.     }
  323.     /**
  324.      * Gets the domain that the cookie is available to.
  325.      */
  326.     public function getDomain(): ?string
  327.     {
  328.         return $this->domain;
  329.     }
  331.     /**
  332.      * Gets the time the cookie expires.
  333.      */
  334.     public function getExpiresTime(): int
  335.     {
  336.         return $this->expire;
  337.     }
  339.     /**
  340.      * Gets the max-age attribute.
  341.      */
  342.     public function getMaxAge(): int
  343.     {
  344.         $maxAge = $this->expire - time();
  346.         return 0 >= $maxAge ? 0 : $maxAge;
  347.     }
  349.     /**
  350.      * Gets the path on the server in which the cookie will be available on.
  351.      */
  352.     public function getPath(): string
  353.     {
  354.         return $this->path;
  355.     }
  357.     /**
  358.      * Checks whether the cookie should only be transmitted over a secure HTTPS connection from the client.
  359.      */
  360.     public function isSecure(): bool
  361.     {
  362.         return $this->secure ?? $this->secureDefault;
  363.     }
  365.     /**
  366.      * Checks whether the cookie will be made accessible only through the HTTP protocol.
  367.      */
  368.     public function isHttpOnly(): bool
  369.     {
  370.         return $this->httpOnly;
  371.     }
  373.     /**
  374.      * Whether this cookie is about to be cleared.
  375.      */
  376.     public function isCleared(): bool
  377.     {
  378.         return 0 !== $this->expire && $this->expire < time();
  379.     }
  381.     /**
  382.      * Checks if the cookie value should be sent with no url encoding.
  383.      */
  384.     public function isRaw(): bool
  385.     {
  386.         return $this->raw;
  387.     }
  389.     /**
  390.      * Checks whether the cookie should be tied to the top-level site in cross-site context.
  391.      */
  392.     public function isPartitioned(): bool
  393.     {
  394.         return $this->partitioned;
  395.     }
  397.     /**
  398.      * @return self::SAMESITE_*|null
  399.      */
  400.     public function getSameSite(): ?string
  401.     {
  402.         return $this->sameSite;
  403.     }
  405.     /**
  406.      * @param bool $default The default value of the "secure" flag when it is set to null
  407.      */
  408.     public function setSecureDefault(bool $default): void
  409.     {
  410.         $this->secureDefault = $default;
  411.     }
  412. }