php-doc-en/language/oop5/serialization.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <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
// classa.inc:
  
  class A {
      public $one = 1;
    
      public function show_one() {
          echo $this->one;
      }
  }
  
// page1.php:

  include("classa.inc");
  
  $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("classa.inc");

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

  // now use the function show_one() of the $a object.  
  $a->show_one();
?>
]]>
   </programlisting>
  </informalexample>
  
  <para>
   If an application is using sessions and uses 
   <function>session_register</function> to register objects, these objects 
   are serialized automatically at the end of each PHP page, and are 
   unserialized automatically on each of the following pages. This means that 
   these objects can show up on any of the application's pages once they become 
   part of the session. However, regarding the <function>session_register</function>
   function: &removed.php.future;
  </para>
  
  <para>
   It is strongly recommended that if an application serializes objects, for use
   later in the application, that the application include 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 running <literal>session_register("a")</literal>, you should include the
   file <literal>classa.inc</literal> on all of your pages, not only <filename>page1.php</filename>
   and <filename>page2.php</filename>.
  </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
-->