php-doc-en/functions/session.sgml

 <reference id="ref.session">
  <title>Session handling functions</title>
  <titleabbrev>Sessions</titleabbrev>
  <partintro>
   <para>
    Session support in PHP consists of a way to preserve certain data
    across subsequent accesses. This enables you to build more
    customized applications and increase the appeal of your web site.
   </para>

   <para>
    A visitor accessing your web site is assigned an 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 register arbitrary numbers of
    variables to be preserved across requests. When a visitor accesses
    your site, PHP will check automatically (if session.auto_start is
    set to 1) or on your request (explicitly through
    <function>session_start</function> or implicitly through
    <function>session_register</function>) whether a specific session
    id has been sent with the request. If this is the case, the prior
    saved environment is recreated.
   </para>

   <para>
    All registered variables are serialized 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>

   <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
    since they are not reliable (clients are not bound to accept
    them), we cannot rely on them. The second method embeds the
    session id directly into URLs.
   </para>

   <para>
    PHP is capable of doing this transparently when compiled with
    <literal>--enable-trans-sid</literal>. If you enable this option,
    relative URIs will be changed to contain the session id
    automatically.  Alternatively, you can use the constant
    <literal>SID</literal> which is defined, if the client did not
    send the appropiate cookie.  <literal>SID</literal> is either of
    the form <literal>session_name=session_id</literal> or is an empty
    string.
   </para>

   <para>
    The following example demonstrates how to register a variable, and
    how to link correctly to another page using SID.
  
   <example>
    <title>Counting the number of hits of a single user</title>
    <programlisting>
&lt;?php

session_register("count");

$count++;

?&gt;

Hello visitor, you have seen this page &lt;? echo $count; ?&gt; times.&lt;p&gt;

&lt;?
# the &lt;?=SID?&gt; is necessary to preserve the session id
# in the case that the user has disabled cookies
?&gt;

 To continue, &lt;A HREF="nextpage.php?&lt;?=SID?&gt;"&gt;click here&lt;/A&gt;
</programlisting></example></para>

   <para>
    To implement database storage you need PHP code and a user level
    function <function>session_set_save_handler</function>. You would
    have to extend the following functions to cover MySQL or another
    database.
   </para>
   <para>
    <example>
     <title>
      Usage of <function>session_set_save_handler</function>
     </title>
     <programlisting role="php">
&lt;?php

function open ($save_path, $session_name) {
    echo "open ($save_path, $session_name)\n";
    return true;
}

function close () {
    echo "close\n";
    return true;
}

function read ($key) {
    echo "write ($key, $val)\n";
    return "foo|i:1;";
}

function write ($key, $val) {
    echo "write ($key, $val)\n";
    return true;
}

function destroy ($key)
    return true;
}

function gc ($maxlifetime) {
    return true;
}

session_set_save_handler ("open", "close", "read", "write", "destroy", "gc");

session_start ();

$foo++;

?>
     </programlisting>
    </example>
   </para> 

   <para>
    Will produce this results:
   </para>

   <para>
    <programlisting>
$ ./php save_handler.php
Content-Type: text/html
Set-cookie: PHPSESSID=f08b925af0ecb52bdd2de97d95cdbe6b

open (/tmp, PHPSESSID)
read (f08b925af0ecb52bdd2de97d95cdbe6b)
write (f08b925af0ecb52bdd2de97d95cdbe6b, foo|i:2;)
close
    </programlisting>
   </para>

   <para>
    The <literal>&lt;?=SID?&gt;</literal> is not necessary, if
    <literal>--enable-trans-sid</literal> was used to compile PHP.
   </para>
   
   <para>
    The session management system supports a number of configuration
    options which you can place in your php.ini file. We will give a
    short overview.

    <itemizedlist>
     <listitem><simpara>
      <literal>session.save_handler</literal> defines the name of the
      handler which is used for storing and retrieving data associated
      with a session.  Defaults to
      <literal>files</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.save_path</literal> defines the argument which
      is passed to the save handler. If you choose the default files
      handler, this is the path where the files are created.  Defaults
      to <literal>/tmp</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.name</literal> specifies the name of the
      session which is used as cookie name. It should only contain
      alphanumeric characters.  Defaults to
      <literal>PHPSESSID</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.auto_start</literal> specifies whether the
      session module start a session automatically on request
      startup. Defaults to <literal>0</literal>
      (disabled).</simpara></listitem>

     <listitem><simpara>
      <literal>session.lifetime</literal> specifies the lifetime of
      the cookie in seconds which is sent to the browser. The value 0
      means "until the browser is closed." Defaults to
      <literal>0</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.serialize_handler</literal> defines the name of
      the handler which is used to serialize/deserialize
      data. Currently, a PHP internal format (name
      <literal>php</literal>) and WDDX is supported (name
      <literal>wddx</literal>). WDDX is only available, if PHP is
      compiled with <link linkend="ref.wddx">WDDX
      support</link>. Defaults to
      <literal>php</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.gc_probability</literal> specifies the
      probability that the gc (garbage collection) routine is started
      on each request in percent. Defaults to
      <literal>1</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.gc_maxlifetime</literal> specifies the number
      of seconds after which data will be seen as 'garbage' and
      cleaned up.</simpara></listitem>

     <listitem><simpara>
      <literal>session.extern_referer_check</literal> determines
      whether session ids referred to by external sites will be
      eliminated. If session ids are propagated using the URL method,
      users not knowing about the impact might publish session
      ids. This can lead to security problems which this check tries
      to defeat. Defaults to
      <literal>0</literal>.</simpara></listitem>

     <listitem><simpara>
      <literal>session.entropy_file</literal> gives a path to an
      external resource (file) which will be used as an additional
      entropy source in the session id creation process. Examples are
      <literal>/dev/random</literal> or
      <literal>/dev/urandom</literal> which are available on many Unix
      systems.</simpara></listitem>

     <listitem><simpara>
      <literal>session.entropy_length</literal> specifies the number
      of bytes which will be read from the file specified
      above. Defaults to <literal>0</literal>
      (disabled).</simpara></listitem>

     <listitem><simpara>
      <literal>session.use_cookies</literal> specifies whether the
      module will use cookies to store the session id on the client
      side. Defaults to <literal>1</literal>
      (enabled).</simpara></listitem>
    
    </itemizedlist>

   <note>
    <para>
     Session handling was added in PHP 4.0.</para>
   </note></para>
  </partintro>

  <refentry id="function.session-start">
   <refnamediv>
    <refname>session_start</refname>
    <refpurpose>Initialize session data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_start</function></funcdef>
     <void>
    </funcsynopsis>
    <simpara>
     <function>session_start</function> creates a session (or resumes
     the current one based on the session id being passed via a GET
     variable or a cookie).</simpara>
    <simpara>
     This function always returns true.</simpara>
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.session-destroy">
   <refnamediv>
    <refname>session_destroy</refname>
    <refpurpose>Destroys all data registered to a session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_destroy</function></funcdef>
     <void>
    </funcsynopsis>
    <simpara>
     <function>session_destroy</function> destroys all of the data
     associated with the current session.</simpara>
    <simpara>
     This function always returns true.</simpara>
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.session-name">
   <refnamediv>
    <refname>session_name</refname>
    <refpurpose>Get and/or set the current session name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>session_name</function></funcdef>
     <paramdef>string <parameter><optional>name</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_name</function> returns the name of the current
     session. If <parameter>name</parameter> is specified, the name of
     the current session is changed to its value.
    <example>
     <title><function>session_name</function> examples</title>
     <programlisting>
