silverstripe-framework/src/Control/CookieJar.php

184 lines
6.6 KiB
PHP
Raw Normal View History

NEW Cookie_Backend for managing cookie state I've decoupled `Cookie` from the actual act of setting and getting cookies. Currently there are a few limitations to how Cookie works that this change mitigates: 0. `Cookie` currently changes the super global `$_COOKIE` when setting to make the state of an application a bit more managable, but this is bad because we shouldn't be modifying super globals 0. One can't actually change the `$cookie_class` once the `Cookie::$inst` has been instantiated 0. One can't test cookies as there is no class that holds the state of the cookies (it's just held in the super global which is reset as part of `Director::test()` 0. One can't tell the origin of a cookie (eg: did the application set it and it needs to be sent, or did we receive it from the browser?) 0. `time()` was used, so testing was made difficult 0. There was no way to get all the cookies at once (without accessing the super global) Todos are on the phpdoc and I'd like to write some tests for the backend as well as update the docs (if there are any) around cookies. DOCS Adding `Cookie` docs Explains basic usage of `Cookie` as well as how the `Cookie_Backend` controls the setting and getting of cookies and manages state of sent vs received cookies Fixing `Cookie` usage `Cookie` is being used inconsistently with the API throughout framework. Either by not using `force_expiry` to expire cookies or setting them to null and then expiring them (which is redundant). NEW `Director::test()` takes `Cookie_Backend` rather than `array` for `$cookies` param
2014-05-04 15:34:58 +02:00
<?php
namespace SilverStripe\Control;
use SilverStripe\ORM\FieldType\DBDatetime;
use LogicException;
NEW Cookie_Backend for managing cookie state I've decoupled `Cookie` from the actual act of setting and getting cookies. Currently there are a few limitations to how Cookie works that this change mitigates: 0. `Cookie` currently changes the super global `$_COOKIE` when setting to make the state of an application a bit more managable, but this is bad because we shouldn't be modifying super globals 0. One can't actually change the `$cookie_class` once the `Cookie::$inst` has been instantiated 0. One can't test cookies as there is no class that holds the state of the cookies (it's just held in the super global which is reset as part of `Director::test()` 0. One can't tell the origin of a cookie (eg: did the application set it and it needs to be sent, or did we receive it from the browser?) 0. `time()` was used, so testing was made difficult 0. There was no way to get all the cookies at once (without accessing the super global) Todos are on the phpdoc and I'd like to write some tests for the backend as well as update the docs (if there are any) around cookies. DOCS Adding `Cookie` docs Explains basic usage of `Cookie` as well as how the `Cookie_Backend` controls the setting and getting of cookies and manages state of sent vs received cookies Fixing `Cookie` usage `Cookie` is being used inconsistently with the API throughout framework. Either by not using `force_expiry` to expire cookies or setting them to null and then expiring them (which is redundant). NEW `Director::test()` takes `Cookie_Backend` rather than `array` for `$cookies` param
2014-05-04 15:34:58 +02:00
/**
* A default backend for the setting and getting of cookies
*
* This backend allows one to better test Cookie setting and separate cookie
NEW Cookie_Backend for managing cookie state I've decoupled `Cookie` from the actual act of setting and getting cookies. Currently there are a few limitations to how Cookie works that this change mitigates: 0. `Cookie` currently changes the super global `$_COOKIE` when setting to make the state of an application a bit more managable, but this is bad because we shouldn't be modifying super globals 0. One can't actually change the `$cookie_class` once the `Cookie::$inst` has been instantiated 0. One can't test cookies as there is no class that holds the state of the cookies (it's just held in the super global which is reset as part of `Director::test()` 0. One can't tell the origin of a cookie (eg: did the application set it and it needs to be sent, or did we receive it from the browser?) 0. `time()` was used, so testing was made difficult 0. There was no way to get all the cookies at once (without accessing the super global) Todos are on the phpdoc and I'd like to write some tests for the backend as well as update the docs (if there are any) around cookies. DOCS Adding `Cookie` docs Explains basic usage of `Cookie` as well as how the `Cookie_Backend` controls the setting and getting of cookies and manages state of sent vs received cookies Fixing `Cookie` usage `Cookie` is being used inconsistently with the API throughout framework. Either by not using `force_expiry` to expire cookies or setting them to null and then expiring them (which is redundant). NEW `Director::test()` takes `Cookie_Backend` rather than `array` for `$cookies` param
2014-05-04 15:34:58 +02:00
* handling from the core
*
* @todo Create a config array for defaults (eg: httpOnly, secure, path, domain, expiry)
* @todo A getter for cookies that haven't been sent to the browser yet
* @todo Tests / a way to set the state without hacking with $_COOKIE
* @todo Store the meta information around cookie setting (path, domain, secure, etc)
*/
2016-11-29 00:31:16 +01:00
class CookieJar implements Cookie_Backend
{
/**
* Hold the cookies that were existing at time of instantiation (ie: The ones
* sent to PHP by the browser)
*
* @var array Existing cookies sent by the browser
*/
protected $existing = [];
2016-11-29 00:31:16 +01:00
/**
* Hold the current cookies (ie: a mix of those that were sent to us and we
* have set without the ones we've cleared)
*
* @var array The state of cookies once we've sent the response
*/
protected $current = [];
2016-11-29 00:31:16 +01:00
/**
* Hold any NEW cookies that were set by the application and will be sent
* in the next response
*
* @var array New cookies set by the application
*/
protected $new = [];
2016-11-29 00:31:16 +01:00
/**
* When creating the backend we want to store the existing cookies in our
* "existing" array. This allows us to distinguish between cookies we received
* or we set ourselves (and didn't get from the browser)
*
* @param array $cookies The existing cookies to load into the cookie jar.
* Omit this to default to $_COOKIE
*/
public function __construct($cookies = [])
2016-11-29 00:31:16 +01:00
{
$this->current = $this->existing = func_num_args()
? ($cookies ?: []) // Convert empty values to blank arrays
2016-11-29 00:31:16 +01:00
: $_COOKIE;
}
/**
* Set a cookie
*
* @param string $name The name of the cookie
* @param string $value The value for the cookie to hold
* @param float $expiry The number of days until expiry; 0 indicates a cookie valid for the current session
2016-11-29 00:31:16 +01:00
* @param string $path The path to save the cookie on (falls back to site base)
* @param string $domain The domain to make the cookie available on
* @param boolean $secure Can the cookie only be sent over SSL?
* @param boolean $httpOnly Prevent the cookie being accessible by JS
*/
public function set($name, $value, $expiry = 90, $path = null, $domain = null, $secure = false, $httpOnly = true)
{
//are we setting or clearing a cookie? false values are reserved for clearing cookies (see PHP manual)
$clear = false;
if ($value === false || $value === '' || $expiry < 0) {
$clear = true;
$value = false;
}
//expiry === 0 is a special case where we set a cookie for the current user session
if ($expiry !== 0) {
//don't do the maths if we are clearing
$expiry = $clear ? -1 : DBDatetime::now()->getTimestamp() + (86400 * $expiry);
2016-11-29 00:31:16 +01:00
}
//set the path up
$path = $path ? $path : Director::baseURL();
//send the cookie
$this->outputCookie($name, $value, $expiry, $path, $domain, $secure, $httpOnly);
//keep our variables in check
if ($clear) {
unset($this->new[$name], $this->current[$name]);
} else {
$this->new[$name] = $this->current[$name] = $value;
}
}
/**
* Get the cookie value by name
*
* Cookie names are normalised to work around PHP's behaviour of replacing incoming variable name . with _
*
* @param string $name The name of the cookie to get
* @param boolean $includeUnsent Include cookies we've yet to send when fetching values
*
* @return string|null The cookie value or null if unset
*/
public function get($name, $includeUnsent = true)
{
$cookies = $includeUnsent ? $this->current : $this->existing;
if (isset($cookies[$name])) {
return $cookies[$name];
}
//Normalise cookie names by replacing '.' with '_'
$safeName = str_replace('.', '_', $name);
if (isset($cookies[$safeName])) {
return $cookies[$safeName];
}
return null;
}
/**
* Get all the cookies
*
* @param boolean $includeUnsent Include cookies we've yet to send
* @return array All the cookies
*/
public function getAll($includeUnsent = true)
{
return $includeUnsent ? $this->current : $this->existing;
}
/**
* Force the expiry of a cookie by name
*
* @param string $name The name of the cookie to expire
* @param string $path The path to save the cookie on (falls back to site base)
* @param string $domain The domain to make the cookie available on
* @param boolean $secure Can the cookie only be sent over SSL?
* @param boolean $httpOnly Prevent the cookie being accessible by JS
*/
public function forceExpiry($name, $path = null, $domain = null, $secure = false, $httpOnly = true)
{
$this->set($name, false, -1, $path, $domain, $secure, $httpOnly);
}
/**
* The function that actually sets the cookie using PHP
*
* @see http://uk3.php.net/manual/en/function.setcookie.php
*
* @param string $name The name of the cookie
* @param string|array $value The value for the cookie to hold
* @param int $expiry A Unix timestamp indicating when the cookie expires; 0 means it will expire at the end of the session
2016-11-29 00:31:16 +01:00
* @param string $path The path to save the cookie on (falls back to site base)
* @param string $domain The domain to make the cookie available on
* @param boolean $secure Can the cookie only be sent over SSL?
* @param boolean $httpOnly Prevent the cookie being accessible by JS
* @return boolean If the cookie was set or not; doesn't mean it's accepted by the browser
*/
protected function outputCookie(
$name,
$value,
$expiry = 90,
$path = null,
$domain = null,
$secure = false,
$httpOnly = true
) {
// if headers aren't sent, we can set the cookie
if (!headers_sent($file, $line)) {
return setcookie($name, $value, $expiry, $path, $domain, $secure, $httpOnly);
}
2017-02-22 04:14:53 +01:00
if (Cookie::config()->uninherited('report_errors')) {
2016-11-29 00:31:16 +01:00
throw new LogicException(
"Cookie '$name' can't be set. The site started outputting content at line $line in $file"
);
}
return false;
}
NEW Cookie_Backend for managing cookie state I've decoupled `Cookie` from the actual act of setting and getting cookies. Currently there are a few limitations to how Cookie works that this change mitigates: 0. `Cookie` currently changes the super global `$_COOKIE` when setting to make the state of an application a bit more managable, but this is bad because we shouldn't be modifying super globals 0. One can't actually change the `$cookie_class` once the `Cookie::$inst` has been instantiated 0. One can't test cookies as there is no class that holds the state of the cookies (it's just held in the super global which is reset as part of `Director::test()` 0. One can't tell the origin of a cookie (eg: did the application set it and it needs to be sent, or did we receive it from the browser?) 0. `time()` was used, so testing was made difficult 0. There was no way to get all the cookies at once (without accessing the super global) Todos are on the phpdoc and I'd like to write some tests for the backend as well as update the docs (if there are any) around cookies. DOCS Adding `Cookie` docs Explains basic usage of `Cookie` as well as how the `Cookie_Backend` controls the setting and getting of cookies and manages state of sent vs received cookies Fixing `Cookie` usage `Cookie` is being used inconsistently with the API throughout framework. Either by not using `force_expiry` to expire cookies or setting them to null and then expiring them (which is redundant). NEW `Director::test()` takes `Cookie_Backend` rather than `array` for `$cookies` param
2014-05-04 15:34:58 +02:00
}