examples.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<appendix xml:id="session.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id="session.examples.basic">
  <title>Basic usage</title>
   <para>
    Sessions are a simple way to store data for individual users against a unique session ID.
    This can be used to persist state information between page requests.  Session IDs are normally
    sent to the browser via session cookies and the ID is used to retrieve existing session data.
    The absence of an ID or session cookie lets PHP know to create a new session, and generate a new
    session ID.
   </para>
   <para>
    Sessions follow a simple workflow.  When a session is started, PHP will either retrieve an
    existing session using the ID passed (usually from a session cookie) or if no session is passed
    it will create a new session.  PHP will populate the <varname>$_SESSION</varname> superglobal
    with any session data after the session has started.  When PHP shuts down, it will automatically
    take the contents of the <varname>$_SESSION</varname> superglobal, serialize it, and send it
    for storage using the session save handler.
   </para>
   <para>
    By default, PHP uses the internal <parameter>files</parameter> save handler which
    is set by <link linkend="ini.session.save-handler">session.save_handler</link>.
    This saves session data on the server at the location specified by the
    <link linkend="ini.session.save-path">session.save_path</link> configuration directive.
   </para>
   <para>
    Sessions can be started manually using the <function>session_start</function> function.
    If the <link linkend="ini.session.auto-start">session.auto_start</link> directive is set
    to <parameter>1</parameter>, a session will automatically start on request startup.
   </para>
   <para>
    Sessions normally shutdown automatically when PHP is finished executing a script, but can be
    manually shutdown using the <function>session_write_close</function> function.
   </para>
  <para>
   <example>
    <title>
     Registering a variable with <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
if (!isset($_SESSION['count'])) {
  $_SESSION['count'] = 0;
} else {
  $_SESSION['count']++;
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>
     Unregistering a variable with <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
unset($_SESSION['count']);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <caution>
    <para>
     Do NOT unset the whole <varname>$_SESSION</varname> with
     <literal>unset($_SESSION)</literal> as this will disable the
     registering of session variables through the
     <varname>$_SESSION</varname> superglobal.
    </para>
   </caution>
  </para>
  <warning>
   <para>
    You can't use references in session variables as there is no feasible way
    to restore a reference to another variable.
   </para>
  </warning>
  <note>
   <para>
    File based sessions (the default in PHP) lock the session file once a
    session is opened via <function>session_start</function> or implicitly via
    <link linkend="ini.session.auto-start">session.auto_start</link>. Once
    locked, no other script can access the same session file until it has been
    closed by the first script terminating or calling
    <function>session_write_close</function>.
   </para>
   <para>
    This is most likely to be an issue on Web sites that use AJAX heavily and
    have multiple concurrent requests. The easiest way to deal with it is to
    call <function>session_write_close</function> as soon as any required
    changes to the session have been made, preferably early in the script.
    Alternatively, a different session backend that does support concurrency
    could be used.
   </para>
  </note>
 </section>

 <section xml:id="session.idpassing">
  <title>Passing the Session ID</title>
  <para>
   There are two methods to propagate a session id:
   <itemizedlist>
    <listitem>
     <simpara>
      Cookies
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      URL parameter
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   The session module supports both methods. Cookies are optimal, but
   because they are not always available, we also provide an alternative
   way.  The second method embeds the session id directly into URLs.
  </para>
  <para>
   PHP is capable of transforming links transparently. If the run-time
   option <literal>session.use_trans_sid</literal> is enabled, relative
   URIs will be changed to contain the session id automatically.
   <note>
    <para>
    The <link linkend="ini.arg-separator.output">arg_separator.output</link>
    &php.ini; directive allows to customize the argument separator. For full
    XHTML conformance, specify &amp;amp; there.
    </para>
   </note>
  </para>
  <para>
   Alternatively, you can use the constant <constant>SID</constant> which is
   defined if the session started.  If the client did not send an appropriate session
   cookie, it has the form <literal>session_name=session_id</literal>.
   Otherwise, it expands to an empty string. Thus, you can embed it
   unconditionally into URLs.
  </para>
  <para>
   The following example demonstrates how to register a variable, and
   how to link correctly to another page using <constant>SID</constant>.
   <example>
    <title>Counting the number of hits of a single user</title>
    <programlisting role="php">
<![CDATA[
<?php

session_start();

if (empty($_SESSION['count'])) {
   $_SESSION['count'] = 1;
} else {
   $_SESSION['count']++;
}
?>

<p>
Hello visitor, you have seen this page <?php echo $_SESSION['count']; ?> times.
</p>

<p>
To continue, <a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">click
here</a>.
</p>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   The <function>htmlspecialchars</function> may be used when printing the <constant>SID</constant>
   in order to prevent XSS related attacks.
  </para>
  <para>
   Printing the <constant>SID</constant>, like shown above, is not necessary if
   <link linkend="ini.session.use-trans-sid">
   --enable-trans-sid</link> was used to compile PHP.
  </para>
  <note>
   <para>
    Non-relative URLs are assumed to point to external sites and
    hence don't append the <constant>SID</constant>, as it would be a security risk to
    leak the <constant>SID</constant> to a different server.
   </para>
  </note>
 </section>

 <section xml:id="session.customhandler">
  <title>Custom Session Handlers</title>
  <para>
   To implement database storage, or any other storage method, you
   will need to use <function>session_set_save_handler</function> to
   create a set of user-level storage functions. A session handlers may be created
   using the <classname>SessionHandlerInterface</classname> or extending PHP's internal handlers by inheriting
   from <classname>SessionHandler</classname>.
  </para>
  <para>
   The callbacks specified in <function>session_set_save_handler</function> are methods
   called by PHP during the life-cycle of a session: <parameter>open</parameter>, <parameter>read</parameter>,
   <parameter>write</parameter> and <parameter>close</parameter> and for the housekeeping tasks:
   <parameter>destroy</parameter> for deleting a session and <parameter>gc</parameter> for periodic garbage
   collection.
  </para>
  <para>
   Therefore, PHP always requires session save handlers. The default is usually the
   internal 'files' save handler. A custom save handler can be set using
   <function>session_set_save_handler</function>. Alternative internal save handlers are also
   provided by PHP extensions, such as <parameter>sqlite</parameter>,
   <parameter>memcache</parameter> and <parameter>memcached</parameter> and can be set with
   <link linkend="ini.session.save-handler">session.save_handler</link>.
  </para>
  <para>
   When the session starts, PHP will internally call the <parameter>open</parameter> handler followed by the
   <parameter>read</parameter> callback which should return an encoded string exactly as it was originally
   passed for storage. Once the <parameter>read</parameter> callback returns the encoded string, PHP will
   decode it and then populate the resulting array into the <varname>$_SESSION</varname> superglobal.
  </para>
  <para>
   When PHP shuts down (or when <function>session_write_close</function> is called),
   PHP will internally encode the <varname>$_SESSION</varname> superglobal and pass this
   along with the session ID to the <parameter>write</parameter> callback.
   After the <parameter>write</parameter> callback has finished, PHP will internally invoke the
   <parameter>close</parameter> callback handler.
  </para>
  <para>
   When a session is specifically destroyed, PHP will call the <parameter>destroy</parameter> handler with
   the session ID.
  </para>
 <para>
   PHP will call the <parameter>gc</parameter> callback from time to time to
   expire any session records according to the set max lifetime of a session.
   This routine should delete all records from persistent storage which were
   last accessed longer than the <parameter>$lifetime</parameter>.
 </para>
 </section>
</appendix>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->