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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.serializer.introduction">
    <title>Introduction</title>

    <para>
        <classname>Zend_Serializer</classname> provides an adapter based interface to simply
        generate storable representation of <acronym>PHP</acronym> types by different facilities,
        and recover.
    </para>

    <example id="zend.serializer.introduction.example.dynamic">
        <title>Using Zend_Serializer dynamic interface</title>

        <para>
            To instantiate a serializer you should use the factory method with the name of the
            adapter:
        </para>

        <programlisting language="php"><![CDATA[
$serializer = Zend_Serializer::factory('PhpSerialize');
// Now $serializer is an instance of Zend_Serializer_Adapter_AdapterInterface,
// specifically Zend_Serializer_Adapter_PhpSerialize

try {
    $serialized = $serializer->serialize($data);
    // now $serialized is a string

    $unserialized = $serializer->unserialize($serialized);
    // now $data == $unserialized
} catch (Zend_Serializer_Exception $e) {
    echo $e;
}
]]></programlisting>
    </example>

    <para>
        The method <methodname>serialize()</methodname> generates a storable string. To regenerate
        this serialized data you can simply call the method <methodname>unserialize()</methodname>.
    </para>

    <para>
        Any time an error is encountered serializing or unserializing,
        <classname>Zend_Serializer</classname> will throw a
        <classname>Zend_Serializer_Exception</classname>.
    </para>

    <para>
        To configure a given serializer adapter, you can optionally add an array or an instance of
        <classname>Zend_Config</classname> to the <methodname>factory()</methodname> or to the
        <methodname>serialize()</methodname> and <methodname>unserialize()</methodname> methods:
    </para>

    <programlisting language="php"><![CDATA[
$serializer = Zend_Serializer::factory('Wddx', array(
    'comment' => 'serialized by Zend_Serializer',
));

try {
    $serialized = $serializer->serialize(
        $data,
        array('comment' => 'change comment')
    );

    $unserialized = $serializer->unserialize(
        $serialized,
        array(/* options for unserialize */)
    );
} catch (Zend_Serializer_Exception $e) {
    echo $e;
}
]]></programlisting>

    <para>
        Options passed to the <methodname>factory()</methodname> are valid for the instantiated
        object. You can change these options using the <methodname>setOption(s)</methodname> method.
        To change one or more options only for a single call, pass them as the second argument to
        either the <methodname>serialize()</methodname> or <methodname>unserialize()</methodname>
        method.
    </para>

    <example id="zend.serializer.introduction.example.static.php">
        <title>Using the Zend_Serializer static interface</title>

        <para>
            You can register a specific serializer adapter as a default serialization adapter for
            use with <classname>Zend_Serializer</classname>. By default, the
            <classname>PhpSerialize</classname> adapter will be registered, but you can change this
            option using the <methodname>setDefaultAdapter()</methodname> static method.
        </para>

        <programlisting language="php"><![CDATA[
Zend_Serializer::setDefaultAdapter('PhpSerialize', $options);
// or
$serializer = Zend_Serializer::factory('PhpSerialize', $options);
Zend_Serializer::setDefaultAdapter($serializer);

try {
    $serialized   = Zend_Serializer::serialize($data, $options);
    $unserialized = Zend_Serializer::unserialize($serialized, $options);
} catch (Zend_Serializer_Exception $e) {
    echo $e;
}
]]></programlisting>
    </example>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->