<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The SessionHandler class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.session-write-close.html">session_write_close</a></div>
<div class="next" style="text-align: right; float: right;"><a href="sessionhandler.close.html">SessionHandler::close</a></div>
<div class="up"><a href="book.session.html">Sessions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.sessionhandler" class="reference">
<h1 class="title">The SessionHandler class</h1>
<div class="partintro"><p class="verinfo">(PHP 5 >= 5.4.0)</p>
<div class="section" id="sessionhandler.intro">
<h2 class="title">Introduction</h2>
<p class="para">
<strong class="classname">SessionHandler</strong> a special class that can be used to expose
the current internal PHP session save handler by inheritance. There are six methods which
wrap the six internal session save handler callbacks (<em><code class="parameter">open</code></em>, <em><code class="parameter">close</code></em>,
<em><code class="parameter">read</code></em>, <em><code class="parameter">write</code></em>, <em><code class="parameter">destroy</code></em> and <em><code class="parameter">gc</code></em>).
By default, this class will wrap whatever internal save handler is set as as defined by the
<a href="session.configuration.html#ini.session.save-handler" class="link">session.save_handler</a> configuration directive which is usually
<em><code class="parameter">files</code></em> by default.
Other internal session save handlers are provided by PHP extensions such as SQLite (as <em><code class="parameter">sqlite</code></em>),
Memcache (as <em><code class="parameter">memcache</code></em>), and Memcached (as <em><code class="parameter">memcached</code></em>).
</p>
<p class="para">
When a plain instance of <strong class="classname">SessionHandler</strong> is set as the save handler using
<span class="function"><a href="function.session-set-save-handler.html" class="function">session_set_save_handler()</a></span> it will wrap the current save handlers.
A class extending from <strong class="classname">SessionHandler</strong> allows you to override
the methods or intercept or filter them by calls the parent class methods which ultimately wrap
the interal PHP session handlers.
</p>
<p class="para">
This allows you, for example, to intercept the <em><code class="parameter">read</code></em> and <em><code class="parameter">write</code></em>
methods to encrypt/decrypt the session data and then pass the result to and from the parent class.
Alternatively one might chose to entirely override a method like the garbage collection callback
<em><code class="parameter">gc</code></em>.
</p>
<p class="para">
Because the <strong class="classname">SessionHandler</strong> wraps the current internal save handler
methods, the above example of encryption can be applied to any internal save handler without
having to know the internals of the handlers.
</p>
<p class="para">
To use this class, first set the save handler you wish to expose using
<a href="session.configuration.html#ini.session.save-handler" class="link">session.save_handler</a> and then pass an instance of
<strong class="classname">SessionHandler</strong> or one extending it to <span class="function"><a href="function.session-set-save-handler.html" class="function">session_set_save_handler()</a></span>.
</p>
<p class="para">
Please note the callback methods of this class are designed to be called internally by
PHP and are not meant to be called from user-space code. The return values are equally processed internally
by PHP. For more information on the session workflow, please refer <span class="function"><a href="function.session-set-save-handler.html" class="function">session_set_save_handler()</a></span>.
</p>
</div>
<div class="section" id="sessionhandler.synopsis">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass"></div>
<div class="classsynopsisinfo">
<span class="ooclass">
<strong class="classname">SessionHandler</strong>
</span>
<span class="oointerface">implements
<span class="interfacename"><a href="class.sessionhandlerinterface.html" class="interfacename">SessionHandlerInterface</a></span>
</span>
{</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><a href="sessionhandler.close.html" class="methodname">close</a></span>
( <span class="methodparam">void</span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><a href="sessionhandler.destroy.html" class="methodname">destroy</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><a href="sessionhandler.gc.html" class="methodname">gc</a></span>
( <span class="methodparam"><span class="type">int</span> <code class="parameter">$maxlifetime</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><a href="sessionhandler.open.html" class="methodname">open</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$save_path</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">string</span> <span class="methodname"><a href="sessionhandler.read.html" class="methodname">read</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><a href="sessionhandler.write.html" class="methodname">write</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_id</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$session_data</code></span>
)</div>
}</div>
</div>
<div class="section" id="session.notes">
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
This class is designed to expose the current internal PHP session save handler, if you you want to
write your own custom save handlers, please implement the <a href="class.sessionhandlerinterface.html" class="classname">SessionHandlerInterface</a>
interface instead of extending from <strong class="classname">SessionHandler</strong>.
</p>
</div>
</div>
<div class="section" id="sessionhandler.examples">
<div class="example" id="example-4774">
<p><strong>Example #1
Using <strong class="classname">SessionHandler</strong> to add encryption to internal PHP save handlers.
</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">class </span><span style="color: #0000BB">EncryptedSessionHandler </span><span style="color: #007700">extends </span><span style="color: #0000BB">SessionHandler<br /></span><span style="color: #007700">{<br /> private </span><span style="color: #0000BB">$key</span><span style="color: #007700">;<br /><br /> public function </span><span style="color: #0000BB">__construct</span><span style="color: #007700">(</span><span style="color: #0000BB">$key</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">key </span><span style="color: #007700">= </span><span style="color: #0000BB">$key</span><span style="color: #007700">;<br /> }<br /><br /> public function </span><span style="color: #0000BB">read</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$data </span><span style="color: #007700">= </span><span style="color: #0000BB">parent</span><span style="color: #007700">::</span><span style="color: #0000BB">read</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">);<br /><br /> return </span><span style="color: #0000BB">mcrypt_decrypt</span><span style="color: #007700">(</span><span style="color: #0000BB">MCRYPT_3DES</span><span style="color: #007700">, </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">key</span><span style="color: #007700">, </span><span style="color: #0000BB">$data</span><span style="color: #007700">, </span><span style="color: #0000BB">MCRYPT_MODE_ECB</span><span style="color: #007700">);<br /> }<br /><br /> public function </span><span style="color: #0000BB">write</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">, </span><span style="color: #0000BB">$data</span><span style="color: #007700">)<br /> {<br /> </span><span style="color: #0000BB">$data </span><span style="color: #007700">= </span><span style="color: #0000BB">mcrypt_encrypt</span><span style="color: #007700">(</span><span style="color: #0000BB">MCRYPT_3DES</span><span style="color: #007700">, </span><span style="color: #0000BB">$this</span><span style="color: #007700">-></span><span style="color: #0000BB">key</span><span style="color: #007700">, </span><span style="color: #0000BB">$data</span><span style="color: #007700">, </span><span style="color: #0000BB">MCRYPT_MODE_ECB</span><span style="color: #007700">);<br /><br /> return </span><span style="color: #0000BB">parent</span><span style="color: #007700">::</span><span style="color: #0000BB">write</span><span style="color: #007700">(</span><span style="color: #0000BB">$id</span><span style="color: #007700">, </span><span style="color: #0000BB">$data</span><span style="color: #007700">);<br /> }<br />}<br /><br /></span><span style="color: #FF8000">// we'll intercept the native 'files' handler, but will equally work<br />// with other internal native handlers like 'sqlite', 'memcache' or 'memcached'<br />// which are provided by PHP extensions.<br /></span><span style="color: #0000BB">ini_set</span><span style="color: #007700">(</span><span style="color: #DD0000">'session.save_handler'</span><span style="color: #007700">, </span><span style="color: #DD0000">'files'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$handler </span><span style="color: #007700">= new </span><span style="color: #0000BB">EncryptedSessionHandler</span><span style="color: #007700">(</span><span style="color: #DD0000">'mykey'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">session_set_save_handler</span><span style="color: #007700">(</span><span style="color: #0000BB">$handler</span><span style="color: #007700">, </span><span style="color: #0000BB">true</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">session_start</span><span style="color: #007700">();<br /><br /></span><span style="color: #FF8000">// proceed to set and retrieve values by key from $_SESSION</span>
</span>
</code></div>
</div>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Since this class' methods are designed to be called internally by PHP as part of the normal session workflow,
child class calls to parent methods (i.e. the actual internal native handlers) will return <strong><code>FALSE</code></strong> unless
the session has actually been started (either automatically, or by explicit <span class="function"><a href="function.session-start.html" class="function">session_start()</a></span>.
This is important to consider when writing unit tests where the class methods might be invoked manually.
</p>
</p></blockquote>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="sessionhandler.close.html">SessionHandler::close</a> — Close the session</li><li><a href="sessionhandler.destroy.html">SessionHandler::destroy</a> — Destroy a session</li><li><a href="sessionhandler.gc.html">SessionHandler::gc</a> — Cleanup old sessions</li><li><a href="sessionhandler.open.html">SessionHandler::open</a> — Initialize session</li><li><a href="sessionhandler.read.html">SessionHandler::read</a> — Read session data</li><li><a href="sessionhandler.write.html">SessionHandler::write</a> — Write session data</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.session-write-close.html">session_write_close</a></div>
<div class="next" style="text-align: right; float: right;"><a href="sessionhandler.close.html">SessionHandler::close</a></div>
<div class="up"><a href="book.session.html">Sessions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
