Cookies management
==================

Cookies are little pieces of information stored locally into the client's browser cookie cache. They are quite useful to store non-sensitive information and ask the browser to recall it (or them) at a later time: a typical example is the storage of some simple data like favourite color, to be requested for each visit in order to dynamically personalize the style sheet, without needing to engage complex preference management with login and sessions.

Obviously, it shouldn't be used to store sensible user data, such as user names and passwords. Indeed, cookies has an important role in sessions management, because they are the preferred method to temporarily store the session ID. For further information about sessions and session management, see section SessionManagement.

------------------------------------
Cookie object and the cookie manager
------------------------------------

PyHP expose the cookie manager module ``pyhp.cookies`` It consists in 3 Python dictionaries:

::

	pyhp.cookies.in
	pyhp.cookies.out
	pyhp.cookies.defaults

managing respectively the input data from requested cookies, the data to be outputted in a cookie and the default settings for cookies created by the ``pyhp.cookies.create()`` method.

With the exception of the ``pyhp.cookies.defaults`` dictionary (explained below), the other two ones shouldn't be directly accessed, as there are dedicated accessory methods such the already mentioned ``create()`` This is because of a single cookie is easily managed as a ``Cookie()`` object.

-----------------
The Cookie object
-----------------


In PyHP, each cookie is represented by a ``Cookie`` object. This class has methods to manage the creation, cancellation and attributes management of each cookie.

You can use the ``create()`` method to create a new cookie with a specified name and automatically add to the outing cookies dictionary, obtaining the new cookie instance. Example:
::

	my_cookie = pyhp.cookies.create('cookie_name')


When you want to delete a cookie, simply use the ``drop()`` method to get it deleted from the browser's cookie cache. It actually works setting a new past date for the specified cookie, in order to make it deleted directly from the browser's cookie management. Example:
::

	c = pyhp.cookies.drop('cookie_name')

In order to retrieve data from a cookie, just use the ``get()`` method. If the specified cookie does not exists, it returns ``None``
::

	c = pyhp.cookies.get('cookie_name')

The ``Cookie`` class either exposes two methods for cookies attributes management: ``get_attr()`` and ``set_attr()`` 

``Cookie.get_attr()`` method retrieves the current setting of the specified attribute name of the cookie we're working on. Assuming x as a valid Cookie:

::

	x = Cookie.get_attr('attr_name')

Complementarily, the ``Cookie.set_attr()`` method sets a specified value to a specified attribute. Assuming x as a valid ``Cookie``
::

	x.set_attr('attr_name', 'attr_value')

Also, it is possible to set more values in a cookie, as in a dictionary, with the ``Cookie['key'] = value`` syntax. Example:
::

	my_cookie['a_key_value'] = 'my value'

This is made possible by the implementation of the Cookie: object in PyHP: it is based on a Python dictionary, serialized before storing in a standard cookie, so you can fill it with the data you desire, structured as you wish.

.. note::
	Since the ``Cookie`` object will be serialized to be stored on a "regular" cookie to be sent to the user's browser, your cookie must have a size smaller than the maximum size defined by the web standards for a cookie. This is actually set to 4KB, so you should avoid storing a lot of data inside them. If you encounter this problem, it is recommended to split data into multiple ones or to consider other forms of data storage and manipulation.

-------
Example
-------
::

    #cookies must be created valid only for /hello.pyhp
    pyhp.cookies.defaults['path'] = '/hello.pyhp'

    #create the cookie
    c = pyhp.cookies.create('cookie_try')
    c.data['my_value'] = 3 + 2

    #cookie should expire in 10 seconds 
    c.set_attr('expires', time.strftime('%a, %d-%b-%Y %H:%M:%S GMT', time.gmtime(time.time()+10)))

    #print the resulting cookie
    print "SETTING COOKIE: %s<br/>" % c


For more examples, see the ''examples'' folder.