documentation/manual/en/tutorials/multiuser-sessions.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="learning.multiuser.sessions">
   4     <title>Managing User Sessions In ZF</title>
   5
   6     <sect2 id="learning.multiuser.sessions.intro">
   7         <title>Introduction to Sessions</title>
   8
   9         <para>
  10             The success of the web is deeply rooted in the protocol that drives the web:
  11             <acronym>HTTP</acronym>. <acronym>HTTP</acronym> over TCP is by its very nature
  12             stateless, which means that inherently the web is also stateless. While this very aspect
  13             is one of the dominating factors for why the web has become such a popular medium, it
  14             also causes an interesting problem for developers that want to use the web as an
  15             application platform.
  16         </para>
  17
  18         <para>
  19             The act of interacting with a web application is typically defined by the sum
  20             of all requests sent to a web server. Since there can be many consumers being served
  21             simultaneously, the application must decide which requests belong to which consumer.
  22             These requests are typically known as a "session".
  23         </para>
  24
  25         <para>
  26             In <acronym>PHP</acronym>, the session problem is solved by the session extension which
  27             utilizes some state tracking, typically cookies, and some form of local storage which is
  28             exposed via the $_SESSION superglobal. In Zend Framework, the component
  29             <classname>Zend_Session</classname> adds value to the <acronym>PHP</acronym> session
  30             extension making it easier to use and depend on inside object-oriented applications.
  31         </para>
  32     </sect2>
  33
  34     <sect2 id="learning.multiuser.sessions.basic-usage">
  35         <title>Basic Usage of Zend_Session</title>
  36
  37         <para>
  38             The <classname>Zend_Session</classname> component is both a session manager as well as
  39             an <acronym>API</acronym> for storing data into a session object for long-term
  40             persistence. The <classname>Zend_Session</classname> <acronym>API</acronym> is for
  41             managing the options and behavior of a session, like options, starting and stopping a
  42             session, whereas <classname>Zend_Session_Namespace</classname> is the actual object used
  43             to store data.
  44         </para>
  45
  46         <para>
  47             While its generally good practice to start a session inside a bootstrap process, this
  48             is generally not necessary as all sessions will be automatically started upon the first
  49             creation of a <classname>Zend_Session_Namespace</classname> object.
  50         </para>
  51
  52         <para>
  53             <classname>Zend_Application</classname> is capable of configuring
  54             <classname>Zend_Session</classname> for you as part of the
  55             <classname>Zend_Application_Resource</classname> system. To use this, assuming your
  56             project uses <classname>Zend_Application</classname> to bootstrap, you would add the
  57             following code to your application.ini file:
  58         </para>
  59
  60         <programlisting language="php"><![CDATA[
  61 resources.session.save_path = APPLICATION_PATH "/../data/session"
  62 resources.session.use_only_cookies = true
  63 resources.session.remember_me_seconds = 864000
  64 ]]></programlisting>
  65
  66         <para>
  67             As you can see, the options passed in are the same options that you'd expect to find
  68             in the ext/session extension in <acronym>PHP</acronym>. Those options setup the path
  69             to the session files where data will be stored within the project. Since
  70             <acronym>INI</acronym> files can additionally use constants, the above will use the
  71             APPLICATION_PATH constant and relatively point to a data session directory.
  72         </para>
  73
  74         <para>
  75             Most Zend Framework components that use sessions need nothing more to use
  76             <classname>Zend_Session</classname>. At this point, you an either use a component that
  77             consumes <classname>Zend_Session</classname>, or start storing your own data inside a
  78             session with <classname>Zend_Session_Namespace</classname>.
  79         </para>
  80
  81         <para>
  82             <classname>Zend_Session_Namespace</classname> is a simple class that proxies data via an
  83             easy to use <acronym>API</acronym> into the <classname>Zend_Session</classname> managed
  84             $_SESSION superglobal. The reason it is called
  85             <classname>Zend_Session_Namespace</classname> is that it effectively namespaces the data
  86             inside $_SESSION, thus allowing multiple components and objects to safely store and
  87             retrieve data. In the following code, we'll explore how to build a simple session
  88             incrementing counter, starting at 1000 and resetting itself after 1999.
  89         </para>
  90
  91         <programlisting language="php"><![CDATA[
  92 $mysession = new Zend_Session_Namespace('mysession');
  93
  94 if (!isset($mysession->counter)) {
  95     $mysession->counter = 1000;
  96 } else {
  97     $mysession->counter++;
  98 }
  99
 100 if ($mysession->counter > 1999) {
 101     unset($mysession->counter);
 102 }
 103 ]]></programlisting>
 104
 105         <para>
 106             As you can see above, the session namespace object uses the magic __get, __set,
 107             __isset, and __unset to allow you to seamlessly and fluently interact with the session.
 108             The information stored in the above example is stored at
 109             $_SESSION['mysession']['counter'].
 110         </para>
 111     </sect2>
 112
 113     <sect2 id="learning.multiuser.sessions.advanced-usage">
 114         <title>Advanced Usage of Zend_Session</title>
 115
 116         <para>
 117             Additionally, if you wanted to use the DbTable
 118             save handler for <classname>Zend_Session</classname>, you'd add the following code to
 119             your application.ini:
 120         </para>
 121
 122         <programlisting language="php"><![CDATA[
 123 resources.session.saveHandler.class = "Zend_Session_SaveHandler_DbTable"
 124 resources.session.saveHandler.options.name = "session"
 125 resources.session.saveHandler.options.primary.session_id = "session_id"
 126 resources.session.saveHandler.options.primary.save_path = "save_path"
 127 resources.session.saveHandler.options.primary.name = "name"
 128 resources.session.saveHandler.options.primaryAssignment.sessionId = "sessionId"
 129 resources.session.saveHandler.options.primaryAssignment.sessionSavePath = "sessionSavePath"
 130 resources.session.saveHandler.options.primaryAssignment.sessionName = "sessionName"
 131 resources.session.saveHandler.options.modifiedColumn = "modified"
 132 resources.session.saveHandler.options.dataColumn = "session_data"
 133 resources.session.saveHandler.options.lifetimeColumn = "lifetime"
 134 ]]></programlisting>
 135     </sect2>
 136 </sect1>