Sessions management
===================

A session is an operation mode that involves the recognition of a single user visiting your web pages and application, allowing a more structured interaction based of the ''browsing session'' identification and temporarily server-side data storing. It will allow you, for example, to implement login mechanisms and state conservation for operations managed by a client-server communication guided through your web application. A typical example could be a publication directory, in which users could browse articles, then login and do operations that requires authentication like publishing another article or modifying and existing item.

---------------------------
How session mechanism works
---------------------------

A session is something that has to be started and then declared. On the server, the session start consists into the generation of an unique ''session ID'' to be associated with the visiting user, the preparation of a data storage section associated with this ID and finally sending this ID to the user's browser using a cookie. After that, every time the user will request a new page, the browser will send back the cookie containing this ''session ID'', allowing the server to recognise that user and act as needed.

PyHP makes this process easier, providing sessions management using the special ``pyhp.session`` object.

-----------------------------------------------
Using sessions with the ``pyhp.session`` object 
-----------------------------------------------

Session fundamental data are the ''session ID'' and the ''session data'', as fundamental operations are its creation, saving and deletion.

You can easily create a new session using the ``start()`` method:
::

	pyhp.session.start()

This will prepare the session storage and generate the ID trasparently, as you does not have to directly manage it. From this moment and onwards, the user's beowsing session will be recognised, and you will be able to store data about its status until the end of session life.

You can put and retrieve session data using the ``pyhp.session.data`` dictionary. Examples:
::

	#storing a piece of data received from a form with a POST request
	pyhp.session.data['logged_username'] = pyhp.post['username']

	#retrieving a piece of data previously saved into the session data dictionary
	print 'Welcome ',pyhp.session.data['logged_username']
	

When you need or want to close current session (e.g. when user logs out), just call the ``wipe()`` method:
::

	pyhp.session.wipe()

Using this command, the session will be reset, the session data will be erased and the session ID will become inconsistent. Since this behaviour (proper for sessions), you should select data that need to remain persistent and save it in a permament storage, such ad into a database. For information about database connections and operations, see the DatabaseInterface section.

This simple description assumes that sessions and session data is automatically saved. This is true, since PyHP saves them at the end of each request manipulation and restore them every time a new request is being server. Anyway you might want to control the exact instant of data saving into your application logic: this is made possible by the ``save()`` method:
::

	pyhp.session.save()


Also, remember that session default lifetime is set to 15 minutes. If users won't send any other requests during this time period, the session ID will become invalid and session will be destroyed.