repo_zf1/documentation/manual/en/module_specs/Zend_Serializer-Adapter.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.serializer.adapter">
    <title>Zend_Serializer_Adapter</title>
    
    <para>
        <classname>Zend_Serializer</classname> adapters create a bridge for different methods of
        serializing with very little effort.
    </para>

    <para>
        Every adapter has different pros and cons. In some cases, not every PHP datatype (e.g.,
        objects) can be converted to a string representation. In most such cases, the type will be
        converted to a similar type that is serializable -- as an example, PHP objects will often be
        cast to arrays.  If this fails, a <classname>Zend_Serializer_Exception</classname> will be
        thrown.
    </para>

    <para>
        Below is a list of available adapters.
    </para>

    <sect2 id="zend.serializer.adapter.phpserialize">
        <title>Zend_Serializer_Adapter_PhpSerialize</title>

        <para>
            This adapter uses the built-in <methodname>un/serialize</methodname> PHP functions, and
            is a good default adapter choice.
        </para>

        <para>
            There are no configurable options for this adapter.
        </para>
    </sect2>

    <sect2 id="zend.serializer.adapter.igbinary">
        <title>Zend_Serializer_Adapter_Igbinary</title>

        <para>
            <ulink url="http://opensource.dynamoid.com">Igbinary</ulink> is Open Source Software
            released by Sulake Dynamoid Oy. It's a drop-in replacement for the standard PHP
            serializer. Instead of time and space consuming textual representation, igbinary stores
            PHP data structures in a compact binary form. Savings are significant when using
            memcached or similar memory based storages for serialized data.
        </para>

        <para>
            You need the igbinary PHP extension installed on your system in order to use this
            adapter.
        </para>

        <para>
            There adapter takes no configuration options.
        </para>
    </sect2>

    <sect2 id="zend.serializer.adapter.wddx">
        <title>Zend_Serializer_Adapter_Wddx</title>

        <para>
            <ulink url="http://wikipedia.org/wiki/WDDX">WDDX</ulink> (Web Distributed Data eXchange)
            is a programming-language-, platform-, and transport-neutral data interchange mechanism
            for passing data between different environments and different computers.
        </para>

        <para>
            The adapter simply uses the <ulink url="http://php.net/manual/book.wddx.php">wddx_*()</ulink>
            PHP functions. Please read the php manual to determine how you may enable them in your
            PHP installation.
        </para>

        <para>
            Additionally, the <ulink
                url="http://php.net/manual/book.simplexml.php">SimpleXML</ulink> PHP extension is
            used to check if a returned <constant>NULL</constant> value from
            <methodname>wddx_unserialize()</methodname> is based on a serialized
            <constant>NULL</constant> or on invalid data.
        </para>

        <para>
            Available options include:
        </para>

        <table>
            <title>Zend_Serializer_Adapter_Wddx Options</title>

            <tgroup cols="4">
                 <thead>
                      <row>
                          <entry>Option</entry>

                          <entry>Data Type</entry>

                          <entry>Default Value</entry>

                          <entry>Description</entry>
                    </row>
                 </thead>

                 <tbody>
                      <row>
                          <entry><emphasis>comment</emphasis></entry>

                          <entry><type>string</type></entry>

                          <entry></entry>

                          <entry>
                            An optional comment that appears in the packet header. 
                          </entry>
                      </row>
                  </tbody>
             </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.serializer.adapter.json">
        <title>Zend_Serializer_Adapter_Json</title>

        <para>
            The <acronym>JSON</acronym> adapter provides a bridge to the
            <classname>Zend_Json</classname> component and/or ext/json. Please read the <link
                linkend= "zend.json.introduction">Zend_Json documentation</link> for further
            information.
        </para>

        <para>
            Available options include:
        </para>

        <table>
            <title>Zend_Serializer_Adapter_Json Options</title>

            <tgroup cols="4">
                 <thead>
                      <row>
                        <entry>Option</entry>

                        <entry>Data Type</entry>

                        <entry>Default Value</entry>

                        <entry>Description</entry>
                    </row>
                 </thead>

                 <tbody>
                      <row>
                          <entry><emphasis>cycleCheck</emphasis></entry>

                          <entry><type>boolean</type></entry>

                          <entry>false</entry>

                          <entry>
                               See <xref linkend= "zend.json.advanced.objects1"/>
                          </entry>
                      </row>

                      <row>
                          <entry><emphasis>objectDecodeType</emphasis></entry>

                          <entry><type>Zend_Json::TYPE_*</type></entry>

                          <entry>Zend_Json::TYPE_ARRAY</entry>

                          <entry>
                               See <xref linkend= "zend.json.advanced.objects1"/>
                          </entry>
                      </row>

                      <row>
                          <entry><emphasis>enableJsonExprFinder</emphasis></entry>

                          <entry><type>boolean</type></entry>

                          <entry>false</entry>

                          <entry>
                               See <xref linkend= "zend.json.advanced.expr"/>
                          </entry>
                      </row>
                  </tbody>
             </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.serializer.adapter.amf03">
        <title>Zend_Serializer_Adapter_Amf 0 and 3</title>

        <para>
            The <acronym>AMF</acronym> adapters, <classname>Zend_Serializer_Adapter_Amf0</classname>
            and <classname>Zend_Serializer_Adapter_Amf3</classname>, provide a bridge to the
            serializer of the <classname>Zend_Amf</classname> component. Please read the <link
                linkend= "zend.amf.introduction">Zend_Amf documentation</link> for further
            information.
        </para>

        <para>
            There are no options for these adapters.
        </para>
    </sect2>

    <sect2 id="zend.serializer.adapter.pythonpickle">
        <title>Zend_Serializer_Adapter_PythonPickle</title>

        <para>
            This adapter converts PHP types to a <ulink
                url="http://docs.python.org/library/pickle.html">Python Pickle</ulink> string
            representation.  With it, you can read the serialized data with Python and read Pickled
            data of Python with PHP.
        </para>

        <para>
            Available options include:
        </para>

        <table>
            <title>Zend_Serializer_Adapter_PythonPickle Options</title>

            <tgroup cols="4">
                 <thead>
                      <row>
                        <entry>Option</entry>

                        <entry>Data Type</entry>

                        <entry>Default Value</entry>

                        <entry>Description</entry>
                    </row>
                 </thead>

                 <tbody>
                      <row>
                          <entry><emphasis>protocol</emphasis></entry>

                          <entry><type>integer</type> (0 | 1 | 2 | 3)</entry>

                          <entry>0</entry>

                          <entry>
                               The Pickle protocol version used on <methodname>serialize</methodname>
                          </entry>
                      </row>
                  </tbody>
             </tgroup>
        </table>

        <para>
            Datatype merging (PHP to Python) occurs as follows:
        </para>

        <table>
            <title>Datatype merging (PHP to Python)</title>

            <tgroup cols="2">
                 <thead>
                      <row>
                        <entry>PHP Type</entry>

                        <entry>Python Type</entry>
                    </row>
                 </thead>

                 <tbody>
                      <row>
                          <entry><type>NULL</type></entry>

                          <entry><type>None</type></entry>
                      </row>

                      <row>
                          <entry><type>boolean</type></entry>

                          <entry><type>boolean</type></entry>
                      </row>

                      <row>
                          <entry><type>integer</type></entry>

                          <entry><type>integer</type></entry>
                      </row>

                      <row>
                          <entry><type>float</type></entry>

                          <entry><type>float</type></entry>
                      </row>

                      <row>
                          <entry><type>string</type></entry>

                          <entry><type>string</type></entry>
                      </row>

                      <row>
                          <entry><type>array</type></entry>

                          <entry><type>list</type></entry>
                      </row>

                      <row>
                          <entry><type>associative array</type></entry>

                          <entry><type>dictionary</type></entry>
                      </row>

                      <row>
                          <entry><type>object</type></entry>

                          <entry><type>dictionary</type></entry>
                      </row>
                  </tbody>
             </tgroup>
        </table>

        <para>
            Datatype merging (Python to PHP) occurs per the following:
        </para>

        <table>
            <title>Datatype merging (Python to PHP)</title>

            <tgroup cols="2">
                 <thead>
                      <row>
                        <entry>Python-Type</entry>

                        <entry>PHP-Type</entry>
                    </row>
                 </thead>

                 <tbody>
                      <row>
                          <entry><type>None</type></entry>

                          <entry><type>NULL</type></entry>
                      </row>

                      <row>
                          <entry><type>boolean</type></entry>

                          <entry><type>boolean</type></entry>
                      </row>

                      <row>
                          <entry><type>integer</type></entry>

                          <entry><type>integer</type></entry>
                      </row>

                      <row>
                          <entry><type>long</type></entry>

                          <entry>
                              <type>integer</type>
                              | <type>float</type>
                              | <type>string</type>
                              | <classname>Zend_Serializer_Exception</classname>
                          </entry>
                      </row>

                      <row>
                          <entry><type>float</type></entry>

                          <entry><type>float</type></entry>
                      </row>

                      <row>
                          <entry><type>string</type></entry>

                          <entry><type>string</type></entry>
                      </row>

                      <row>
                          <entry><type>bytes</type></entry>

                          <entry><type>string</type></entry>
                      </row>

                      <row>
                          <entry><type>Unicode string</type></entry>

                          <entry><type>UTF-8 string</type></entry>
                      </row>

                      <row>
                          <entry><type>list</type></entry>

                          <entry><type>array</type></entry>
                      </row>

                      <row>
                          <entry><type>tuple</type></entry>

                          <entry><type>array</type></entry>
                      </row>

                      <row>
                          <entry><type>dictionary</type></entry>

                          <entry><type>associative array</type></entry>
                      </row>

                      <row>
                          <entry>All other types</entry>

                          <entry><classname>Zend_Serializer_Exception</classname></entry>
                      </row>
                  </tbody>
             </tgroup>
        </table>
    </sect2>
    
    <sect2 id="zend.serializer.adapter.phpcode">
        <title>Zend_Serializer_Adapter_PhpCode</title>

        <para>
            This adapter generates a parsable PHP code representation using <ulink
                url="http://php.net/manual/function.var-export.php">var_export()</ulink>. On
            restoring, the data will be executed using <ulink
                url="http://php.net/manual/function.eval.php">eval</ulink>.
        </para>

        <para>
            There are no configuration options for this adapter.
        </para>

        <warning>
            <title>Unserializing objects</title>

            <para>
                Objects will be serialized using the <ulink
                    url="http://php.net/manual/language.oop5.magic.php#language.oop5.magic.set-state">__set_state</ulink>
                magic method. If the class doesn't implement this method, a fatal error will occur
                during execution.
            </para>
        </warning>

        <warning>
            <title>Uses eval()</title>

            <para>
                The <classname>PhpCode</classname> adapter utilizes <methodname>eval()</methodname>
                to unserialize. This introduces both a performance and potential security issue as a
                new process will be executed. Typically, you should use the
                <methodname>PhpSerialize</methodname> adapter unless you require human-readability
                of the serialized data.
            </para>
        </warning>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->