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 <acronym>PHP</acronym>
        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,
        <acronym>PHP</acronym> 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>
            <acronym>PHP</acronym> 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
            <acronym>PHP</acronym> serializer. Instead of time and space consuming textual
            representation, igbinary stores <acronym>PHP</acronym> 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 <acronym>PHP</acronym> 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> <acronym>PHP</acronym>
            functions. Please read the <acronym>PHP</acronym> manual to determine how you may enable
            them in your <acronym>PHP</acronym> installation.
        </para>

        <para>
            Additionally, the <ulink
                url="http://php.net/manual/book.simplexml.php">SimpleXML</ulink>
            <acronym>PHP</acronym> 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 id="zend.serializer.adapter.wddx.table.options">
            <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 id="zend.serializer.adapter.json.table.options">
            <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 <link linkend="zend.json.advanced.objects1">this section</link>
                          </entry>
                      </row>

                      <row>
                          <entry><emphasis>objectDecodeType</emphasis></entry>
                          <entry><type>Zend_Json::TYPE_*</type></entry>
                          <entry>Zend_Json::TYPE_ARRAY</entry>

                          <entry>
                              See <link linkend= "zend.json.advanced.objects1">this section</link>
                          </entry>
                      </row>

                      <row>
                          <entry><emphasis>enableJsonExprFinder</emphasis></entry>
                          <entry><type>boolean</type></entry>
                          <entry>false</entry>

                          <entry>
                              See <link linkend= "zend.json.advanced.expr">this section</link>
                          </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 <acronym>PHP</acronym> 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 <acronym>PHP</acronym>.
        </para>

        <para>
            Available options include:
        </para>

        <table id="zend.serializer.adapter.pythonpickle.table.options">
            <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 id="zend.serializer.adapter.pythonpickle.table.php2python">
            <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 <acronym>PHP</acronym>) occurs per the following:
        </para>

        <table id="zend.serializer.adapter.pythonpickle.table.python2php">
            <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 <acronym>PHP</acronym> 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:
-->