<commit_before><sect1 id="zend.registry.using">

    <title>Using the Registry</title>

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

    <para>
        The typical usage of the registry is through static methods in the
        Zend_Registry class.  Alternatively, the class is 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>
            To store an entry in the registry, use the static method
            <code>set()</code>.
        </para>

        <example id="zend.registry.using.storing.example">
            <title>Example of set() method</title>
            <programlisting role="php"><![CDATA[
Zend_Registry::set('index', $value);
]]>
            </programlisting>
        </example>

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

        <para>
            The index can be a scalar, either string or integer,
            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 method
            <code>get()</code>.
        </para>

        <example id="zend.registry.using.retrieving.example">
            <title>Example of get() method</title>
            <programlisting role="php"><![CDATA[
$value = Zend_Registry::get('index');
]]>
            </programlisting>
        </example>

        <para>
            The <code>getInstance()</code> method returns the static registry object.
        </para>

        <para>
            A registry object is iterable.
        </para>

        <example id="zend.registry.using.retrieving.example-iterating">
            <title>Example of iterating over the registry</title>
            <programlisting role="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 through
            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, and it is
            for convenience that it is stored statically, so you
            can access it from anywhere in your application.
        </para>

        <para>
            Use a traditional <code>new</code> constructor to create
            an instance of the registry.  This gives you the opportunity
            to initialize the entries in the registry as an associative
            array.
        </para>

        <example id="zend.registry.using.constructing.example">
            <title>Example of constructing a registry</title>
            <programlisting role="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));
]]>
            </programlisting>
        </example>

        <para>
            After constructing this instance, you can use it using
            array-object methods, or you can set this instance
            to become the static instance using the static method
            <code>setInstance()</code>.
        </para>

        <example id="zend.registry.using.constructing.example-setinstance">
            <title>Example of initializing the static registry</title>
            <programlisting role="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));

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

        <para>
            The <code>setInstance()</code> method throws a Zend_Exception
            if the static registry has already been initialized by its
            first access.
        </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 role="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, using index names as object
            properties.
            To do this, you need to specifically construct the registry
            object using the <code>ArrayObject::ARRAY_AS_PROPS</code> option,
            and initialize the static instance.  You must do this before
            the static registry has been accessed for the first time.
            <emphasis role="strong">Beware</emphasis> of using this option,
            since some versions of PHP have bugs when using the registry
            with this option.
        </para>

        <example id="zend.registry.using.array-object.example">
            <title>Example of object access</title>
            <programlisting role="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 a value, use the static method <code>isRegistered()</code>.
        </para>

        <example id="zend.registry.using.isset.example-isregistered">
            <title>Example of isRegistered() method</title>
            <programlisting role="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-object has a value, use <code>isset()</code>
            like you would with an ordinary array.
        </para>

        <example id="zend.registry.using.isset.example-isset">
            <title>Example of isset() method</title>
            <programlisting role="php"><![CDATA[
$registry = Zend_Registry::getInstance();

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

// using object-access syntax, if enabled
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 Zend_Registry.
            If you want to add functionality to the registry, you can
            create a class that extends Zend_Registry, and then you can
            specify this class as the class to use for the static registry.
            Use the static method <code>setClassName()</code> to specify
            the class.  The class must extend Zend_Registry.
        </para>

        <example id="zend.registry.using.subclassing.example">
            <title>Example of specifying the static registry's class name</title>
            <programlisting role="php"><![CDATA[
Zend_Registry::setClassName('My_Registry');

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

        <para>
            The registry throws a Zend_Exception if you try to set the
            classname after the registry has been accessed for the first time.
            It is recommended that you specify the classname 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 static instance of the registry.
            Use the static method <code>_unsetInstance()</code>.
        </para>

        <note>
            <title>Data loss risk</title>
            <para>
                When you use <code>_unsetInstance()</code>,
                all data in the static registry are
                discarded and cannot be recovered.
            </para>
        </note>

        <para>
            You might use this method, for example, if you want to
            use <code>setInstance()</code> or <code>setClassName()</code>
            after the static registry object has been initialized.
            Unsetting the static instance allows you to use these methods.
        </para>

        <example id="zend.registry.using.unsetting.example">
            <title>Example of _unsetInstance() method</title>
            <programlisting role="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:
--><commit_msg>Major style changes, some content addition and grammar re-working. Translation required.<commit_after><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
        <code>Zend_Registry</code> 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 <code>set()</code> to store an entry in the registry, .
        </para>

        <example id="zend.registry.using.storing.example">
            <title>Example of <code>set()</code> Method Usage</title>
            <programlisting role="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 <code>set()</code> method to set the entry
            to a new value.
        </para>

        <para>
            The index can be a scalar (<code>null</code>, 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
            <code>get()</code> method.
        </para>

        <example id="zend.registry.using.retrieving.example">
            <title>Example of <code>get()</code> Method Usage</title>
            <programlisting role="php"><![CDATA[
$value = Zend_Registry::get('index');
]]>
            </programlisting>
        </example>

        <para>
            The <code>getInstance()</code> 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 role="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 <code>new</code> operator to instantiate
            <code>Zend_Registry</code>. Instantiating <code>Zend_Registry</code>
            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 role="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));
]]>
            </programlisting>
        </example>

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

        <example id="zend.registry.using.constructing.example-setinstance">
            <title>Example of Initializing the Singleton Registry</title>
            <programlisting role="php"><![CDATA[
$registry = new Zend_Registry(array('index' => $value));

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

        <para>
            The <code>setInstance()</code> method throws a <code>Zend_Exception</code>
            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 role="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 <code>ArrayObject::ARRAY_AS_PROPS</code> option
            and initialize the static instance to enable this functionality.
            <note>You must set the <code>ArrayObject::ARRAY_AS_PROPS</code> option
            <emphasis>before</emphasis>
            the static registry has been accessed for the first time.</note>
        </para>
            <warning>
                <title>Known Issues with the <code>ArrayObject::ARRAY_AS_PROPS</code> Option</title>

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

        <example id="zend.registry.using.array-object.example">
            <title>Example of Object Access</title>
            <programlisting role="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 <code>isRegistered()</code>.
        </para>

        <example id="zend.registry.using.isset.example-isregistered">
            <title>Example of isRegistered() method</title>
            <programlisting role="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 <code>isset()</code> function
            as you would with an ordinary array.
        </para>

        <example id="zend.registry.using.isset.example-isset">
            <title>Example of Using the <code>isset()</code> Method</title>
            <programlisting role="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 <code>Zend_Registry</code>.
            If you want to add functionality to the registry, you should
            create a class that extends <code>Zend_Registry</code> and
            specify this class to instantiate for the singleton in the static registry.
            Use the static method <code>setClassName()</code> to specify
            the class.
            <note>
            	The class must be a subclass of <code>Zend_Registry</code>.
            </note>
        </para>

        <example id="zend.registry.using.subclassing.example">
            <title>Example of Specifying the Singleton Registry's Class Name</title>
            <programlisting role="php"><![CDATA[
Zend_Registry::setClassName('My_Registry');

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

        <para>
            The registry throws a <code>Zend_Exception</code> 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 <code>_unsetInstance()</code> to do so.
        </para>

        <warning>
            <title>Data Loss Risk</title>
            <para>
                When you use <code>_unsetInstance()</code>,
                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 <code>setInstance()</code> or <code>setClassName()</code>
            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
            <code>Zend_Registry</code> in this manner is not recommended for typical
            applications and environments.
        </para>

        <example id="zend.registry.using.unsetting.example">
            <title>Example of the <code>_unsetInstance()</code> Method</title>
            <programlisting role="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:
-->
{'fraction_non_alphanumeric': 0.10521279504237674, 'fraction_numerical': 0.0018226556092226375, 'mean_word_length': 2.2688412272862677, 'pattern_counts': {'":': 0, '<': 437, '<?xml version=': 0, '>': 455, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4551017', 'n_tokens_mistral': 5861, 'n_tokens_neox': 5524, 'n_words': 1924}