Merge pull request #4193 from paulbalandan/alternative-cookie-implementation

Abstraction for cookies and cookie collections

Author: paulbalandan

app/Config/App.php

@@ -3,6 +3,7 @@
 namespace Config;
 
 use CodeIgniter\Config\BaseConfig;
+use DateTimeInterface;
 
 class App extends BaseConfig
 {
@@ -279,14 +280,14 @@ class App extends BaseConfig
 
 	/**
 	 * --------------------------------------------------------------------------
-	 * Cookie HTTP Only
+	 * Cookie HttpOnly
 	 * --------------------------------------------------------------------------
 	 *
 	 * Cookie will only be accessible via HTTP(S) (no JavaScript).
 	 *
 	 * @var boolean
 	 */
-	public $cookieHTTPOnly = false;
+	public $cookieHTTPOnly = true;
 
 	/**
 	 * --------------------------------------------------------------------------
@@ -299,14 +300,50 @@ class App extends BaseConfig
 	 * - Strict
 	 * - ''
 	 *
+	 * Alternatively, you can use the constant names:
+	 * - `Cookie::SAMESITE_NONE`
+	 * - `Cookie::SAMESITE_LAX`
+	 * - `Cookie::SAMESITE_STRICT`
+	 *
 	 * Defaults to `Lax` for compatibility with modern browsers. Setting `''`
-	 * (empty string) means no SameSite attribute will be set on cookies. If
-	 * set to `None`, `$cookieSecure` must also be set.
+	 * (empty string) means default SameSite attribute set by browsers (`Lax`)
+	 * will be set on cookies. If set to `None`, `$cookieSecure` must also be set.
 	 *
-       * @var string 'Lax'|'None'|'Strict'
+	 * @var string
 	 */
 	public $cookieSameSite = 'Lax';
 
+	/**
+	 * --------------------------------------------------------------------------
+	 * Cookie Raw
+	 * --------------------------------------------------------------------------
+	 *
+	 * This flag allows setting a "raw" cookie, i.e., its name and value are
+	 * not URL encoded using `rawurlencode()`.
+	 *
+	 * If this is set to `true`, cookie names should be compliant of RFC 2616's
+	 * list of allowed characters.
+	 *
+	 * @var boolean
+	 *
+	 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes
+	 * @see https://tools.ietf.org/html/rfc2616#section-2.2
+	 */
+	public $cookieRaw = false;
+
+	/**
+	 * --------------------------------------------------------------------------
+	 * Cookie Expires Timestamp
+	 * --------------------------------------------------------------------------
+	 *
+	 * Default expires timestamp for cookies. Setting this to `0` will mean the
+	 * cookie will not have the `Expires` attribute and will behave as a session
+	 * cookie.
+	 *
+	 * @var DateTimeInterface|integer|string
+	 */
+	public $cookieExpires = 0;
+
 	/**
 	 * --------------------------------------------------------------------------
 	 * Reverse Proxy IPs

app/Config/Security.php

@@ -84,9 +84,12 @@ class Security extends BaseConfig
 	 * Allowed values are: None - Lax - Strict - ''.
 	 *
 	 * Defaults to `Lax` as recommended in this link:
+	 *
 	 * @see https://portswigger.net/web-security/csrf/samesite-cookies
 	 *
-       * @var string 'Lax'|'None'|'Strict'
+	 * @var string
+	 *
+	 * @deprecated
 	 */
 	public $samesite = 'Lax';
 }

system/Common.php

@@ -15,6 +15,9 @@
 use CodeIgniter\Database\ConnectionInterface;
 use CodeIgniter\Debug\Timer;
 use CodeIgniter\Files\Exceptions\FileNotFoundException;
+use CodeIgniter\HTTP\Cookie\Cookie;
+use CodeIgniter\HTTP\Cookie\CookieStore;
+use CodeIgniter\HTTP\Exceptions\CookieException;
 use CodeIgniter\HTTP\Exceptions\HTTPException;
 use CodeIgniter\HTTP\RedirectResponse;
 use CodeIgniter\HTTP\RequestInterface;
@@ -226,6 +229,46 @@ function config(string $name, bool $getShared = true)
 	}
 }
 
