ongr/cookies-bundle

Cookie model for using cookies as Symfony services

v1.0.0 2016-06-06 08:42 UTC

Requires

• php: >=5.5
• cocur/slugify: 0.2.2
• symfony/symfony: ~2.6|~3.0

Requires (Dev)

• phpunit/phpunit: ~4.4
• satooshi/php-coveralls: ~1.0
• squizlabs/php_codesniffer: ~2.0

MIT

• ONGR team

• symfony
• service
• model
• cookies
• cookie
• ongr

README

Cookies bundle provides Symfony way to handle cookies defining them as services. This allows changing the values of the service and the bundle handles the actual creation and updates of cookies.

Install bundle

To install this bundle add it to composer.

   composer require ongr/cookies-bundle

Then register it in AppKernel.php

   class AppKernel extends Kernel
   {
       public function registerBundles()
       {
           return [
               // ...
               new ONGR\CookiesBundle\ONGRCookiesBundle(),
           ];
       }

       // ...
   }

That's it - the bundle is ready for work.

Working with cookies

How to define a cookie model

ONGR provides cookie model abstraction for working with cookie values in the request and response.

One can define a service:

    parameters:
        project.cookie.foo.name: cookie_foo
        project.cookie.foo.defaults: # Defaults section is optional
            http_only: false
            expires_interval: P5DT4H # 5 days and 4 hours

    services:
        project.cookie.foo:
            class: %ongr_cookie.json.class%
            arguments: [ %project.cookie.foo.name% ]
            calls:
                - [setDefaults, [%project.cookie.foo.defaults%]] # Optional
            tags:
                - { name: ongr_cookie.cookie }

Notice Cookie models' names of a cookie service should not contain dot symbol '.' and must be the same as cookie names that need to be modeled.

Such injected service allows accessing cookie value. If the value has been modified by your code, it will send new value back to the client browser. Manipulating cookie values with ONGR Cookies Bundle is very easy: you need to get the cookie model service and from it you can get the cookie value with getValue() method and set the value with setValue(mixed $value) method.

    class CookieController
    {
        use ContainerAwareTrait;

        public function updateAction()
        {
            /** @var JsonCookie $cookie */
            $cookie = $this->container->get('project.cookie.foo');
            $cookie->setValue(['bar']);
            // Cookie has been marked as dirty and will be updated in the response.
            $cookie->setExpiresTime(2000000000);

            return new JsonResponse();
        }
    }

Default values

Possible setDefaults keys (default values if unspecified):

• domain - string (null)

• path - string ('/')

• http_only - boolean (true)

• secure - boolean (false)

• expires_time - integer (0)

• expires_interval - DateInterval string (null)

These values are used to initialize the cookie model if cookie does not exist in client's browser.

Model types

Currently, there are these pre-configured classes one can use:

• %ongr_cookie.json.class% - one can work with it's value as it was a PHP array. In the background, value is encoded and decoded back using JSON format.

• %ongr_cookie.generic.class% works with plain string data. Other cookie formats can be created by extending this class.

Manually setting cookie

If a cookie with the same name, path and domain is added to the response object, it's value is not overwritten with the changed cookie model data.

Deleting cookie

To remove a cookie from the client browser, use $cookie->setClear(true). All other model values will be ignored.

Components

1. CookieModelListener - event listener responsible for listening for kernel.request and kernel.response events;

2. CookieInjector - service doing the heavy lifting (gets and sets cookies).

3. Cookie Models all implementing CookieInterface via GenericCookie class. Basic cookie fields (domain, expires, etc.) are placed in CookieFieldsTrait trait. Cookie Models are responsible for loading the raw mixed data into an nice PHP object (implementation is customizable and may differ per-model) and returning cookie-izable raw data when the need arises.

How it works?

1. Symfony receives a request. kernel.request event is fired. CookieModelListener is listening.

2. CookieModelListener's onKernelRequest method is called, GetResponseEvent is passed to it. onKernelRequest calls CookieInjector's inject method.

3. CookieInjector iterates through registered Cookie Models, gets raw data for each one and calls a Cookie Model's load method to load the data from the cookie.

4. Now we have a nice cookie-based object available!

5. We do whatever we need to do,

6. Symfony prepares to return a response. kernel.response event is fired. Once again, CookieModelListener is listening.

7. CookieModelListener 's onKernelResponse method is called, FilterResponseEvent is passed to it. onKernelResponse calls CookieInjector's update method.

8. CookieInjector iterates through cookies to be sent to the client, "flattens" them, and then iterates through registered Cookie Models, calling toCookie method to get the data to be stored in the cookie. If Cookie Model's clear property is set to true, the cookie is cleared, otherwise it is saved.

9. Our cookie is either saved and sent to the users' browser or cleared from it.

10. Everyone is happy.

Configuration of Cookie Models

Cookie Models are described as any other Symfony service, with one significant difference: tag ongr_cookie.cookie is used to denote that the service is a Cookie Model. All services tagged with this tag are collected in a separate compiler pass and added to the ongr_cookie.injector service by appending addCookieModel call to its' definition.

Cookie models' names of a cookie service should not contain dot symbol '.' and must be the same as cookie names that need to be modeled.

License

This bundle is under the MIT license. Please, see the complete license in the bundle LICENSE file.