<?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>
  <note>
   <para>
    As of PHP 4.1.0, <varname>$_SESSION</varname> is available as a 
    global variable just like <varname>$_POST</varname>,
    <varname>$_GET</varname>, <varname>$_REQUEST</varname> and so on.
    Unlike <varname>$HTTP_SESSION_VARS</varname>,
    <varname>$_SESSION</varname> is always global. Therefore, you do not
    need to use the <link
    linkend="language.variables.scope"><command>global</command></link>
    keyword for <varname>$_SESSION</varname>. Please note that this
    documentation has been changed to use
    <varname>$_SESSION</varname> everywhere. You can substitute
    <varname>$HTTP_SESSION_VARS</varname> for
    <varname>$_SESSION</varname>, if you prefer the former.  Also note
    that you must start your session using <function>session_start</function> 
    before use of <varname>$_SESSION</varname> becomes available.
   </para>
   <para>
    The keys in the <varname>$_SESSION</varname> associative
    array are subject to the
    same limitations as regular variable names in PHP, i.e. they cannot
    start with a number and must start with a letter or underscore.
    For more details see the section on
    <link linkend='language.variables'>variables</link> in this manual.
   </para>
  </note>

  <para>
   If <link
   linkend="ini.register-globals">register_globals</link>
   is disabled, only members of the global associative array
   <varname>$_SESSION</varname> can be registered as session
   variables. The restored session variables will only be available
   in the array <varname>$_SESSION</varname>.
  </para>
  <para>
   Use of <varname>$_SESSION</varname> (or
   <varname>$HTTP_SESSION_VARS</varname> with PHP 4.0.6 or less) is
   recommended for improved security and code readability. With
   <varname>$_SESSION</varname>, there is no need to use the
   <function>session_register</function>,
   <function>session_unregister</function>,
   <function>session_is_registered</function> functions. Session variables
   are accessible like any other variables.
   <example>
    <title>
     Registering a variable with <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
// Use $HTTP_SESSION_VARS with PHP 4.0.6 or less
if (!isset($_SESSION['count'])) {
  $_SESSION['count'] = 0;
} else {
  $_SESSION['count']++;
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>
     Unregistering a variable with <varname>$_SESSION</varname> and
     <link
     linkend="ini.register-globals">register_globals</link> disabled.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
// Use $HTTP_SESSION_VARS with PHP 4.0.6 or less
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>
  <para>
   If <link
   linkend="ini.register-globals">register_globals</link>
   is enabled, then each global variable can be registered as session
   variable. Upon a restart of a session, these variables will be restored
   to corresponding global variables. Since PHP must know which global
   variables are registered as session variables, users need to register
   variables with <function>session_register</function> function.
   You can avoid this by simply setting entries in
   <varname>$_SESSION</varname>.
   <caution>
    <para>
     Before PHP 4.3.0, if you are using <varname>$_SESSION</varname> and you
     have disabled <link linkend="ini.register-globals">register_globals</link>,
     don't use <function>session_register</function>,
     <function>session_is_registered</function> or
     <function>session_unregister</function>.
      Disabling <link
      linkend="ini.register-globals">register_globals</link>
      is recommended for both security and performance reasons.
    </para>
   </caution>
  </para>
  <para>
   If <link
   linkend="ini.register-globals">register_globals</link>
   is enabled, then the global variables and the
   <varname>$_SESSION</varname> entries will automatically reference the
   same values which were registered in the prior session instance.
   However, if the variable is registered by <varname>$_SESSION</varname>
   then the global variable is available since the next request.
  </para>
  <para>
   There is a defect in PHP 4.2.3 and earlier.  If you register a new
   session variable by using <function>session_register</function>, the
   entry in the global scope and the <varname>$_SESSION</varname> entry will
   not reference the same value until the next
   <function>session_start</function>.  I.e. a modification to the newly
   registered global variable will not be reflected by the
   <varname>$_SESSION</varname> entry.  This has been corrected in PHP 4.3.0.
  </para>
 </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.
  </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
-->