<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 17172 -->
<!-- Reviewed: no -->
<sect1 id="zend.filter.inflector">
    <title>Zend_Filter_Inflector</title>

    <para>
        <classname>Zend_Filter_Inflector</classname> ist ein generell verwendbares Tool für
        regel-basierende Beugung von Strings zu einem gegebenen Ziel.
    </para>

    <para>
        Als Beispiel, kann es gewünscht sein MixedCase oder camelCaseWörter in einen Pfad zu
        transformieren; für die Lesbarkeit, OS Policies, oder andere Gründe, sollen diese auch
        kleingeschrieben werden, und die Wörter sollen mit einem Bindestrich ('-') getrennt werden.
        Eine Beugung (Inflector) kann das erledigen.
    </para>

    <para>
        <classname>Zend_Filter_Inflector</classname> implementiert
        <classname>Zend_Filter_Interface</classname>; eine Beugung kann durch den Aufruf von
        <methodname>filter()</methodname> auf der Objekt Instanz durchgeführt werden.
    </para>

    <example id="zend.filter.inflector.camel_case_example">
        <title>MixedCase und camelCaseText in ein anderes Format transformieren</title>

        <programlisting language="php"><![CDATA[
$inflector = new Zend_Filter_Inflector('pages/:page.:suffix');
$inflector->setRules(array(
    ':page'  => array('Word_CamelCaseToDash', 'StringToLower'),
    'suffix' => 'html'
));

$string   = 'camelCasedWords';
$filtered = $inflector->filter(array('page' => $string));
// pages/camel-cased-words.html

$string   = 'this_is_not_camel_cased';
$filtered = $inflector->filter(array('page' => $string));
// pages/this_is_not_camel_cased.html
]]></programlisting>
    </example>

    <sect2 id="zend.filter.inflector.operation">
        <title>Funktion</title>

        <para>
            Eine Beugung benötigt ein <emphasis>Ziel</emphasis> (target) und ein oder mehrere
            <emphasis>Regeln</emphasis> (rules). Ein Ziel ist grundsätzlich ein String der
            Platzhalter für Variablen definiert die ersetzt werden sollen. Sie werden durch das
            Voranstellen eines ':' spezifiziert: <code>:script</code>.
        </para>

        <para>
            Wenn <methodname>filter()</methodname> aufgerufen wird, muß ein Array von
            Schlüssel/Wert Paaren übergeben werden die den Variablen im Ziel entsprechen.
        </para>

        <para>
            Jede Variable im Ziel kann null oder mehr, mit Ihr assoziierte Regeln, besitzen. Regeln
            können entweder <emphasis>statisch</emphasis> (static) sein oder zu einer
            <classname>Zend_Filter</classname> Klasse verweisen. Statische Regeln werden den
            angegebenen Text ersetzen. Andernfalls wird eine Klasse verwendet die auf die Regel
            passt die angegeben wurde, um den Text zu beugen. Klasse werden typischerweise
            spezifiziert indem ein Kurzname verwendet wird, der den Filternamen indiziert, wobei
            jeglicher üblicher Präfix entfernt wurde.
        </para>

        <para>
            Als Beispiel kann jede konkrete <classname>Zend_Filter</classname> Implementierung
            verwendet werden; trotzdem, statt auf diese als 'Zend_Filter_Alpha' oder
            'Zend_Filter_StringToLower' zu verweisen kann einfach 'Alpha' oder 'StringToLower'
            spezifiziert werden.
        </para>
    </sect2>

     <sect2 id="zend.filter.inflector.paths">
        <title>Pfade zu alternativen Filtern setzen</title>

        <para>
            <classname>Zend_Filter_Inflector</classname> verwendet
            <classname>Zend_Loader_PluginLoader</classname> um das Laden von Filtern zu managen die
            von der Beugung verwendet werden sollen. Standardmäßig, wird jeder Filter mit dem Präfix
            <classname>Zend_Filter</classname> vorhanden sein. Um auf Filter mit diesem Präfix
            zuzugreifen, die aber tiefer in der Hirarchie vorhanden sind, kann einfach der
            <classname>Zend_Filter Präfix</classname> entfernt werden:
        </para>

        <programlisting language="php"><![CDATA[
// Verwendet Zend_Filter_Word_CamelCaseToDash als Regel
$inflector->addRules(array('script' => 'Word_CamelCaseToDash'));
]]></programlisting>

        <para>
            Um einen alternativen Pfad zu setzen hat <classname>Zend_Filter_Inflector</classname>
            eine Utility Methode die den Plugin Lader verwendet,
            <methodname>addFilterPrefixPath()</methodname>:
        </para>

        <programlisting language="php"><![CDATA[
$inflector->addFilterPrefixPath('My_Filter', 'My/Filter/');
]]></programlisting>

        <para>
            Alternativ kann der Plugin Lader von der Beugung empfangen, und direkt mit Ihm
            interagiert werden:
        </para>

        <programlisting language="php"><![CDATA[
$loader = $inflector->getPluginLoader();
$loader->addPrefixPath('My_Filter', 'My/Filter/');
]]></programlisting>

        <para>
            Für weitere Optionen über das Bearbeiten von Pfaden zu Filtern sollte in die <link
                linkend="zend.loader.pluginloader">PluginLoader Dokumentation</link> gesehen werden.
        </para>
    </sect2>

    <sect2 id="zend.filter.inflector.targets">
        <title>Das Ziel der Beugung setzen</title>

        <para>
            Das Ziel der Beugung ist ein String mit einigen Platzhaltern für Variablen. Platzhalter
            haben die Form eines Identifizierers, standardmäßig einem Doppelpunkt (':'), gefolgt von
            einem Variablennamen: ':script', ':path', usw. Die <methodname>filter()</methodname>
            Methode sieht nach dem Identifizierer gefolgt von dem Variablennamen der ersetzt werden
            soll.
        </para>

        <para>
            Der Identifizierer kann geändert werden in dem die
            <methodname>setTargetReplacementIdentifier()</methodname> Methode verwendet wird, oder
            indem er als drittes Argument dem Konstruktor übergeben wird:
        </para>

        <programlisting language="php"><![CDATA[
// Über Konstruktor:
$inflector = new Zend_Filter_Inflector('#foo/#bar.#sfx', null, '#');

// Über Zugriffsmethode:
$inflector->setTargetReplacementIdentifier('#');
]]></programlisting>

        <para>
            Typischerweise wird das Ziel über den Konstruktor gesetzt. Trotzdem kann es Ziel später
            geändert werden (zum Beispiel, um die Standardbeugung in Kernkomponenten die dem
            <code>ViewRenderer</code> oder <classname>Zend_Layout</classname> zu verändern).
            <methodname>setTarget()</methodname> kann für diese Zwecke verwendet werden:
        </para>

        <programlisting language="php"><![CDATA[
$inflector = $layout->getInflector();
$inflector->setTarget('layouts/:script.phtml');
]]></programlisting>

        <para>
            Zusätzlich kann es gewünscht sein einen Klassenmember für die eigene Klasse zu haben,
            der es erlaubt das Beugungsziel zu aktualisieren -- ohne das das Ziel jedesmal direkt
            aktualisiert werden muß (was Methodenaufrufe erspart).
            <methodname>setTargetReference()</methodname> erlaubt es das zu tun:
        </para>

        <programlisting language="php"><![CDATA[
class Foo
{
    /**
     * @var string Beugungsziel
     */
    protected $_target = 'foo/:bar/:baz.:suffix';

    /**
     * Konstruktor
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend_Filter_Inflector();
        $this->_inflector->setTargetReference($this->_target);
    }

    /**
     * Setzt das Ziel; Aktualisiert das Ziel für die Beugung
     *
     * @param  string $target
     * @return Foo
     */
    public function setTarget($target)
    {
        $this->_target = $target;
        return $this;
    }
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.filter.inflector.rules">
        <title>Beugungsregeln</title>

        <para>
            Wie bereits in der Einführung erwähnt, gibt es zwei Typen von Regeln: statische und
            filter-basierende.
        </para>

        <note>
            <para>
                Es ist wichtig festzustellen das unabhängig von der Methode in welche Regeln dem
                Inflector hinzugefügt werden, entweder eine nach der anderen, oder alle auf einmal;
                die Reihenfolge sehr wichtig ist. Speziellere Namen, oder Namen die andere
                Regelnamen enthalten können, müssen vor nicht speziellen Namen hinzugefügt werden.
                Wenn zum Beispiel zwei Regelnamen 'moduleDir' und 'module' angenommen werden,
                sollte die 'moduleDir' Regel vor 'module' auftreten, da 'module' in 'moduleDir'
                enthalten ist. Wenn 'module' vor 'moduleDir' hinzugefügt wurde, wird 'module' als
                Teil von 'moduleDir' erkannt und und ausgeführt wobei 'Dir' im Ziel nicht ersetzt
                wird.
            </para>
        </note>

        <sect3 id="zend.filter.inflector.rules.static">
            <title>Statische Regeln</title>

            <para>
                Statische Regeln führen einfach eine Ersetzung von Strings aus; sie sollten
                verwendet werden wenn ein Segment in einem Ziel existiert das typischerweise
                statisch ist, aber welches der Entwickler ändern darf. Die
                <methodname>setStaticRule()</methodname> Methode kann verwendet werden um die Regel
                zu ändern:
            </para>

            <programlisting language="php"><![CDATA[
$inflector = new Zend_Filter_Inflector(':script.:suffix');
$inflector->setStaticRule('suffix', 'phtml');

// Später ändern:
$inflector->setStaticRule('suffix', 'php');
]]></programlisting>

            <para>
                So wie das Ziel selbst kann auch eine statische Regel an eine Referenz gebunden
                werden, was die Aktualisierung einer einzelnen Variablen erlaubt statt das ein
                Methodenaufruf benötigt wird; das ist oft nützlich wenn die Klasse intern eine
                Beugung verwendet, und die User den Beugungsmechanismus nicht holen sollen damit
                dieser aktualisiert werden kann. Die
                <methodname>setStaticRuleReference()</methodname> kann verwendet werden um das
                durchzuführen:
            </para>

            <programlisting language="php"><![CDATA[
class Foo
{
    /**
     * @var string Suffix
     */
    protected $_suffix = 'phtml';

    /**
     * Konstruktor
     * @return void
     */
    public function __construct()
    {
        $this->_inflector = new Zend_Filter_Inflector(':script.:suffix');
        $this->_inflector->setStaticRuleReference('suffix', $this->_suffix);
    }

    /**
     * Suffix setzen
     * aktualisiert die statische Suffix Regel im Beugungsmechanismus
     *
     * @param  string $suffix
     * @return Foo
     */
    public function setSuffix($suffix)
    {
        $this->_suffix = $suffix;
        return $this;
    }
}
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.inflector.rules.filters">
            <title>Beugungsregeln filtern</title>

            <para>
                Die Filter von <classname>Zend_Filter</classname> können auch als Beugungsregeln
                verwendet werden. Genauso wie bei statische Regeln werden Sie an eine Zielvariable
                gebunden; anders als statische Regeln können mehrfache Filter definiert werden die
                zur Beugung verwendet werden. Diese Filter werden in der Reihenfolge ausgeführt,
                weswegen man vorsichtig sein sollte und Sie in der Reihenfolge registriert die für
                die Daten die empfangen werden sollen Sinn machen.
            </para>

            <para>
                Regeln können durch Verwendung von <methodname>setFilterRule()</methodname>
                hinzugefügt werden (was alle vorhergehenden Regeln für diese Variable überschreibt)
                oder <methodname>addFilterRule()</methodname> (was die neue Regel zu jeder
                existierenden Regel für diese Variable hinzufügt). Filter werden in einem der
                folgenden Wege spezifiziert:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>String</emphasis>. Der String kann ein Klassenname eines Filters,
                        oder ein Segment des Klassennamens ohne jeglichem Präfix sein der im
                        Beugungs Plugin Lader gesetzt ist (standardmäßig, ohne den 'Zend_Filter'
                        Präfix).
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Filter Objekt</emphasis>. Jede Objekt Instanz die
                        <classname>Zend_Filter_Interface</classname> implementiert kann als ein
                        Filter übergeben werden.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>Array</emphasis>. Ein Array von einem oder mehreren Strings oder
                        Filterobjekten wie vorher definiert.
                    </para>
                </listitem>
            </itemizedlist>

            <programlisting language="php"><![CDATA[
$inflector = new Zend_Filter_Inflector(':script.:suffix');

// Setzt eine Regel um den Zend_Filter_Word_CamelCaseToDash Filter zu verwenden
$inflector->setFilterRule('script', 'Word_CamelCaseToDash');

// Eine Regel hinzufügen um Strings kleinzuschreiben
$inflector->addFilterRule('script', new Zend_Filter_StringToLower());

// Regeln en-masse setzen
$inflector->setFilterRule('script', array(
    'Word_CamelCaseToDash',
    new Zend_Filter_StringToLower()
));
]]></programlisting>
        </sect3>

        <sect3 id="zend.filter.inflector.rules.multiple">
            <title>Viele Regeln auf einmal setzen</title>

            <para>
                Typischerweise ist es einfacher viele Regeln auf einmal zu setzen als eine einzelne
                Variable und die Beugungsregeln auf einmal zu konfigurieren.
                <classname>Zend_Filter_Inflector</classname>'s <methodname>addRules()</methodname>
                und <methodname>setRules()</methodname> Methode erlaubt dies.
            </para>

            <para>
                Jede Methode nimmt ein Array von Variable/Regel Paaren, wobei die Regel alles sein
                kann was der Typ der Regel akzeptiert (String, Filterobjekt, oder Array).
                Variablennamen akzeptieren eine spezielle Schreibweise um das Setzen von statischen
                Regeln und Filterregeln zu erlauben, entsprechend der folgenden Schreibweise:
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>':' prefix</emphasis>: Filterregeln.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <emphasis>kein Präfix</emphasis>: statische Regel.
                    </para>
                </listitem>
            </itemizedlist>

            <example id="zend.filter.inflector.rules.multiple.example">
                <title>Mehrere Regeln auf einmal setzen</title>

                <programlisting language="php"><![CDATA[
// Es kann auch setRules() mit dieser Schreibweise verwendet werden:
$inflector->addRules(array(
    // Filterregeln:
    ':controller' => array('CamelCaseToUnderscore','StringToLower'),
    ':action'     => array('CamelCaseToUnderscore','StringToLower'),

    // Statische Regel:
    'suffix'      => 'phtml'
));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.filter.inflector.utility">
        <title>Hilfsmethoden</title>

        <para>
            <classname>Zend_Filter_Inflector</classname> hat eine Anzahl von Hilfsmethoden für das
            Empfangen und Setzen der Plugin Laders, die Manipulation und das Empfangen von Regeln,
            und die Kontrolle ob und wann Ausnahmen geworfen werden.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setPluginLoader()</methodname> kann verwendet werden wenn ein
                    eigener Plugin Loader konfiguriert werden soll der mit
                    <classname>Zend_Filter_Inflector</classname> verwendet werden soll;
                    <methodname>getPluginLoader()</methodname> empfängt den aktuell gesetzten.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>setThrowTargetExceptionsOn()</methodname> kann verwendet werden um
                    zu kontrollieren ob <methodname>filter()</methodname> eine Ausnahme wirft, oder
                    nicht, wenn ein übergegebener Identifizierer der ersetzt werden soll nicht im
                    Ziel gefunden wird. Standardmäßig wird keine Ausnahme geworfen.
                    <methodname>isThrowTargetExceptionsOn()</methodname> zeigt wie der aktuelle
                    Wert ist.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getRules($spec = null)</methodname> kann verwendet werden um alle
                    registrierten Regeln für alle Variablen zu empfangen, oder nur die Regeln für
                    eine einzelne Variable.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>getRule($spec, $index)</methodname> holt eine einzelne Regel für
                    eine gegebene Variable; das kann nützlich sein für das Holen einer spezifischen
                    Filterregel für eine Variable die eine Filterkette hat.
                    <varname>$index</varname> muß übergeben werden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <methodname>clearRules()</methodname> löscht alle aktuell registrierten Regeln.
                </para>
            </listitem>
        </itemizedlist>
    </sect2>

    <sect2 id="zend.filter.inflector.config">
        <title>Zend_Config mit Zend_Filter_Inflector verwenden</title>

        <para>
            <classname>Zend_Config</classname> kann verwendet werden um Regeln, Filter Präfix Pfade,
            oder andere Objektstati im Beugungsmachanismus zu setzen, entweder durch die Übergabe
            eines <classname>Zend_Config</classname> Objekts zum Konstruktor, oder durch
            <methodname>setConfig()</methodname>. Die folgenden Einstellungen können spezifiziert
            werden:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>target</code> spezifiziert das Beugungsziel.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>filterPrefixPath</code> spezifiziert ein oder mehrere Filter Präfix/Pfad
                    Paare für die Verwendung mit dem Beugungsmechanismus.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>throwTargetExceptionsOn</code> sollte ein Boolscher Wert sein der anzeigt
                    ob eine Ausnahme geworfen wird, oder nicht geworfen wird, wenn ein
                    Idenzifizierer der ersetzt werden soll nach der Beugung noch immer vorhanden
                    ist.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>targetReplacementIdentifier</code> spezifiziert das Zeichen das verwendet
                    wird wenn Ersetzungsvariablen im Zielstring identifiziert werden.
                </para>
            </listitem>

            <listitem>
                <para>
                    <code>rules</code> spezifiziert ein Array von Beugungsregeln; es sollte aus
                    Schlüsseln bestehen die entweder Werte oder Arrays von Werten spezifizieren, die
                    mit <methodname>addRules()</methodname> übereinstimmen.
                </para>
            </listitem>
        </itemizedlist>

        <example id="zend.filter.inflector.config.example">
            <title>Zend_Config mit Zend_Filter_Inflector verwenden</title>

            <programlisting language="php"><![CDATA[
// Mit dem Konstruktor:
$config    = new Zend_Config($options);
$inflector = new Zend_Filter_Inflector($config);

// Oder mit setConfig():
$inflector = new Zend_Filter_Inflector();
$inflector->setConfig($config);
]]></programlisting>
        </example>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->
