Patch persistance2.diff for Documentation problem Bug #60686

Patch version 2012-01-08 17:43 UTC

Obsoleted by patches:

• persistence3.diff, revision 2012-01-09 21:56 UTC

Obsolete patches:

• persistance.diff, revision 2012-01-08 16:58 UTC

• 2012-01-08 17:43 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)
@@ -11,20 +11,29 @@
   &reftitle.description;
   <methodsynopsis>
    <modifier>public</modifier> <type>void</type><methodname>SoapServer::setPersistence</methodname>
-   <methodparam><type>int</type><parameter>mode</parameter></methodparam>
+   <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> 
+   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 <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>
+     <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>
+      <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 <link linkend="language.oop5.magic.sleep">__wakeup</link> and <link linkend="language.oop5.magic.sleep">__sleep</link> magic methods on his
+      or her class object. 
+     </para>  
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -35,13 +44,16 @@
      <term><parameter>mode</parameter></term>
      <listitem>
       <para>
-       One of the <literal>SOAP_PERSISTENCE_XXX</literal> constants.
+       One of the <constant>SOAP_PERSISTENCE_XXX</constant> constants.
       </para>
       <para>
-       <literal>SOAP_PERSISTENCE_REQUEST</literal> - persist the object for the duration of a request.
-      </para>
+       <constant>SOAP_PERSISTENCE_REQUEST</constant> - 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.
+       <constant>SOAP_PERSISTENCE_SESSION</constant> - SoapServer data does persists between requests.
+       This is accomplished by serializing the SoapServer class data into $_SESSION['_bogus_session_name'],
+       because of this <methodname>session_start</methodname> must be called before this persistence mode is set. 
       </para>
      </listitem>
     </varlistentry>
@@ -55,13 +67,59 @@
    &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_PERSISTENCE_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>