$username="foo";

if(isset($username)) {
    session_name($username);
}

echo "Your username is " . session_name();
     </programlisting>
    </example>
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-module-name">
   <refnamediv>
    <refname>session_module_name</refname>
    <refpurpose>Get and/or set the current session module</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>session_module_name</function></funcdef>
     <paramdef>string <parameter><optional>module</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_module_name</function> returns the name of the current
     session module. If <parameter>module</parameter> is specified, that
     module will be used instead.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-save-path">
   <refnamediv>
    <refname>session_save_path</refname>
    <refpurpose>Get and/or set the current session save path</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>session_save_path</function></funcdef>
     <paramdef>string <parameter><optional>path</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_save_path</function> returns the path of the current
     directory used to save session data. If <parameter>path</parameter>
     is specified, the path to which data is saved will be changed.
    <note>
     <para>
      On some operating systems, you may want to specify a path on
      a filesystem that handles lots of small files efficiently. For
      example, on Linux, reiserfs may provide better performance than
      ext2fs.</para>
    </note>
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-id">
   <refnamediv>
    <refname>session_id</refname>
    <refpurpose>Get and/or set the current session id</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>session_id</function></funcdef>
     <paramdef>string <parameter><optional>id</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_id</function> returns the session id for the current
     session. If <parameter>id</parameter> is specified, it will replace
     the current session id.</para>
    <para>
     directory used to save session data. If <parameter>path</parameter>
     is specified, the path to which data is saved will be changed.</para>
    <para>
     The constant <systemitem>SID</systemitem> can also be used to retrieve
     the current name and session id as a string suitable for adding to
     URLs.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-register">
   <refnamediv>
    <refname>session_register</refname>
    <refpurpose>Register a variable with the current session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_register</function></funcdef>
     <paramdef>string <parameter>name</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_register</function> registers the global variable
     named <parameter>name</parameter> with the current session.</para>
    <para>
     This function returns true when the variable is successfully
     registered with the session.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-unregister">
   <refnamediv>
    <refname>session_unregister</refname>
    <refpurpose>Unregister a variable from the current session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_unregister</function></funcdef>
     <paramdef>string <parameter>name</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_unregister</function> unregisters (forgets)
     the global variable named <parameter>name</parameter> from the
     current session.</para>
    <para>
     This function returns true when the variable is successfully
     unregistered from the session.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-is-registered">
   <refnamediv>
    <refname>session_is_registered</refname>
    <refpurpose>Find out if a variable is registered in a session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_is_registered</function></funcdef>
     <paramdef>string <parameter>name</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_is_registered</function> returns true if there
     is a variable with the name <parameter>name</parameter> registered
     in the current session.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-decode">
   <refnamediv>
    <refname>session_decode</refname>
    <refpurpose>Decodes session data from a string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_decode</function></funcdef>
     <paramdef>string <parameter>data</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>session_decode</function> decodes the session data in
     <parameter>data</parameter>, setting variables stored in the
     session.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

  <refentry id="function.session-encode">
   <refnamediv>
    <refname>session_encode</refname>
    <refpurpose>Encodes the current session data as a string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>session_encode</function></funcdef>
     <void>
    </funcsynopsis>
    <para>
     <function>session_encode</function> returns a string with the
     contents of the current session encoded within.
    <note>
     <para>
      This function was added in PHP 4.0.</para>
    </note></para>
   </refsect1>
  </refentry>

 </reference>

<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->