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

<!-- $Revision$ -->

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler" xmlns:xlink="http://www.w3.org/1999/xlink">

<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>callable</type><parameter>open</parameter></methodparam>

<methodparam><type>callable</type><parameter>close</parameter></methodparam>

<methodparam><type>callable</type><parameter>read</parameter></methodparam>

<methodparam><type>callable</type><parameter>write</parameter></methodparam>

<methodparam><type>callable</type><parameter>destroy</parameter></methodparam>

<methodparam><type>callable</type><parameter>gc</parameter></methodparam>

<methodparam choice="opt"><type>callable</type><parameter>create_sid</parameter></methodparam>

<methodparam choice="opt"><type>callable</type><parameter>validate_sid</parameter></methodparam>

<methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>

</methodsynopsis>

<para>

It is possible to register the following prototype:

</para>

<methodsynopsis>

<type>bool</type><methodname>session_set_save_handler</methodname>

<methodparam><type>object</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, e.g. 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>, and optionally

<interfacename>SessionIdInterface</interfacename> and/or

<interfacename>SessionUpdateTimestampHandlerInterface</interfacename>, such as

<classname>SessionHandler</classname>, to register as the session

handler.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>register_shutdown</parameter></term>

<listitem>

<para>

Register <function>session_write_close</function> as a

<function>register_shutdown_function</function> function.

</para>

</listitem>

</varlistentry>

</variablelist>

or

<variablelist>

<varlistentry>

<term><parameter>open</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>open</replaceable></methodname>

<methodparam><type>string</type><parameter>savePath</parameter></methodparam>

<methodparam><type>string</type><parameter>sessionName</parameter></methodparam>

</methodsynopsis>

</para>

<para>

The open callback 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>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>close</replaceable></methodname>

<void/>

</methodsynopsis>

</para>

<para>

The close callback 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</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>string</type><methodname><replaceable>read</replaceable></methodname>

<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>

</methodsynopsis>

</para>

<para>

The <parameter>read</parameter> callback must always return a session encoded (serialized)

string, or an empty string if there is no data to read.

</para>

<para>

This callback is called internally by PHP when the session starts or

when <function>session_start</function> is called. Before this callback is invoked

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 <varname>$_SESSION</varname> superglobal.

While the data looks similar to <function>serialize</function> please note it is a different format

which is specified in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>write</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>write</replaceable></methodname>

<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>

<methodparam><type>string</type><parameter>data</parameter></methodparam>

</methodsynopsis>

</para>

<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 <varname>$_SESSION</varname> superglobal. The serialization

method used internally 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 callback is invoked when PHP shuts down or explicitly when <function>session_write_close</function>

is called. Note that after executing this function PHP will internally execute 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</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>destroy</replaceable></methodname>

<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>

</methodsynopsis>

</para>

<para>

This callback 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</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>gc</replaceable></methodname>

<methodparam><type>int</type><parameter>lifetime</parameter></methodparam>

</methodsynopsis>

</para>

<para>

The garbage collector callback is invoked internally by PHP periodically in order to

purge old session data. The frequency is controlled 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 callback 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>

<varlistentry>

<term><parameter>create_sid</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>string</type><methodname><replaceable>create_sid</replaceable></methodname>

<void/>

</methodsynopsis>

</para>

<para>

This callback is executed when a new session ID is required. No

parameters are provided, and the return value should be a string that

is a valid session ID for your handler.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>validate_sid</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>

<methodparam><type>string</type><parameter>key</parameter></methodparam>

</methodsynopsis>

</para>

<para>

This callback is executed when a session is to be started, a session ID is supplied

and <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link> is enabled.

The <parameter>key</parameter> is the session ID to validate.

A session ID is valid, if a session with that ID already exists.

The return value should be &true; for success, &false; for failure.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>update_timestamp</parameter></term>

<listitem>

<para>

A callable with the following signature:

<methodsynopsis>

<type>bool</type><methodname><replaceable>update_timestamp</replaceable></methodname>

<methodparam><type>string</type><parameter>key</parameter></methodparam>

<methodparam><type>string</type><parameter>val</parameter></methodparam>

</methodsynopsis>

</para>

<para>

This callback is executed when a session is updated.

<parameter>key</parameter> is the session ID, <parameter>val</parameter> is the session data.

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

Custom session handler: see full code in <classname>SessionHandlerInterface</classname> synopsis.

</title>

<para>

We just show the invocation here, the full example can be

seen in the <classname>SessionHandlerInterface</classname> synopsis linked above.

</para>

<para>

Note we use the OOP prototype with <function>session_set_save_handler</function> and

register the shutdown function using the function's parameter flag. This is generally

advised when registering objects as session save handlers.

</para>

<programlisting role="php">

<![CDATA[

<?php

class MySessionHandler implements SessionHandlerInterface

{

// implement interfaces here

}

$handler = new MySessionHandler();

session_set_save_handler($handler, true);

session_start();

// proceed to set and retrieve values by key from $_SESSION

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<warning>

<para>

The <parameter>write</parameter> and

<parameter>close</parameter> handlers are called after object

destruction and therefore cannot use objects or throw exceptions.

Exceptions are not able to be caught since will not be caught nor will

any exception trace be displayed and the execution will just cease unexpectedly.

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 but the most reliable way is

to register the shutdown function as described above.

</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="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member>

The <link linkend="ini.session.save-handler">session.save_handler</link>

configuration directive

</member>

<member>

The <link linkend="ini.session.serialize-handler">session.serialize_handler</link>

configuration directive.

</member>

<member>The <function>register_shutdown_function</function></member>

<member>The <function>session_register_shutdown</function></member>

<member>

Refer to <link xlink:href="&url.session-save-handler;">save_handler.inc</link>

for a full procedural reference implementation

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

-->