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

<book xml:id="book.session" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <?phpdoc extension-membership="bundled" ?>
 <title>Session Handling</title>
 <titleabbrev>Sessions</titleabbrev>

 <!-- {{{ preface -->
 <preface xml:id="intro.session">
  &reftitle.intro;
  <para>
   Session support in PHP consists of a way to preserve certain data
   across subsequent accesses. 
  </para>
  <para>
   A visitor accessing your web site is assigned a unique id, the
   so-called session id. This is either stored in a cookie on the
   user side or is propagated in the URL.
  </para>
  <para>
   The session support allows you to store data between requests in the
   <varname>$_SESSION</varname> superglobal array. When a visitor accesses
   your site, PHP will check automatically (if <link linkend="ini.session.auto-start">session.auto_start</link>
   is set to 1) or on your request (explicitly through
   <function>session_start</function>) whether a specific session
   id has been sent with the request. If this is the case, the prior
   saved environment is recreated.
  </para>
  <caution>
   <para>
    If you turn on <link linkend="ini.session.auto-start">
    session.auto_start</link> then the only way to put objects
    into your sessions is to load its class definition using
    <link linkend="ini.auto-prepend-file">auto_prepend_file</link>
    in which you load the class definition else you will have to
    <function>serialize</function> your object
    and <function>unserialize</function> it
    afterwards.
   </para>
  </caution>
  <para>
   <varname>$_SESSION</varname> (and all registered variables) are serialized
   internally by PHP using the serialization handler specified by the
   <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting,
   after the request finishes.  Registered variables which are undefined are
   marked as being not defined.  On subsequent accesses, these are not defined
   by the session module unless the user defines them later. 
  </para>
  <warning>
   <para>
    Because session data is serialized, <type>resource</type> variables cannot
    be stored in the session.
   </para>
   <para>
     Serialize handlers (<literal>php</literal>
     and <literal>php_binary</literal>) inherit register_globals
     limitations. Therefore, numeric index or string index contains
     special characters (<literal>|</literal>
     and <literal>!</literal>) cannot be used. Using these will end up
     with errors at script shutdown. <literal>php_serialize</literal>
     does not have such limitations.
   </para>
  </warning>
  <note>
   <para>
    Please note when working with sessions that a record of a session
    is not created until a variable has been registered by adding a new
    key to the <varname>$_SESSION</varname> superglobal array. This
    holds true regardless of if a session has been started using the
    <function>session_start</function> function.
   </para>
  </note>
 </preface>
 <!-- }}} -->

 &reference.session.setup;
 &reference.session.constants;
 &reference.session.examples;
 &reference.session.upload-progress;
 &reference.session.security;
 &reference.session.reference;
 &reference.session.sessionhandler;
 &reference.session.sessionhandlerinterface;
 &reference.session.sessionidinterface;
 &reference.session.sessionupdatetimestamphandlerinterface;

</book>

<!-- 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
-->

