Patch persistance.diff for Documentation problem Bug #60686

Patch version 2012-01-08 16:58 UTC

Obsoleted by patches:

• persistance2.diff, revision 2012-01-08 17:43 UTC
• persistence3.diff, revision 2012-01-09 21:56 UTC

• 2012-01-08 16:58 UTC [diff to current]

Developer: nveid@silvona.com

Index: reference/soap/soapserver/setpersistence.xml
===================================================================
--- reference/soap/soapserver/setpersistence.xml	(revision 321860)
+++ reference/soap/soapserver/setpersistence.xml	(working copy)
@@ -13,18 +13,22 @@
    <modifier>public</modifier> <type>void</type><methodname>SoapServer::setPersistence</methodname>
    <methodparam><type>int</type><parameter>mode</parameter></methodparam>
   </methodsynopsis>
-  <para>
-   This function allows saving data between requests in a PHP session. It works only
-   with a server that exports functions from a class with <methodname>SoapServer::setClass</methodname>
-   or <methodname>SoapServer::setObject</methodname>.
-  </para>
+  <para> This function allows changing the persistence state of a SoapServer object between
+   requests. This function allows saving data between requests utilizing PHP sessions.  This method
+   only has an affect on a SoapServer after it has exported functions utilizing
+    <methodname>SoapServer::setClass</methodname>. </para>
    <note>
+    <para> The persistence of <constant>SOAP_PERSISTENCE_SESSION</constant> makes only objects of
+    the given class persistent, but not the class static data. In this case, use $this->bar instead
+    of self::$bar. </para>
+   </note>
+  <note>
     <para>
-     The persistence <constant>SOAP_PERSISTENCE_SESSION</constant> makes only
-     objects of the given class persistent, but not the class static data. In
-     this case, use $this->bar instead of self::$bar.
-    </para>
-   </note>
+    <constant>SOAP_PERSISTENCE_SESSION</constant> serializes data on the class object between
+    requests. In order to properly utilize resources(e.g. <classname>PDO</classname>) the programmer
+    should utilize <literal>__wakeup</literal> and <literal>__sleep</literal> magic methods on his
+    or her class object. </para>  
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -38,11 +42,13 @@
        One of the <literal>SOAP_PERSISTENCE_XXX</literal> constants.
       </para>
       <para>
-       <literal>SOAP_PERSISTENCE_REQUEST</literal> - persist the object for the duration of a request.
-      </para>
+       <literal>SOAP_PERSISTENCE_REQUEST</literal> - SoapServer data does not persist between
+       requests. This is the <emphasis role="bold">default</emphasis> behavior of any SoapServer
+       object after setClass is called. </para>
       <para>
-       <literal>SOAP_PERSISTENCE_SESSION</literal> - persist the object for the duration of a session.
-      </para>
+       <literal>SOAP_PERSISTENCE_SESSION</literal> - SoapServer data does persists between requests.
+       This is accomplished by serializing the SoapServer class data into $_SESSION['_bogus_session_name'],
+       because of this session_start() must be called before this persistence mode is set. </para>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -55,13 +61,62 @@
    &return.void;
   </para>
  </refsect1>
+ 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>SoapServer::setPersistence</function>example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
 
+ class MyFirstPersistentSoapServer {
+    private $resource; // (Such as PDO, mysqli, etc..)
+    public $myvar1;
+    public $myvar2;
+    
+    public function __construct() {
+        $this->__wakeup(); // We're calling our wakeup to handle starting our resource
+    }
+
+    public function __wakeup() {
+         $this->resource = CodeToStartOurResourceUp();
+    }
+
+    public function __sleep() {
+        // We make sure to leave out $resource here, so our session data remains persistent
+        // Failure to do so will result in the failure during the unserialization of data
+        // on the next request; thus, our SoapObject would not be persistent across requests.
+        return array('myvar1','myvar2');
+    }
+}
+
+try {
+  session_start();
+  $server = new SoapServer(null, array('uri' => $_SERVER['REQUEST_URI']));
+  $server->setClass('MyFirstPersistentSoapServer');
+  // setPersistence MUST be called after setClass, because setClass's
+  // behavior sets SESSION_PERSISTENT_REQUEST upon enacting the method.
+  $server->setPersistence(SOAP_PERSISTENCE_SESSION);
+  $server->handle();
+} catch(SoapFault $e) {
+    error_log("SOAP ERROR: ". $e->getMessage());
+}
+
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+ 
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><methodname>SoapServer::setClass</methodname></member>
-    <member><methodname>SoapServer::setObject</methodname></member>
    </simplelist>
   </para>
  </refsect1>