php-doc-en/reference/session/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 a ID or session cookie let's 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,
    and if the <link linkend="ini.session.auto-start">session.auto_start</link> directive is set
    to <parameter>1</parameter>, a session will automatically start the moment PHP sends any output
    to the output buffer.
   </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>
 </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. Unless you are using
   PHP 4.2.0 or later, you need to enable it manually when building PHP.
   Under Unix, pass <link linkend="ini.session.use-trans-sid">
   --enable-trans-sid</link> to configure. If this build
   option and the run-time option
   <literal>session.use_trans_sid</literal> are 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 seperator. 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. As of PHP 5.4.0 you may create session handlers
   using the <classname>SessionHandlerInterface</classname> or extend internal PHP 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>
   Therefor, 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 be
   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 extactly 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 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
-->