+if (! function_exists('cookie'))
+{
+	/**
+	 * Simpler way to create a new Cookie instance.
+	 *
+	 * @param string $name    Name of the cookie
+	 * @param string $value   Value of the cookie
+	 * @param array  $options Array of options to be passed to the cookie
+	 *
+	 * @throws CookieException
+	 *
+	 * @return Cookie
+	 */
+	function cookie(string $name, string $value = '', array $options = []): Cookie
+	{
+		return Cookie::create($name, $value, $options);
+	}
+}
+
+if (! function_exists('cookies'))
+{
+	/**
+	 * Fetches the global `CookieStore` instance held by `Response`.
+	 *
+	 * @param Cookie[] $cookies   If `getGlobal` is false, this is passed to CookieStore's constructor
+	 * @param boolean  $getGlobal If false, creates a new instance of CookieStore
+	 *
+	 * @return CookieStore
+	 */
+	function cookies(array $cookies = [], bool $getGlobal = true): CookieStore
+	{
+		if ($getGlobal)
+		{
+			return Services::response()->getCookieStore();
+		}
+
+		return new CookieStore($cookies);
+	}
+}
+
 if (! function_exists('csrf_token'))
 {
 	/**

system/Config/Services.php

@@ -677,7 +677,7 @@ public static function security(App $config = null, bool $getShared = true)
 			return static::getSharedInstance('security', $config);
 		}
 
-		$config = $config ?? config('Security') ?? config('App');
+		$config = $config ?? config('App');
 
 		return new Security($config);
 	}

system/HTTP/Cookie/CloneableCookieInterface.php

@@ -0,0 +1,125 @@
+<?php
+
+/**
+ * This file is part of the CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\HTTP\Cookie;
+
+use DateTimeInterface;
+
+/**
+ * Interface for a fresh Cookie instance with selected attribute(s)
+ * only changed from the original instance.
+ */
+interface CloneableCookieInterface extends CookieInterface
+{
+	/**
+	 * Creates a new Cookie with URL encoding option updated.
+	 *
+	 * @param boolean $raw
+	 *
+	 * @return static
+	 */
+	public function withRaw(bool $raw = true);
+
+	/**
+	 * Creates a new Cookie with a new cookie prefix.
+	 *
+	 * @param string $prefix
+	 *
+	 * @return static
+	 */
+	public function withPrefix(string $prefix = '');
+
+	/**
+	 * Creates a new Cookie with a new name.
+	 *
+	 * @param string $name
+	 *
+	 * @return static
+	 */
+	public function withName(string $name);
+
+	/**
+	 * Creates a new Cookie with new value.
+	 *
+	 * @param string $value
+	 *
+	 * @return static
+	 */
+	public function withValue(string $value);
+
+	/**
+	 * Creates a new Cookie with a new cookie expires time.
+	 *
+	 * @param DateTimeInterface|integer|string $expires
+	 *
+	 * @return static
+	 */
+	public function withExpiresAt($expires = 0);
+
+	/**
+	 * Creates a new Cookie that will expire the cookie from the browser.
+	 *
+	 * @return static
+	 */
+	public function withExpired();
+
+	/**
+	 * Creates a new Cookie that will virtually never expire from the browser.
+	 *
+	 * @return static
+	 */
+	public function withNeverExpiring();
+
+	/**
+	 * Creates a new Cookie with a new domain the cookie is available.
+	 *
+	 * @param string|null $domain
+	 *
+	 * @return static
+	 */
+	public function withDomain(?string $domain);
+
+	/**
+	 * Creates a new Cookie with a new path on the server the cookie is available.
+	 *
+	 * @param string|null $path
+	 *
+	 * @return static
+	 */
+	public function withPath(?string $path);
+
+	/**
+	 * Creates a new Cookie with a new "Secure" attribute.
+	 *
+	 * @param boolean $secure
+	 *
+	 * @return static
+	 */
+	public function withSecure(bool $secure = true);
+
+	/**
+	 * Creates a new Cookie with a new "HttpOnly" attribute
+	 *
+	 * @param boolean $httpOnly
+	 *
+	 * @return static
+	 */
+	public function withHttpOnly(bool $httpOnly = true);
+
+	/**
+	 * Creates a new Cookie with a new "SameSite" attribute.
+	 *
+	 * @param string $sameSite
+	 *
+	 * @return static
+	 */
+	public function withSameSite(string $sameSite);
+}