documentation/manual/en/module_specs/Zend_Serializer-Introduction.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.serializer.introduction">
   4     <title>Introduction</title>
   5
   6     <para>
   7         <classname>Zend_Serializer</classname> provides an adapter based interface to simply
   8         generate storable representation of <acronym>PHP</acronym> types by different facilities,
   9         and recover.
  10     </para>
  11
  12     <example id="zend.serializer.introduction.example.dynamic">
  13         <title>Using Zend_Serializer dynamic interface</title>
  14
  15         <para>
  16             To instantiate a serializer you should use the factory method with the name of the
  17             adapter:
  18         </para>
  19
  20         <programlisting language="php"><![CDATA[
  21 $serializer = Zend_Serializer::factory('PhpSerialize');
  22 // Now $serializer is an instance of Zend_Serializer_Adapter_AdapterInterface,
  23 // specifically Zend_Serializer_Adapter_PhpSerialize
  24
  25 try {
  26     $serialized = $serializer->serialize($data);
  27     // now $serialized is a string
  28
  29     $unserialized = $serializer->unserialize($serialized);
  30     // now $data == $unserialized
  31 } catch (Zend_Serializer_Exception $e) {
  32     echo $e;
  33 }
  34 ]]></programlisting>
  35     </example>
  36
  37     <para>
  38         The method <methodname>serialize()</methodname> generates a storable string. To regenerate
  39         this serialized data you can simply call the method <methodname>unserialize()</methodname>.
  40     </para>
  41
  42     <para>
  43         Any time an error is encountered serializing or unserializing,
  44         <classname>Zend_Serializer</classname> will throw a
  45         <classname>Zend_Serializer_Exception</classname>.
  46     </para>
  47
  48     <para>
  49         To configure a given serializer adapter, you can optionally add an array or an instance of
  50         <classname>Zend_Config</classname> to the <methodname>factory()</methodname> or to the
  51         <methodname>serialize()</methodname> and <methodname>unserialize()</methodname> methods:
  52     </para>
  53
  54     <programlisting language="php"><![CDATA[
  55 $serializer = Zend_Serializer::factory('Wddx', array(
  56     'comment' => 'serialized by Zend_Serializer',
  57 ));
  58
  59 try {
  60     $serialized = $serializer->serialize(
  61         $data,
  62         array('comment' => 'change comment')
  63     );
  64
  65     $unserialized = $serializer->unserialize(
  66         $serialized,
  67         array(/* options for unserialize */)
  68     );
  69 } catch (Zend_Serializer_Exception $e) {
  70     echo $e;
  71 }
  72 ]]></programlisting>
  73
  74     <para>
  75         Options passed to the <methodname>factory()</methodname> are valid for the instantiated
  76         object. You can change these options using the <methodname>setOption(s)</methodname> method.
  77         To change one or more options only for a single call, pass them as the second argument to
  78         either the <methodname>serialize()</methodname> or <methodname>unserialize()</methodname>
  79         method.
  80     </para>
  81
  82     <example id="zend.serializer.introduction.example.static.php">
  83         <title>Using the Zend_Serializer static interface</title>
  84
  85         <para>
  86             You can register a specific serializer adapter as a default serialization adapter for
  87             use with <classname>Zend_Serializer</classname>. By default, the
  88             <classname>PhpSerialize</classname> adapter will be registered, but you can change this
  89             option using the <methodname>setDefaultAdapter()</methodname> static method.
  90         </para>
  91
  92         <programlisting language="php"><![CDATA[
  93 Zend_Serializer::setDefaultAdapter('PhpSerialize', $options);
  94 // or
  95 $serializer = Zend_Serializer::factory('PhpSerialize', $options);
  96 Zend_Serializer::setDefaultAdapter($serializer);
  97
  98 try {
  99     $serialized   = Zend_Serializer::serialize($data, $options);
 100     $unserialized = Zend_Serializer::unserialize($serialized, $options);
 101 } catch (Zend_Serializer_Exception $e) {
 102     echo $e;
 103 }
 104 ]]></programlisting>
 105     </example>
 106 </sect1>
 107 <!--
 108 vim:se ts=4 sw=4 et:
 109 -->