mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-07-07 20:09:31 +02:00
152 lines
4.1 KiB
Markdown
152 lines
4.1 KiB
Markdown
title: Cookies
|
|
summary: A set of static methods for manipulating PHP cookies.
|
|
|
|
# Cookies
|
|
## Accessing and Manipulating Cookies
|
|
|
|
Cookies are a mechanism for storing data in the remote browser and thus tracking or identifying return users.
|
|
|
|
SilverStripe uses cookies for remembering users preferences. Application code can modify a users cookies through
|
|
the [Cookie](api:SilverStripe\Control\Cookie) class. This class mostly follows the PHP API.
|
|
|
|
### set
|
|
|
|
Sets the value of cookie with configuration.
|
|
|
|
|
|
```php
|
|
use SilverStripe\Control\Cookie;
|
|
|
|
Cookie::set($name, $value, $expiry = 90, $path = null, $domain = null, $secure = false, $httpOnly = false);
|
|
|
|
// Cookie::set('MyApplicationPreference', 'Yes');
|
|
```
|
|
|
|
### get
|
|
|
|
Returns the value of cookie.
|
|
|
|
|
|
```php
|
|
Cookie::get($name);
|
|
|
|
// Cookie::get('MyApplicationPreference');
|
|
// returns 'Yes'
|
|
```
|
|
|
|
### force_expiry
|
|
|
|
Clears a given cookie.
|
|
|
|
|
|
```php
|
|
Cookie::force_expiry($name, $path = null, $domain = null);
|
|
|
|
// Cookie::force_expiry('MyApplicationPreference')
|
|
```
|
|
|
|
## Cookie_Backend
|
|
|
|
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
|
|
[setcookie](http://www.php.net/manual/en/function.setcookie.php) function.
|
|
|
|
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
|
|
from the browser.
|
|
|
|
|
|
```php
|
|
use SilverStripe\Core\Injector\Injector;
|
|
use SilverStripe\Control\Cookie;
|
|
use SilverStripe\Control\CookieJar;
|
|
|
|
$myCookies = [
|
|
'cookie1' => 'value1',
|
|
];
|
|
|
|
$newBackend = new CookieJar($myCookies);
|
|
|
|
Injector::inst()->registerService($newBackend, 'Cookie_Backend');
|
|
|
|
Cookie::get('cookie1');
|
|
|
|
```
|
|
|
|
### Resetting the Cookie_Backend state
|
|
|
|
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.
|
|
|
|
|
|
```php
|
|
Injector::inst()->unregisterNamedObject('Cookie_Backend');
|
|
|
|
Cookie::get('cookiename'); // will return $_COOKIE['cookiename'] if set
|
|
```
|
|
|
|
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.
|
|
|
|
|
|
```php
|
|
//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');
|
|
```
|
|
|
|
### 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.
|
|
|
|
|
|
```yml
|
|
---
|
|
Name: mycookie
|
|
After: '#cookie'
|
|
---
|
|
SilverStripe\Core\Injector\Injector:
|
|
Cookie_Backend:
|
|
class: MyCookieJar
|
|
```
|
|
|
|
To be a valid backend your class must implement the [Cookie_Backend](api:SilverStripe\Control\Cookie_Backend) interface.
|
|
|
|
## 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:
|
|
|
|
|
|
```php
|
|
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);
|
|
```
|
|
|
|
### Accessing all the cookies at once
|
|
|
|
One can also access all of the cookies in one go using the `Cookie_Backend`
|
|
|
|
|
|
```php
|
|
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
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
* [Cookie](api:SilverStripe\Control\Cookie)
|
|
* [CookieJar](api:SilverStripe\Control\CookieJar)
|
|
* [Cookie_Backend](api:SilverStripe\Control\Cookie_Backend)
|