From 0ba16b3425457964475a67bf4bd3ecd565d6df65 Mon Sep 17 00:00:00 2001
From: Daniel Beckham <danbeck@php.net>
Date: Tue, 22 Aug 2000 23:02:46 +0000
Subject: [PATCH] added session_set_save_handler documentation; removed example
 from session intro since the function is now documented

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@30920 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/session.xml | 192 +++++++++++++++++++++++++++---------------
 1 file changed, 124 insertions(+), 68 deletions(-)

diff --git a/functions/session.xml b/functions/session.xml
index 45d7a39403..493a250368 100644
--- a/functions/session.xml
+++ b/functions/session.xml
@@ -132,77 +132,15 @@ To continue, &lt;A HREF="nextpage.php?&lt;?=SID?&gt;"&gt;click here&lt;/A&gt;
      </programlisting>
     </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
@@ -776,6 +714,124 @@ echo "The previous session name was $previous_name&lt;p&gt;";
    </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 = @fopen($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 = @fopen($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(@unlink($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-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
--->
+-->
\ No newline at end of file