[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/reference/session/_sessionhandler/close.xml_sessionhandler
From: Karma_Dordrak <drak () php ! net>
Date: 2012-02-28 13:33:52
Message-ID: svn-drak-1330436032-323627-1177816832 () svn ! php ! net
[Download RAW message or body]
drak Tue, 28 Feb 2012 13:33:52 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=323627
Log:
[sessions] Updated specific details about how to correctly implement SessionHandler \
and added references to relevant ini settings and functions.
Changed paths:
U phpdoc/en/trunk/reference/session/sessionhandler/close.xml
U phpdoc/en/trunk/reference/session/sessionhandler/destroy.xml
U phpdoc/en/trunk/reference/session/sessionhandler/gc.xml
U phpdoc/en/trunk/reference/session/sessionhandler/open.xml
U phpdoc/en/trunk/reference/session/sessionhandler/read.xml
U phpdoc/en/trunk/reference/session/sessionhandler/write.xml
U phpdoc/en/trunk/reference/session/sessionhandler.xml
["svn-diffs-323627.txt" (text/x-diff)]
Modified: phpdoc/en/trunk/reference/session/sessionhandler/close.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler/close.xml 2012-02-28 13:32:20 \
UTC (rev 323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler/close.xml 2012-02-28 13:33:52 \
UTC (rev 323627) @@ -14,21 +14,23 @@
<void />
</methodsynopsis>
<para>
- Closes the current session. This function is automaticaly executed when
- closing the session, or explicitly via <function>session_write_close</function>.
+ Closes the current session. This method is automaticaly executed internally by \
PHP when + closing the session, or explicitly via \
<function>session_write_close</function> (which + first calls the \
<function>SessionHandler::write</function>). </para>
<para>
This method wraps the internal PHP save handler defined in the
<link linkend="ini.session.save-handler">session.save_handler</link> ini setting \
that was set
- before this handler was set by <function>session_set_save_handler</function>.
+ before this handler was activated by \
<function>session_set_save_handler</function>. </para>
<para>
- If this class is extended by inheritiance, calling the parent \
<parameter>open</parameter> method will invoke the
- wrapper for this method and therefor invoke the associated internal callback. \
This allows this method to be + If this class is extended by inheritiance, calling \
the parent <parameter>close</parameter> method will invoke the + wrapper for this \
method and therefor invoke the associated internal callback. This allows the method \
to be overidden and or intercepted.
</para>
<para>
- For more information on what this method is expected to do, please refer to the \
documetation at <function>SessionHandlerInterface::close</function>. + For more \
information on what this method is expected to do, please refer to the documentation \
at + <function>SessionHandlerInterface::close</function>.
</para>
</refsect1>
@@ -45,7 +47,6 @@
</para>
</refsect1>
-
</refentry>
<!-- Keep this comment at the end of the file
Modified: phpdoc/en/trunk/reference/session/sessionhandler/destroy.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler/destroy.xml 2012-02-28 13:32:20 \
UTC (rev 323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler/destroy.xml 2012-02-28 13:33:52 \
UTC (rev 323627) @@ -14,8 +14,9 @@
<methodparam><type>string</type><parameter>session_id</parameter></methodparam>
</methodsynopsis>
<para>
- Destroys a session. Called by <function>session_regenerate_id</function>,
- <function>session_destroy</function> and when <function>session_decode</function> \
fails. + Destroys a session. Called by internally by PHP with \
<function>session_regenerate_id</function> (assuming + the \
<parameter>$destory</parameter> is set to &true;, by \
<function>session_destroy</function> or when + <function>session_decode</function> \
fails. </para>
<para>
This method wraps the internal PHP save handler defined in the
@@ -23,8 +24,14 @@
before this handler was set by <function>session_set_save_handler</function>.
</para>
<para>
- For more information on what this method is expected to do, please refer to the \
documetation at <function>SessionHandlerInterface::destroy</function>. + If this \
class is extended by inheritiance, calling the parent <parameter>destroy</parameter> \
method will invoke the + wrapper for this method and therefor invoke the associated \
internal callback. This allows this method to be + overidden and or intercepted \
and filtered. </para>
+ <para>
+ For more information on what this method is expected to do, please refer to the \
documentation + at <function>SessionHandlerInterface::destroy</function>.
+ </para>
</refsect1>
<refsect1 role="parameters">
Modified: phpdoc/en/trunk/reference/session/sessionhandler/gc.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler/gc.xml 2012-02-28 13:32:20 UTC \
(rev 323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler/gc.xml 2012-02-28 13:33:52 UTC \
(rev 323627) @@ -14,9 +14,11 @@
<methodparam><type>int</type><parameter>maxlifetime</parameter></methodparam>
</methodsynopsis>
<para>
- Cleans up expired sessions. Called by <function>session_start</function>,
- based on <link linkend="ini.session.gc-divisor">session.gc_divisor</link> and
- <link linkend="ini.session.gc-probability">session.gc_probability</link> \
settings. + Cleans up expired sessions. Called randomly by PHP internally when a \
sessio starts or when + <function>session_start</function> is invoked. The \
frequency this is called is + based on the <link \
linkend="ini.session.gc-divisor">session.gc_divisor</link> and + <link \
linkend="ini.session.gc-probability">session.gc_probability</link> configuration + \
directives. </para>
<para>
This method wraps the internal PHP save handler defined in the
@@ -24,8 +26,14 @@
before this handler was set by <function>session_set_save_handler</function>.
</para>
<para>
- For more information on what this method is expected to do, please refer to the \
documetation at <function>SessionHandlerInterface::gc</function>. + If this class \
is extended by inheritiance, calling the parent <parameter>open</parameter> method \
will invoke the + wrapper for this method and therefor invoke the associated \
internal callback. This allows this method to be + overidden and or intercepted \
and filtered. </para>
+ <para>
+ For more information on what this method is expected to do, please refer to the \
documentation at + <function>SessionHandlerInterface::gc</function>.
+ </para>
</refsect1>
<refsect1 role="parameters">
Modified: phpdoc/en/trunk/reference/session/sessionhandler/open.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler/open.xml 2012-02-28 13:32:20 UTC \
(rev 323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler/open.xml 2012-02-28 13:33:52 UTC \
(rev 323627) @@ -15,8 +15,8 @@
<methodparam><type>string</type><parameter>session_id</parameter></methodparam>
</methodsynopsis>
<para>
- Re-initialize existing session, or creates a new one. Called from
- <function>session_start</function>.
+ Create new session, or re-initialize existing session. Called internally by PHP \
when + a session starts either automatically or when \
<function>session_start</function> is invoked. </para>
<para>
This method wraps the internal PHP save handler defined in the
@@ -29,7 +29,8 @@
overidden and or intercepted and filtered.
</para>
<para>
- For more information on what this method is expected to do, please refer to the \
documetation at <function>SessionHandlerInterface::open</function>. + For more \
information on what this method is expected to do, please refer to the documentation \
at + <function>SessionHandlerInterface::open</function>.
</para>
</refsect1>
@@ -62,7 +63,19 @@
</para>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member>
+ The <link linkend="ini.session.auto-start">session.auto-start</link>
+ configuration directive.
+ </member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
Modified: phpdoc/en/trunk/reference/session/sessionhandler/read.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler/read.xml 2012-02-28 13:32:20 UTC \
(rev 323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler/read.xml 2012-02-28 13:33:52 UTC \
(rev 323627) @@ -14,8 +14,10 @@
<methodparam><type>string</type><parameter>session_id</parameter></methodparam>
</methodsynopsis>
<para>
- Reads the session data from the session storage, and returns the results.
- Called right after <function>session_start</function>.
+ Reads the session data from the session storage, and returns the result back to \
PHP for internal processing. + This method is called automatically by PHP when a \
session is started (either automatically or explicity + with \
<function>session_start</function> and is preceeded by an internal call to the + \
<function>SessionHandler::open</function>. </para>
<para>
This method wraps the internal PHP save handler defined in the
@@ -24,12 +26,13 @@
</para>
<para>
If this class is extended by inheritiance, calling the parent \
<parameter>read</parameter> method will invoke the
- wrapper for this method and therefor invoke the associated internal callback. \
This allows this method to be + wrapper for this method and therefor invoke the \
associated internal callback. This allows the method to be overidden and or \
intercepted and filtered (for example, decrypting <parameter>$data</parameter> value \
returned by the parent <parameter>read</parameter> method). </para>
<para>
- For more information on what this method is expected to do, please refer to the \
documetation at <function>SessionHandlerInterface::read</function>. + For more \
information on what this method is expected to do, please refer to the documentation \
at + <function>SessionHandlerInterface::read</function>.
</para>
</refsect1>
@@ -50,11 +53,23 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
- Always returns string of the read data. If nothing was read returns empty string.
+ Returns an encoded string of the read data. If nothing was read, it must return \
an empty string. </para>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member>
+ The <link linkend="ini.session.serialize-handler">session.serialize_handler</link>
+ configuration directive.
+ </member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
Modified: phpdoc/en/trunk/reference/session/sessionhandler/write.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler/write.xml 2012-02-28 13:32:20 \
UTC (rev 323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler/write.xml 2012-02-28 13:33:52 \
UTC (rev 323627) @@ -15,8 +15,9 @@
<methodparam><type>string</type><parameter>session_data</parameter></methodparam>
</methodsynopsis>
<para>
- Writes the session data to the session storage. Called by
- <function>session_write_close</function>, when \
<function>session_register_shutdown</function> fails, and during request shutdown. + \
Writes the session data to the session storage. Called by normal PHP shutdown, by + \
<function>session_write_close</function>, or when \
<function>session_register_shutdown</function> fails. + PHP will call \
<function>SessionHandler::close</function> immediately after this method returns. \
</para> <para>
This method wraps the internal PHP save handler defined in the
@@ -30,7 +31,8 @@
before sending it to the parent <parameter>write</parameter> method).
</para>
<para>
- For more information on what this method is expected to do, please refer to the \
documetation at <function>SessionHandlerInterface::write</function>. + For more \
information on what this method is expected to do, please refer to the documentation \
+ at <function>SessionHandlerInterface::write</function>. </para>
</refsect1>
@@ -50,7 +52,8 @@
<term><parameter>session_data</parameter></term>
<listitem>
<para>
- The (<function>session_encode</function>d) session data.
+ The encoded session data. This data is the result of the PHP internally \
encoding the <varname>$_SESSION</varname> superglobal to a serialized + string \
and passing it as this parameter. Please note sessions use an alternative \
serialization method. </para>
</listitem>
</varlistentry>
@@ -64,7 +67,19 @@
</para>
</refsect1>
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member>
+ The <link linkend="ini.session.serialize-handler">session.serialize_handler</link>
+ configuration directive.
+ </member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
Modified: phpdoc/en/trunk/reference/session/sessionhandler.xml
===================================================================
--- phpdoc/en/trunk/reference/session/sessionhandler.xml 2012-02-28 13:32:20 UTC (rev \
323626)
+++ phpdoc/en/trunk/reference/session/sessionhandler.xml 2012-02-28 13:33:52 UTC (rev \
323627) @@ -12,29 +12,44 @@
<section xml:id="sessionhandler.intro">
&reftitle.intro;
<para>
- <classname>SessionHandler</classname> a special class that can be used to extend
- the current internal PHP session save handler by using inheritance. There are \
six methods which
- wrap the six session save handler callbacks. By default PHP uses the \
<parameter>files</parameter>
- save handler as defined by <link \
linkend="ini.session.save-handler">session.save_handler</link>.
- Others are provided by PHP extensions such as SQLite (as \
<parameter>sqlite</parameter>), + <classname>SessionHandler</classname> 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 (<parameter>open</parameter>, <parameter>close</parameter>, + \
<parameter>read</parameter>, <parameter>write</parameter>, \
<parameter>destroy</parameter> and <parameter>gc</parameter>). + By default, this \
class will wrap whatever internal save handler is set as as defined by the + <link \
linkend="ini.session.save-handler">session.save_handler</link> configuration \
directive which is usually + <parameter>files</parameter> by default.
+ Other internal session save hadlers are provided by PHP extensions such as \
SQLite (as <parameter>sqlite</parameter>),
Memcache (as <parameter>memcache</parameter>), and Memcached (as \
<parameter>Memcached</parameter>). </para>
<para>
- This class can be extended, and it's methods overridden by inheritance including
- the ability to call the parent class methods. This allows one for example, to \
intercept the
- <parameter>read</parameter> and <parameter>write</parameter> methods to \
encrypt/decrypt the
- session data and then pass the result to and from the parent class.
+ When a plain instance of <classname>SessionHandler</classname> is set as the \
save handler using + <function>session_set_save_handler</function> it will wrap \
the current save handlers. + A class extending from \
<classname>SessionHandler</classname> 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. </para>
<para>
+ This allows you, for example, to intercept the <parameter>read</parameter> and \
<parameter>write</parameter> + 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 + \
<parameter>gc</parameter>. + </para>
+ <para>
Because the <classname>SessionHandler</classname> 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.
</para>
<para>
- To use this class, pass an instance of this class or one extending it
- to <function>session_set_save_handler</function>. This will cause which ever
- native (internal) session handler in use to be wrapped by that instance.
+ To use this class, first set the save handler you wish to expose using
+ <link linkend="ini.session.save-handler">session.save_handler</link> and then \
pass an instance of + <classname>SessionHandler</classname> or one extending it to \
<function>session_set_save_handler</function>. </para>
+ <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 <function>session_set_save_handler</function>. + \
</para> </section>
<!-- }}} -->
@@ -63,6 +78,17 @@
<!-- }}} -->
</section>
+
+ <section xml:id="session.notes">
+ <warning>
+ <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 \
<classname>SessionHandlerInterface</classname> + interface instead of extending \
from <classname>SessionHandler</classname>. + </para>
+ </warning>
+ </section>
+
<section xml:id="sessionhandler.examples">
<example>
<title>
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic