php-doc-en/reference/session/functions/session-set-save-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler">
 <refnamediv>
  <refname>session_set_save_handler</refname>
  <refpurpose>Sets user-level session storage functions</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>callback</type><parameter>open</parameter></methodparam>
   <methodparam><type>callback</type><parameter>close</parameter></methodparam>
   <methodparam><type>callback</type><parameter>read</parameter></methodparam>
   <methodparam><type>callback</type><parameter>write</parameter></methodparam>
   <methodparam><type>callback</type><parameter>destroy</parameter></methodparam>
   <methodparam><type>callback</type><parameter>gc</parameter></methodparam>
  </methodsynopsis>
  <para>
   Since PHP 5.4 it is possible to register the following prototype:
  </para>
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>SessionHandlerInterface</type><parameter>sessionhandler</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>true</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_set_save_handler</function> sets the user-level
   session storage functions which are used for storing and
   retrieving data associated with a session.  This is most useful
   when a storage method other than those supplied by PHP sessions
   is preferred.  i.e. Storing the session data in a local database.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   This function has two prototypes.
   <variablelist>
    <varlistentry>
     <term><parameter>sessionhandler</parameter></term>
     <listitem>
      <para>
       An instance of a class implementing
       <interfacename>SessionHandlerInterface</interfacename>, such as
       <classname>SessionHandler</classname>, to register as the session
       handler. Since PHP 5.4 only.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>register_shutdown</parameter></term>
     <listitem>
      <para>
       Register <function>session_register_shutdown</function> as a
       <function>register_shutdown_function</function> function.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   or

   <variablelist>
    <varlistentry>
     <term><parameter>open(string $savePath, string $sessionName)</parameter></term>
     <listitem>
      <para>
       Open function, this works like a constructor in classes and is
       executed when the session is being opened.  It is the first callback
       function executed when the session is started automatically or
       manually with <function>session_start</function>.
       Return value is &true; for success, &false; for failure.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>close()</parameter></term>
     <listitem>
      <para>
       Close function, this works like a destructor in classes and is
       executed after the session write callback has been called. It is also invoked when
       <function>session_write_close</function> is called.
       Return value should be &true; for success, &false; for failure.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>read(string $sessionId)</parameter></term>
     <listitem>
      <para>
       The <parameter>read</parameter> function must always return a session encoded (serialized)
       string, or an empty string if there is no data to read.
      </para>
      <para>
       This callback is automatically called by PHP when the session starts or
       when <function>session_start</function> is called.  Before this function is called
       PHP will invoke the <parameter>open</parameter> callback.
      </para>
      <para>
       The value this callback returns must be in exactly the same serialized format that was originally
       passed for storage to the <parameter>write</parameter> callback.  The value returned will be
       unserialized automatically by PHP and used to populate the $_SESSION superglobal.
       While the data looks similar to <function>serialize</function> please note it is a different format
       which is speficied in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write(string $sessionId, string $data)</parameter></term>
     <listitem>
      <para>
       The <parameter>write</parameter> callback is called when the session needs to be saved and closed. This
       callback receives the current session ID a serialized version the $_SESSION superglobal.  The serialization
       method used by PHP is specified in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.
      </para>
      <para>
       The serialized session data passed to this callback should be stored against the passed session ID. When retrieving
       this data, the <parameter>read</parameter> callback must return the exact value that was originally passed to
       the <parameter>write</parameter> callback.
      </para>
      <para>
       This function is called PHP shuts down or explicitly when <function>session_write_close</function>
       is called.  Note that after executing this function PHP will call the <parameter>close</parameter> callback.
       <note>
        <para>
         The "write" handler is not executed until after the output stream is
         closed.  Thus, output from debugging statements in the "write"
         handler will never be seen in the browser.  If debugging output is
         necessary, it is suggested that the debug output be written to a
         file instead.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>destroy($sessionId)</parameter></term>
     <listitem>
      <para>
       The destroy handler taked one parameter, the session ID. This is executed when
       a session is destroyed with <function>session_destroy</function> or with <function>session_regenerate_id</function> with
       the destroy parameter set to &true;.
       Return value should be &true; for success, &false; for failure.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>gc($lifetime)</parameter></term>
     <listitem>
      <para>
       The garbage collector, this is executed when the session garbage collector
       is executed and takes the max session lifetime in seconds as its only parameter.
       This method is called at random according to the frequency set by
       <link linkend="ini.session.gc-probability">session.gc_probability</link> and <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
       The value of lifetime which is passed to this function can be set in <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link>.
       Return value should be &true; for success, &false; for failure.
      </para>
     </listitem>
    </varlistentry>   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>session_set_save_handler</function> example</title>
    <para>
     The following example provides file based session storage similar to the
     PHP sessions default save handler <parameter>files</parameter>.  This
     example could easily be extended to cover database storage using your
     favorite PHP supported database engine.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
