[PHP-DOC] cvs: phpdoc /en/functions session.xml From: Daniel Beckham (danbeck <email protected>)
Date: 08/22/00

danbeck Tue Aug 22 16:02:46 2000 EDT

  Modified files:
    /phpdoc/en/functions session.xml
  Log:
  added session_set_save_handler documentation; removed example from session intro since the function is now documented
  
Index: phpdoc/en/functions/session.xml
diff -u phpdoc/en/functions/session.xml:1.22 phpdoc/en/functions/session.xml:1.23
--- phpdoc/en/functions/session.xml:1.22 Fri Aug 18 05:13:10 2000
+++ phpdoc/en/functions/session.xml Tue Aug 22 16:02:46 2000
@@ -133,77 +133,15 @@
     </example>
    </para>
    <para>
- To implement database storage you need PHP code and a user level
- function <function>session_set_save_handler</function>. You would
- have to extend the following functions to cover MySQL or another
- database.
- </para>
- <para>
- <example>
- <title>
- Usage of <function>session_set_save_handler</function>
- </title>
- <programlisting role="php">
-&lt;?php
-
-function open ($save_path, $session_name) {
- echo "open ($save_path, $session_name)\n";
- return true;
-}
-
-function close() {
- echo "close\n";
- return true;
-}
-
-function read ($key) {
- echo "read ($key)\n";
- return "foo|i:1;";
-}
-
-function write ($key, $val) {
- echo "write ($key, $val)\n";
- return true;
-}
-
-function destroy ($key) {
- return true;
-}
-
-function gc ($maxlifetime) {
- return true;
-}
-
-session_set_save_handler ("open", "close", "read", "write", "destroy", "gc");
-
-session_start();
-
-$foo++;
-
-?&gt;
- </programlisting>
- </example>
- </para>
- <para>
- Will produce this results:
- </para>
- <para>
- <programlisting>
-$ ./php save_handler.php
-Content-Type: text/html
-Set-cookie: PHPSESSID=f08b925af0ecb52bdd2de97d95cdbe6b
-
-open (/tmp, PHPSESSID)
-read (f08b925af0ecb52bdd2de97d95cdbe6b)
-write (f08b925af0ecb52bdd2de97d95cdbe6b, foo|i:2;)
-close
- </programlisting>
- </para>
- <para>
     The <literal>&lt;?=SID?&gt;</literal> is not necessary, if
     <literal>--enable-trans-sid</literal> was used to compile PHP.
    </para>
    <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>
+ <para>
     The session management system supports a number of configuration
     options which you can place in your php.ini file. We will give a
     short overview.
@@ -776,6 +714,124 @@
    </refsect1>
   </refentry>
 
+ <refentry id="function.session-set-save-handler">
+ <refnamediv>
+ <refname>session_set_save_handler</refname>
+ <refpurpose>
+ Sets user-level session storage functions
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void
+ <function>session_set_save_handler</function>
+ </funcdef>
+ <paramdef>string
+ <parameter>open</parameter></paramdef><paramdef>string
+ <parameter>close</parameter></paramdef><paramdef>string
+ <parameter>read</parameter></paramdef><paramdef>string
+ <parameter>write</parameter></paramdef><paramdef>string
+ <parameter>destroy</parameter></paramdef><paramdef>string
+ <parameter>gc</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <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>
+ <note>
+ <para>
+ You must set the configuration option
+ <parameter>session.save_handler</parameter> to
+ <parameter>user</parameter> in your php.ini file for
+ <function>session_set_save_handler</function> to take effect.
+ </para>
+ </note>
+ <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>
+ <para>
+ <example>
+ <title>
+ <function>session_set_save_handler</function> example
+ </title>
+ <programlisting role="php">
+&lt;?php
+
+function open ($save_path, $session_name) {
+ global $sess_save_path, $sess_session_name;
+
+ $sess_save_path = $save_path;
+ $sess_session_name = $session_name;
+ return(true);
+}
+
+function close() {
+ return(true);
+}
+
+function read ($id) {
+ global $sess_save_path, $sess_session_name;
+
+ $sess_file = "$sess_save_path/sess_$id";
+ if ($fp =  <email protected>($sess_file, "r")) {
+ $sess_data = fread($fp, filesize($sess_file));
+ return($sess_data);
+ } else {
+ return("");
+ }
+
+}
+
+function write ($id, $sess_data) {
+ global $sess_save_path, $sess_session_name;
+
+ $sess_file = "$sess_save_path/sess_$id";
+ if ($fp =  <email protected>($sess_file, "w")) {
+ return(fwrite($fp, $sess_data));
+ } else {
+ return(false);
+ }
+
+}
+
+function destroy ($id) {
+ global $sess_save_path, $sess_session_name;
+
+ $sess_file = "$sess_save_path/sess_$id";
+ return( <email protected>($sess_file));
+}
+
+/*********************************************
+ * WARNING - You will need to implement some *
+ * sort of garbage collection routine here. *
+ *********************************************/
+function gc ($maxlifetime) {
+ return true;
+}
+
+session_set_save_handler ("open", "close", "read", "write", "destroy", "gc");
+
+session_start();
+
+// proceed to use sessions normally
+
+?&gt;
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
  </reference>
 
 <!-- Keep this comment at the end of the file
@@ -793,4 +849,4 @@
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
--->
+-->
\ No newline at end of file