php-doc-en/reference/session/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.14 $ -->
 <reference id="ref.session">
  <title>Session handling functions</title>
  <titleabbrev>Sessions</titleabbrev>
    
  <partintro>
  
   <section id="session.intro">
    &reftitle.intro;
    <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>
     If you are familiar with the session management of PHPLIB, you
     will notice that some concepts are similar to PHP's session
     support.
    </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>
    <note>
     <para>
      Session handling was added in PHP 4.0.
     </para>
    </note>
   </section>
   
   <section id="session.security">
    <title>Sessions and security</title>
    <para>
     Using sessions, does not mean, you can be absolutely sure, that
     the session data can only be viewed by that user. This is important 
     to keep in mind, when storing and displaying sensitive
     information. When storing data into a session, one should always
     ask themselves, what the damage is, when somebody else views that
     information, or how your application is affected when this session
     is actually somebody else.
    </para>
    <para>
     For instance, if somebody else takes a session, can he then post
     a message in a forum, as that user and how big of a problem is
     that? Or perhaps he can view what the original user was thinking
     of ordering, because he gets access to that user's shopping cart.
     Obviously for a flowershop, this is less dramatic, than for a
     pharmacy.
    </para>
    <para>
     Therefore, when dealing with sensitive information, there should
     always be additional methods to decide whether it is a valid
     session. Sessions are not reliable as a secure authentication
     mechanism.
    </para>
    <para>
     Sessions rely on the session ID, meaning one can 'steal' a
     session, by stealing the session ID. This can be made harder, by
     using a cookie specifically a session cookie, but does not in any
     way make it impossible and still relies on the user closing all
     browser windows, to expire the session cookie.
     Besides that, even session cookies can be sniffed on a network or
     logged by a proxyserver.
    </para>
   </section>
   <section id="session.requirements">
    &reftitle.required;
    &no.requirement;
   </section>

   <section id="session.installation">
    &reftitle.install;
    <para>
     Session support is enabled in PHP by default. If you would
     not like to build your PHP with session support, you should
     specify the <option role="configure">--disable-session</option>
     option to configure.
    </para>
   </section>

   &reference.session.ini;

   <section id="session.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   &reference.session.constants;

   <section id="session.examples">
    &reftitle.examples;
    <note>
     <para>
      As of PHP 4.1.0, <varname>$_SESSION</varname> is available as
      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 <literal>global</literal> 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.
     </para>
    </note>

    <para>
     If <link
     linkend="ini.register-globals"><literal>register_globals</literal></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 readablity. With
     <varname>$_SESSION</varname>, there is no need to use
     session_register()/session_unregister()/session_is_registered()
     functions. Session variables are accessible like any other
     variables.
     <example>
      <title>
       Registering a variable with $_SESSION.
      </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 $_SESSION and register_globals 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>
     <example>
      <title>
       Unregistering a variable with register_globals enabled, after
       registering it using $_SESSION.
      </title>
      <programlisting role="php">
<![CDATA[
<?php
session_start();
// With PHP 4.3 and later, you can also use simply use the prior example.
session_unregister('count');
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     If <link
     linkend="ini.register-globals"><literal>register_globals</literal></link>
     is enabled, then all global variables can be registered as session
     variables and the session 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
     session_register() function. You can avoid this by simply setting entries
     in <varname>$_SESSION</varname>.
     <caution>
      <para>
       If you are using
       <varname>$_SESSION</varname>
       and disable <link
       linkend="ini.register-globals"><literal>register_globals</literal></link>,
       do not use <function>session_register</function>,
       <function>session_is_registered</function> and
       <function>session_unregister</function>, if your scripts shall work
       in PHP 4.2 and earlier. You can use these functions in 4.3 and later.
      </para>
      <para>
       If you enable <link
        linkend="ini.register-globals"><literal>register_globals</literal></link>,
        <function>session_unregister</function> should be used since
        session variables are registered as global variables when
        session data is deserialized. Disabling <link
        linkend="ini.register-globals"><literal>register_globals</literal></link>
        is recommended for both security and performance reasons.
      </para>
     </caution>
     <example>
      <title>
       Registering a variable with <link
       linkend="ini.register-globals"><literal>register_globals</literal></link>
       enabled
      </title>
      <programlisting role="php">
<![CDATA[
<?php
if (!session_is_registered('count')) {
    session_register("count");
    $count = 0;
}
else {
    $count++;
}
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     If <link
     linkend="ini.register-globals"><literal>register_globals</literal></link>
     is enabled, then the global variables and the
     <varname>$_SESSION</varname> entries will automatically reference the
     same value for session variables which were registered in prior session
     instances.
    </para>
    <para>
     Additionally, 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 session start (this applies to PHP 4.2 and before
     only).  I.e. a modification to the global variable will not be reflected
     by the <varname>$_SESSION</varname> entry.  This is unlikely to matter in
     practice and has been corrected in PHP 4.3.
    </para>
   </section>
    
   <section 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
     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 if compiled with <link
     linkend="install.configure.enable-trans-sid">
     <literal>--enable-trans-sid</literal></link>. This option is always
     enabled in PHP 4.2 and later.  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 appropriate cookie.  <literal>SID</literal> is
     either of the form <literal>session_name=session_id</literal> or is an
     empty string.
     <note>
      <para>
      The <link linkend="ini.arg_separator.output">arg_separator.output</link>
      &php.ini; directive allows to customize the argument seperator.
      </para>
     </note> 
    </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 role="php">
<![CDATA[
<?php
if (!session_is_registered('count')) {
    session_register('count');
    $count = 1;
}
else {
    $count++;
}
?>

Hello visitor, you have seen this page <?php echo $count; ?> times.<p>;

<?php
# the <?php echo SID?> (<?=SID?> can be used if short tag is enabled) 
# is necessary to preserve the session id
# in the case that the user has disabled cookies
?>

To continue, <A HREF="nextpage.php?<?php echo SID?>">click here</A>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The <literal>&lt;?=SID?&gt;</literal> is not necessary, if
     <link linkend="install.configure.enable-trans-sid">
     <literal>--enable-trans-sid</literal></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 SID, as it would be a security risk to
      leak the SID to a different server.
     </para>
    </note>
   </section>
   
   <section 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>
  </partintro>

&reference.session.functions;

 </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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../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
-->