function open($save_path, $session_name)
{
  global $sess_save_path;

  $sess_save_path = $save_path;
  return(true);
}

function close()
{
  return(true);
}

function read($id)
{
  global $sess_save_path;

  $sess_file = "$sess_save_path/sess_$id";
  return (string) @file_get_contents($sess_file);
}

function write($id, $sess_data)
{
  global $sess_save_path;

  $sess_file = "$sess_save_path/sess_$id";
  if ($fp = @fopen($sess_file, "w")) {
    $return = fwrite($fp, $sess_data);
    fclose($fp);
    return $return;
  } else {
    return(false);
  }

}

function destroy($id)
{
  global $sess_save_path;

  $sess_file = "$sess_save_path/sess_$id";
  return(@unlink($sess_file));
}

function gc($maxlifetime)
{
  global $sess_save_path;

  foreach (glob("$sess_save_path/sess_*") as $filename) {
    if (filemtime($filename) + $maxlifetime < time()) {
      @unlink($filename);
    }
  }
  return true;
}

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

session_start();

// proceed to use sessions normally

?>
]]>
    </programlisting>
   </example>
   <example>
    <title>
     <function>session_set_save_handler</function> using
     <classname>SessionHandler</classname>
    </title>
    <programlisting role="php">
<![CDATA[
<?php
class MySessionHandler extends SessionHandler {
  public function open($save_path, $sessionid)
  {
    global $sess_save_path;

    $sess_save_path = $save_path;
    return(true);
  }
  public function close()
  {
    return true;
  }
  public function read($sessionid)
  {
    global $sess_save_path;

    $sess_file = "$sess_save_path/sess_$id";
    return (string) @file_get_contents($sess_file);
  }
  public function write($sessionid, $sessiondata)
  {
    global $sess_save_path;

    $sess_file = "$sess_save_path/sess_$id";
    if ($fp = @fopen($sess_file, "w")) {
      $return = fwrite($fp, $sess_data);
      fclose($fp);
      return $return;
    } else {
      return(false);
    }
  }
  public function destroy($sessionid)
  {
    global $sess_save_path;

    $sess_file = "$sess_save_path/sess_$id";
    return(@unlink($sess_file));
  }
  public function gc($maxlifetime)
  {
    global $sess_save_path;

    foreach (glob("$sess_save_path/sess_*") as $filename) {
      if (filemtime($filename) + $maxlifetime < time()) {
        @unlink($filename);
      }
    }
    return true;
  }
}

$handler = new MySessionHandler();
session_set_save_handler($handler);

session_start();
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    As of PHP 5.0.5 the <parameter>write</parameter> and
    <parameter>close</parameter> handlers are called after object
    destruction and therefore cannot use objects or throw exceptions.
    The object destructors can however use sessions.
   </para>
   <para>
    It is possible to call <function>session_write_close</function> from the
    destructor to solve this chicken and egg problem.
   </para>
  </warning>
  <warning>
   <para>
    Current working directory is changed with some SAPIs if session is
    closed in the script termination. It is possible to close the session
    earlier with <function>session_write_close</function>.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>5.4.0</entry>
      <entry>
       Added <interfacename>SessionHandlerInterface</interfacename> and
       <classname>SessionHandler</classname> for implementing session
       handlers.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     The <link linkend="ini.session.save-handler">session.save_handler</link>
     configuration directive
    </member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

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