serialization.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- TODO Rewrite to remove usage of "you" and talk about __serialize/_unserialize -->
 <sect1 xml:id="language.oop5.serialization" xmlns="http://docbook.org/ns/docbook">
  <title>Object Serialization</title>
  <title>Serializing objects - objects in sessions</title>

  <para>
   <function>serialize</function> returns a string containing a
   byte-stream representation of any value that can be stored in
   PHP. <function>unserialize</function> can use this string to
   recreate the original variable values. Using serialize to
   save an object will save all variables in an object.  The
   methods in an object will not be saved, only the name of
   the class.
  </para>
  
  <para>
   In order to be able to <function>unserialize</function> an object, the
   class of that object needs to be defined. That is, if you have an object
    of class A and serialize this, you'll
   get a string that refers to class A and contains all values of variables
   contained in it. If you want to be able to unserialize
   this in another file, an object of class A, the
   definition of class A must be present in that file first.
   This can be done for example by storing the class definition of class A
   in an include file and including this file or making use of the
   <function>spl_autoload_register</function> function.
  </para>
  
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
// A.php:
  
  class A {
      public $one = 1;
    
      public function show_one() {
          echo $this->one;
      }
  }
  
// page1.php:

  include "A.php";
  
  $a = new A;
  $s = serialize($a);
  // store $s somewhere where page2.php can find it.
  file_put_contents('store', $s);

// page2.php:
  
  // this is needed for the unserialize to work properly.
  include "A.php";

  $s = file_get_contents('store');
  $a = unserialize($s);

  // now use the function show_one() of the $a object.  
  $a->show_one();
?>
]]>
   </programlisting>
  </informalexample>

  <para>
   It is strongly recommended that if an application serializes objects, for use
   later in the application, that the application includes the class definition
   for that object throughout the application. Not doing so might result in an
   object being unserialized without a class definition, which will result in
   PHP giving the object a class of <classname>__PHP_Incomplete_Class_Name</classname>,
   which has no methods and would render the object useless.
  </para>
  
  <para>
   So if in the example above <varname>$a</varname> became part of a session
   by adding a new key to the <varname>$_SESSION</varname> superglobal array, you should include the
   file <literal>A.php</literal> on all of your pages, not only <filename>page1.php</filename>
   and <filename>page2.php</filename>.
  </para>

  <para>
   Beyond the above advice, note that you can also hook into the serialization
   and unserialization events on an object using the
   <link linkend="object.sleep">__sleep()</link> and
   <link linkend="object.wakeup">__wakeup()</link> methods. Using
   <link linkend="object.sleep">__sleep()</link> also allows you to only
   serialize a subset of the object's properties.
  </para>
 </sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->