repo_zf1/documentation/manual/de/module_specs/Zend_Registry.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect1 id="zend.registry.using">
    <title>Die Registry verwenden</title>

    <para>
        Eine Registry ist ein Container für das Speichern von Objekten und Werten im
        Raum der Anwendung. Durch das Speichern der Werte in einer Registry steht das
        selbe Objekt immer innerhalb der kompletten Anwendung zur Verfügung.
        Dieser Mechanismus ist eine Alernative zur Verwendung eines Globalen Speichers.
    </para>

    <para>
        Die typische Methode um Registries mit dem Zend Framework zu verwenden ist durch die
        statischen Methoden in der <classname>Zend_Registry</classname> Klasse. Alternativ kann die
        Registry als Arrayobjekt verwendet werden, und so können Elemente welche darin gespeichert
        wurden durch ein gewöhnliches Array-artiges Interface verwendet werden.
    </para>

    <sect2 id="zend.registry.using.storing">
        <title>Werte in die Registry speichern</title>

        <para>
            Verwende die statische Methode <methodname>set()</methodname> um einen Eintrag in der
            Registry zu Speichern.
        </para>

        <example id="zend.registry.using.storing.example">
            <title>Beispiel der Verwendung der set() Methode</title>

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

        <para>
            Der zurückgegebene Wert kann ein Objekt, ein Array oder ein Skalar sein.
            Der gespeicherte Wert in einem speziellen Eintrag der Registry
            kann durch den Aufruf der <methodname>set()</methodname> Methode verändert werden um
            den Eintrag auf einen neuen Wert zu setzen.
        </para>

        <para>
            Der Index kann ein Skalar (<constant>NULL</constant>, String oder Nummer),
            sowie ein gewöhnliches Array sein.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.retrieving">
        <title>Werte aus der Registry lesen</title>

        <para>
            Um einen Eintrag von der Registry zu erhalten, kann die statische
            <methodname>get()</methodname> Methode verwendet werden.
        </para>

        <example id="zend.registry.using.retrieving.example">
            <title>Beispiel der Verwendung der get() Methode</title>

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

        <para>
            Die <methodname>getInstance()</methodname> Methode gibt ein Singleton Registry Objekt
            zurück. Dieses Registry Objekt ist durchsuchbar, und erlaubt es auf alle in der Registry
            gespeicherten Werte einfach zuzugreifen.
        </para>

        <example id="zend.registry.using.retrieving.example-iterating">
            <title>Beispiel des Durchsuchens der Registry</title>

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

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

    <sect2 id="zend.registry.using.constructing">
        <title>Erstellen eines Registry Objektes</title>

        <para>
            Zusätzlich zur Verwendung der statischen Registry über die statischen Methoden,
            kann eine Instanz direkt erzeugt werden und als Objekt verwendet werden.
        </para>

        <para>
            Die Registry Instanz die durch die statischen Methoden verwendet wird,
            ist einfach eine solche Instanz. Es ist eine Vereinfachung die statisch
            gespeichert ist damit Sie von überall innerhalb einer Anwendung verwendet
            werden kann.
        </para>

        <para>
            Der traditionelle <emphasis>new</emphasis> Operator kann verwendet werden um
            <classname>Zend_Registry</classname> zu initiieren. Das Initiieren von
            <classname>Zend_Registry</classname> mit seinem Konstruktor initiiert auch die Einträge
            in der Registry einfach durch die Verwendung eines assoziativen Arrays als Argument.
        </para>

        <example id="zend.registry.using.constructing.example">
            <title>Beispiel für das Erstellen einer Registry</title>

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

        <para>
            Sobald so ein <classname>Zend_Registry</classname> Objekt initiiert wurde, kann es durch
            den Aufruf irgendeiner Array Objektmethode verwendet werden, oder indem es als
            Singleton Instanz für <classname>Zend_Registry</classname> mit der statischen Methode
            <methodname>setInstance()</methodname> gesetzt wird.
        </para>

        <example id="zend.registry.using.constructing.example-setinstance">
            <title>Beispiel der Initialisierung der Singleton Registry</title>

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

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

        <para>
            Die <methodname>setInstance()</methodname> Methode wirft eine
            <classname>Zend_Exception</classname> wenn die statische Registry bereits initialisiert
            wurde.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.array-access">
        <title>Auf die Registry als Array zugreifen</title>

        <para>
            Wenn mehrere Werte gesetzt oder gelesen werden sollen, kann es einfacher
            sein auf die Registry in Array Schreibweise zuzugreifen.
        </para>

        <example id="zend.registry.using.array-access.example">
            <title>Beispiel eines Array-zugriffs</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>Zugriff auf die Registry als Objekt</title>

        <para>
            Manchmal ist es einfacher auf die Registry in einer Objekt-Orientierten
            Art und Weise zuzugreifen, durch Verwendung von Indexnamen als Objekt Eigenschaften.
            Man muß das Registry Objekt mit der <constant>ArrayObject::ARRAY_AS_PROPS</constant>
            Option erstellen und die statische Instanz initialisieren um diese Funktionalität
            einzuschalten.

            <note>
                <para>
                    Man muß die <constant>ArrayObject::ARRAY_AS_PROPS</constant> Option setzen
                    <emphasis>bevor</emphasis> auf die statische Registry das erste Mal
                    zugegriffen wird.
                </para>
            </note>
        </para>

        <warning>
            <title>Bekannte Probleme mit der ArrayObject::ARRAY_AS_PROPS Option</title>

            <para>
                Einige Versionen von <acronym>PHP</acronym> sind bekanntermaßen sehr fehlerhaft wenn
                die Registry mit der <constant>ArrayObject::ARRAY_AS_PROPS</constant> Option
                verwendet wird.
            </para>
        </warning>

        <example id="zend.registry.using.array-object.example">
            <title>Beispiel eines Objektzugriffs</title>

            <programlisting language="php"><![CDATA[
// In der Anwendungs Bootstrap Datei:
$registry = new Zend_Registry(array(), ArrayObject::ARRAY_AS_PROPS)
Zend_Registry::setInstance($registry);
$registry->tree = 'Apfel';

.
.
.

// In einer anderen Funktion, irgendwo in der Anwendung:
$registry = Zend_Registry::getInstance();

echo $registry->tree; // Gibt "Apfel" aus

$registry->index = $value;

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

    <sect2 id="zend.registry.using.isset">
        <title>Abfragen ob ein Index existiert</title>

        <para>
            Um herauszufinden ob ein bestimmter Index in der Registry gesetzt wurde,
            kann die statische Methode <methodname>isRegistered()</methodname> verwendet werden.
        </para>

        <example id="zend.registry.using.isset.example-isregistered">
            <title>Beispiel der Verwendung der isRegistered() Methode</title>

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

        <para>
            Um herauszufinden ob ein bestimmter Index in einem Registry Array oder Objekt
            einen Wert hat kann die <methodname>isset()</methodname> Methode verwendet werden, wie
            bei einem gewöhnlichen Array.
        </para>

        <example id="zend.registry.using.isset.example-isset">
            <title>Beispiel der Verwendung der isset() Methode</title>

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

// Verwendung der Array Syntax
if (isset($registry['index'])) {
    var_dump( $registry['index'] );
}

// Verwendung der Objekt Syntax
if (isset($registry->index)) {
    var_dump( $registry->index );
}
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.registry.using.subclassing">
        <title>Erweitern der Registry</title>

        <para>
            Die statische Registry ist eine Instanz der Klasse <classname>Zend_Registry</classname>.
            Wenn Funktionalität zur Registry hinzugefügt werden soll, sollte eine Klasse
            erstellt werden die <classname>Zend_Registry</classname> erweitert und dann kann diese
            spezielle Klasse definiert werden um das Singleton in der statische Registry zu
            initiieren. Die statische Methode <methodname>setClassName()</methodname> kann verwendet
            werden um die Klasse zu definieren.

            <note>
                <para>
                    Diese Klasse muß eine Unterklasse von <classname>Zend_Registry</classname> sein.
                </para>
            </note>
        </para>

        <example id="zend.registry.using.subclassing.example">
            <title>Beispiel des Definierens des Singleton Registry Klassennamens</title>

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

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

        <para>
            Die Registry wirft eine <classname>Zend_Exception</classname> wenn man versucht den
            Klassennamen zu setzen nachdem die Registry das erste Mal verwendet wurde. Es ist
            deshalb notwendig den Klassennamen für die statische Registry in der Bootstrap
            Datei der Anwendung zu definieren.
        </para>
    </sect2>

    <sect2 id="zend.registry.using.unsetting">
        <title>Entfernen der statischen Registry</title>

        <para>
            Obwohl es normalerweise nicht notwendig ist, kann die Singleton Instanz
            der Registry entfernt werden. Die statische Methode
            <methodname>_unsetInstance()</methodname> verwendet werden, um das zu tun.
        </para>

        <warning>
            <title>Risiko des Datenverlustes</title>

            <para>
                Wenn <methodname>_unsetInstance()</methodname> verwendet wird,
                werden alle Daten in der statischen Registry verworfen und können
                nicht wiederhergestellt werden.
            </para>
        </warning>

        <para>
            Diese Methode kann zum Beispiel verwendet werden, wenn
            <methodname>setInstance()</methodname> oder <methodname>setClassName()</methodname> nach
            der Initialisierung des Singleton Registry Objektes verwendet werden soll.
            Entfernen der Singleton Instanz erlaubt die Benutzung dieser Methoden
            selbst nachdem das Singleton Registry Objekt gesetzt wurde. Die Verwendung
            von <classname>Zend_Registry</classname> auf diese Weise ist für typische Anwendungen
            und Umgebungen nicht empfohlen.
        </para>

        <example id="zend.registry.using.unsetting.example">
            <title>Beispiel der Verwendung der _unsetInstance() Methode</title>

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

Zend_Registry::_unsetInstance();

// Ändern der Klasse
Zend_Registry::setClassName('Meine_Registry');

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