2014-10-28 07:03:27 +01:00
title: Cookies
summary: A set of static methods for manipulating PHP cookies.
# Cookies
2014-12-15 22:55:36 +01:00
## Accessing and Manipulating Cookies
2014-10-28 07:03:27 +01:00
Cookies are a mechanism for storing data in the remote browser and thus tracking or identifying return users.
2014-11-15 00:58:31 +01:00
2014-10-28 07:03:27 +01:00
SilverStripe uses cookies for remembering users preferences. Application code can modify a users cookies through
2017-07-03 03:22:12 +02:00
the [Cookie ](api:SilverStripe\Control\Cookie ) class. This class mostly follows the PHP API.
2014-10-28 07:03:27 +01:00
2014-12-15 22:55:36 +01:00
### set
2014-10-28 07:03:27 +01:00
Sets the value of cookie with configuration.
2017-08-03 02:51:32 +02:00
```php
2014-10-28 07:03:27 +01:00
Cookie::set($name, $value, $expiry = 90, $path = null, $domain = null, $secure = false, $httpOnly = false);
// Cookie::set('MyApplicationPreference', 'Yes');
2017-08-03 02:51:32 +02:00
```
2014-10-28 07:03:27 +01:00
2014-12-15 22:55:36 +01:00
### get
2014-10-28 07:03:27 +01:00
Returns the value of cookie.
2017-08-03 02:51:32 +02:00
```php
2014-10-28 07:03:27 +01:00
Cookie::get($name);
// Cookie::get('MyApplicationPreference');
// returns 'Yes'
2017-08-03 02:51:32 +02:00
```
2014-10-28 07:03:27 +01:00
2014-12-15 22:55:36 +01:00
### force_expiry
2014-10-28 07:03:27 +01:00
Clears a given cookie.
2017-08-03 02:51:32 +02:00
```php
2014-10-28 07:03:27 +01:00
Cookie::force_expiry($name, $path = null, $domain = null);
// Cookie::force_expiry('MyApplicationPreference')
2017-08-03 02:51:32 +02:00
```
2014-11-15 00:58:31 +01:00
## Cookie_Backend
2017-07-03 03:22:12 +02:00
The [Cookie ](api:SilverStripe\Control\Cookie ) class manipulates and sets cookies using a [Cookie_Backend ](api:SilverStripe\Control\Cookie_Backend ). The backend is in charge of the logic
that fetches, sets and expires cookies. By default we use a [CookieJar ](api:SilverStripe\Control\CookieJar ) backend which uses PHP's
2014-11-15 00:58:31 +01:00
[setcookie ](http://www.php.net/manual/en/function.setcookie.php ) function.
2017-07-03 03:22:12 +02:00
The [CookieJar ](api:SilverStripe\Control\CookieJar ) keeps track of cookies that have been set by the current process as well as those that were received
2014-11-15 00:58:31 +01:00
from the browser.
2017-08-03 02:51:32 +02:00
```php
2014-11-15 00:58:31 +01:00
$myCookies = array(
'cookie1' => 'value1',
);
$newBackend = new CookieJar($myCookies);
Injector::inst()->registerService($newBackend, 'Cookie_Backend');
Cookie::get('cookie1');
2017-08-03 02:51:32 +02:00
```
2014-11-15 00:58:31 +01:00
2014-12-15 22:55:36 +01:00
### Resetting the Cookie_Backend state
2014-11-15 00:58:31 +01:00
Assuming that your application hasn't messed around with the `$_COOKIE` superglobal, you can reset the state of your
`Cookie_Backend` by simply unregistering the `CookieJar` service with `Injector` . Next time you access `Cookie` it'll
create a new service for you using the `$_COOKIE` superglobal.
2017-08-03 02:51:32 +02:00
```php
2014-11-15 00:58:31 +01:00
Injector::inst()->unregisterNamedObject('Cookie_Backend');
Cookie::get('cookiename'); // will return $_COOKIE['cookiename'] if set
2017-08-03 02:51:32 +02:00
```
2014-11-15 00:58:31 +01:00
Alternatively, if you know that the superglobal has been changed (or you aren't sure it hasn't) you can attempt to use
the current `CookieJar` service to tell you what it was like when it was registered.
2017-08-03 02:51:32 +02:00
```php
2014-11-15 00:58:31 +01:00
//store the cookies that were loaded into the `CookieJar`
$recievedCookie = Cookie::get_inst()->getAll(false);
//set a new `CookieJar`
Injector::inst()->registerService(new CookieJar($recievedCookie), 'CookieJar');
2017-08-03 02:51:32 +02:00
```
2014-11-15 00:58:31 +01:00
### Using your own Cookie_Backend
If you need to implement your own Cookie_Backend you can use the injector system to force a different class to be used.
2017-08-03 02:51:32 +02:00
```yml
2014-11-15 00:58:31 +01:00
---
Name: mycookie
After: '#cookie'
---
Injector:
Cookie_Backend:
class: MyCookieJar
2017-08-03 02:51:32 +02:00
```
2014-11-15 00:58:31 +01:00
2017-07-03 03:22:12 +02:00
To be a valid backend your class must implement the [Cookie_Backend ](api:SilverStripe\Control\Cookie_Backend ) interface.
2014-11-15 00:58:31 +01:00
2014-12-15 22:55:36 +01:00
## Advanced Usage
### Sent vs Received Cookies
Sometimes it's useful to be able to tell if a cookie was set by the process (thus will be sent to the browser) or if it
came from the browser as part of the request.
Using the `Cookie_Backend` we can do this like such:
2017-08-03 02:51:32 +02:00
```php
2014-12-15 22:55:36 +01:00
Cookie::set('CookieName', 'CookieVal');
Cookie::get('CookieName'); //gets the cookie as we set it
//will return the cookie as it was when it was sent in the request
Cookie::get('CookieName', false);
2017-08-03 02:51:32 +02:00
```
2014-12-15 22:55:36 +01:00
### Accessing all the cookies at once
One can also access all of the cookies in one go using the `Cookie_Backend`
2017-08-03 02:51:32 +02:00
```php
2014-12-15 22:55:36 +01:00
Cookie::get_inst()->getAll(); //returns all the cookies including ones set during the current process
Cookie::get_inst()->getAll(false); //returns all the cookies in the request
2017-08-03 02:51:32 +02:00
```
2014-11-15 00:58:31 +01:00
2014-10-28 07:03:27 +01:00
## API Documentation
2017-07-03 03:22:12 +02:00
* [Cookie ](api:SilverStripe\Control\Cookie )
* [CookieJar ](api:SilverStripe\Control\CookieJar )
* [Cookie_Backend ](api:SilverStripe\Control\Cookie_Backend )