<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.registry.using">
    <title>Using the Registry</title>

    <para>
        A registry is a container for storing objects and values in the
        application space. By storing the value in a registry, the same
        object is always available throughout your application.
        This mechanism is an alternative to using global storage.
    </para>

    <para>
        The typical method to use registries with Zend Framework is through static methods in the
        <classname>Zend_Registry</classname> class. Alternatively, the registry can be used as an
        array object, so you can access elements stored within it with a convenient array-like
        interface.
    </para>

    <sect2 id="zend.registry.using.storing">
        <title>Setting Values in the Registry</title>

        <para>
            Use the static method <methodname>set()</methodname> to store an entry in the registry.
        </para>

        <example id="zend.registry.using.storing.example">
            <title>Example of set() Method Usage</title>

            <programlisting language="php"><![CDATA[
Zend_Registry::set('index', $value);
]]></programlisting>
        </example>

        <para>
            The value returned can be an object, an array, or a scalar.
            You can change the value stored in a specific entry of
            the registry by calling the <methodname>set()</methodname> method to set the entry
            to a new value.
        </para>

        <para>
            The index can be a scalar (<constant>NULL</constant>, string, or number), like an
            ordinary array.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.retrieving">
        <title>Getting Values from the Registry</title>

        <para>
            To retrieve an entry from the registry, use the static
            <methodname>get()</methodname> method.
        </para>

        <example id="zend.registry.using.retrieving.example">
            <title>Example of get() Method Usage</title>

            <programlisting language="php"><![CDATA[
$value = Zend_Registry::get('index');
]]></programlisting>
        </example>

        <para>
            The <methodname>getInstance()</methodname> method returns the singleton registry object.
            This registry object is iterable, making all values stored in the registry easily
            accessible.
        </para>

        <example id="zend.registry.using.retrieving.example-iterating">
            <title>Example of Iterating over the Registry</title>

            <programlisting language="php"><![CDATA[
$registry = Zend_Registry::getInstance();

foreach ($registry as $index => $value) {
    echo "Registry index $index contains:\n";
    var_dump($value);
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.constructing">
        <title>Constructing a Registry Object</title>

        <para>
            In addition to accessing the static registry via
            static methods, you can create an instance directly and
            use it as an object.
        </para>

        <para>
            The registry instance you access through the
            static methods is simply one such instance. It is
            for convenience that it is stored statically, so that it is
            accessible from anywhere in an application.
        </para>

        <para>
            Use the traditional <emphasis>new</emphasis> operator to instantiate
            <classname>Zend_Registry</classname>. Instantiating <classname>Zend_Registry</classname>
            using its constructor also makes initializing the entries in the registry simple by
            taking an associative array as an argument.
        </para>

        <example id="zend.registry.using.constructing.example">
            <title>Example of Constructing a Registry</title>

            <programlisting language="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));
]]></programlisting>
        </example>

        <para>
            Once such a <classname>Zend_Registry</classname> object is instantiated,
            you can use it by calling any array object method or by setting it
            as the singleton instance for <classname>Zend_Registry</classname> with the static
            method <methodname>setInstance()</methodname>.
        </para>

        <example id="zend.registry.using.constructing.example-setinstance">
            <title>Example of Initializing the Singleton Registry</title>

            <programlisting language="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));

Zend_Registry::setInstance($registry);
]]></programlisting>
        </example>

        <para>
            The <methodname>setInstance()</methodname> method throws a
            <classname>Zend_Exception</classname> if the static registry has already been
            initialized.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.array-access">
        <title>Accessing the Registry as an Array</title>

        <para>
            If you have several values to get or set, you may find it
            convenient to access the registry with array notation.
        </para>

        <example id="zend.registry.using.array-access.example">
            <title>Example of Array Access</title>

            <programlisting language="php"><![CDATA[
$registry = Zend_Registry::getInstance();

$registry['index'] = $value;

var_dump( $registry['index'] );
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.array-object">
        <title>Accessing the Registry as an Object</title>

        <para>
            You may also find it convenient to access the registry
            in an object-oriented fashion by using index names as object
            properties.
            You must specifically construct the registry
            object using the <constant>ArrayObject::ARRAY_AS_PROPS</constant> option
            and initialize the static instance to enable this functionality.

            <note>
                <para>You must set the <constant>ArrayObject::ARRAY_AS_PROPS</constant> option
                <emphasis>before</emphasis> the static registry has been accessed for
                the first time.</para>
            </note>
        </para>

        <warning>
            <title>Known Issues with the ArrayObject::ARRAY_AS_PROPS Option</title>

            <para>
                Some versions of <acronym>PHP</acronym> have proven very buggy when using the
                registry with the <constant>ArrayObject::ARRAY_AS_PROPS</constant> option.
            </para>
        </warning>

        <example id="zend.registry.using.array-object.example">
            <title>Example of Object Access</title>

            <programlisting language="php"><![CDATA[
// in your application bootstrap:
$registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS)
Zend_Registry::setInstance($registry);
$registry->tree = 'apple';

.
.
.

// in a different function, elsewhere in your application:
$registry = Zend_Registry::getInstance();

echo $registry->tree; // echo's "apple"

$registry->index = $value;

var_dump($registry->index);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.isset">
        <title>Querying if an Index Exists</title>

        <para>
            To find out if a particular index in the registry
            has been set, use the static method <methodname>isRegistered()</methodname>.
        </para>

        <example id="zend.registry.using.isset.example-isregistered">
            <title>Example of isRegistered() Method Usage</title>

            <programlisting language="php"><![CDATA[
if (Zend_Registry::isRegistered($index)) {
    $value = Zend_Registry::get($index);
}
]]></programlisting>
        </example>

        <para>
            To find out if a particular index in a registry
            array or object has a value, use the <methodname>isset()</methodname> function
            as you would with an ordinary array.
        </para>

        <example id="zend.registry.using.isset.example-isset">
            <title>Example of isset() Method Usage</title>

            <programlisting language="php"><![CDATA[
$registry = Zend_Registry::getInstance();

// using array access syntax
if (isset($registry['index'])) {
    var_dump( $registry['index'] );
}

// using object access syntax
if (isset($registry->index)) {
    var_dump( $registry->index );
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.subclassing">
        <title>Extending the Registry</title>

        <para>
            The static registry is an instance of the class <classname>Zend_Registry</classname>.
            If you want to add functionality to the registry, you should
            create a class that extends <classname>Zend_Registry</classname> and
            specify this class to instantiate for the singleton in the static registry.
            Use the static method <methodname>setClassName()</methodname> to specify
            the class.

            <note>
                <para>The class must be a subclass of <classname>Zend_Registry</classname>.</para>
            </note>
        </para>

        <example id="zend.registry.using.subclassing.example">
            <title>Example of Specifying the Singleton Registry's Class Name</title>

            <programlisting language="php"><![CDATA[
Zend_Registry::setClassName('My_Registry');

Zend_Registry::set('index', $value);
]]></programlisting>
        </example>

        <para>
            The registry throws a <classname>Zend_Exception</classname> if you attempt to set the
            classname after the registry has been accessed for the first time.
            It is therefore recommended that you specify the class name for your
            static registry in your application bootstrap.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.unsetting">
        <title>Unsetting the Static Registry</title>

        <para>
            Although it is not normally necessary, you can
            unset the singleton instance of the registry, if desired.
            Use the static method <methodname>_unsetInstance()</methodname> to do so.
        </para>

        <warning>
            <title>Data Loss Risk</title>

            <para>
                When you use <methodname>_unsetInstance()</methodname>,
                all data in the static registry are
                discarded and cannot be recovered.
            </para>
        </warning>

        <para>
            You might use this method, for example, if you want to
            use <methodname>setInstance()</methodname> or <methodname>setClassName()</methodname>
            after the singleton registry object has been initialized.
            Unsetting the singleton instance allows you to use these methods
            even after the singleton registry object has been set. Using
            <classname>Zend_Registry</classname> in this manner is not recommended for typical
            applications and environments.
        </para>

        <example id="zend.registry.using.unsetting.example">
            <title>Example of _unsetInstance() Method Usage</title>

            <programlisting language="php"><![CDATA[
Zend_Registry::set('index', $value);

Zend_Registry::_unsetInstance();

// change the class
Zend_Registry::setClassName('My_Registry');

Zend_Registry::set('index', $value);
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->