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

<?xml version="1.0" encoding="UTF-8"?>
<!-- EN-Revision: 15207 -->
<!-- Reviewed: no -->
<sect1 id="zend.validate.introduction">

    <title>Einführung</title>

    <para>
        Die Zend_Validate Komponente bietet ein Set von üblich verwendeten Prüfungen. Sie bietet auch einen einfachen
        Prüf-Ketten-Mechanismus mit welchem mehrfache Prüfungen zu einem einfachen Wert in einer benutzer-definierten
        Art und Weise zugeordnet werden können.
    </para>

    <sect2 id="zend.validate.introduction.definition">

        <title>Was ist eine Prüfung?</title>

        <para>
            Eine Prüfung untersucht seine Eingabe mit Obacht auf einige Anforderungen und produziert ein boolsches
            Ergebnis - wenn die Eingabe erfolgreich gegen die Anforderungen geprüft werden konnte. Wenn die Eingabe
            den Anforderungen nicht entspricht, kann die Prüfung zusätzliche Informationen darüber bieten, welche
            der Anforderungen die Eingabe nicht entspricht.
        </para>

        <para>
            Eine WebAnwendung, zum Beispiel, könnte erfordern das ein Benutzername zwischen sechs und zwölf Zeichen
            lang ist und dürfte nur alphanummerische Zeichen  enthalten. Eine Prüfung kann dafür verwendet werden um
            sicherzustellen das Benutzernamen diesen Anforderungen entsprechen. Wenn ein gewählter Benutzername einer
            oder beiden Anforderungen nicht entspricht, wäre es nützlich zu wissen welche der Anforderungen der
            Benutzername nicht entsprochen hat.
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.using">

        <title>Standardnutzung von Prüfungen</title>

        <para>
            Prüfungen auf diesem Weg definiert zu haben, bietet die Sammlung für <classname>Zend_Validate_Interface</classname>
            welche zwei Methoden definiert, <code>isValid()</code> und <code>getMessages()</code>. Die
            <code>isValid()</code> Methode führt eine Prüfung über die angegebenen Werte aus, und gibt nur dann
            <code>true</code> zurück wenn der Wert gegenüber den Kriterien der Prüfung entsprochen hat.
        </para>

        <para>
            Wenn <code>isValid()</code> <code>false</code> zurück gibt, bietet <code>getMessages()</code> ein Array von
            Nachrichten welche die Gründe für die fehlgeschlagene Prüfung beschreiben. Die Arrayschlüssel sind
            kurze Strings die die Gründe für eine fehlgeschlagene Prüfung identifizieren, und die Arraywerte
            sind die entsprechend menschlich-lesbaren String Nachrichten. Die Schlüssel und Werte sind
            Klassenabhängig; jede Prüfklasse definiert Ihr eigenes Set von Nachrichten für fehlgeschlagene
            Prüfungen und die eindeutigen Schlüssel die diese identifizieren. Jede klasse hat also eine
            <code>const</code> Definition die jedem Identifikator für eine fehlgeschlagene Prüfung entspricht.
        </para>

        <note>
            <para>
                Die <code>getMessages()</code> gibt die Information für Prüfungsfehler nur für den zuletzt
                durchgeführten Aufruf von <code>isValid()</code> zurück. Jeder Aufruf von <code>isValid()</code>
                löscht jegliche Nachricht und Fehler welche durch vorhergehende <code>isValid()</code> Aufrufe
                vorhanden waren, weil normalerweise jeder Aufruf von <code>isValid()</code> für einen
                unterschiedlichen Eingabewert gemacht wird.
            </para>
        </note>

        <para>
            Das folgende Beispiel zeigt die Prüfung einer E-Mail Adresse:

            <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_EmailAddress();

if ($validator->isValid($email)) {
    //
    // E-Mail scheint gültig zu sein
    //
} else {
    //
    // E-Mail ist ungültig; drucke die Gründe
    //
    foreach ($validator->getMessages() as $messageId => $message) {
        echo "Validation failure '$messageId': $message\n";
    }
}
]]></programlisting>

        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.messages">

        <title>Nachrichten anpassen</title>

        <para>
            Prüf Klassen bieten eine <code>setMessage()</code> Methode mit der das Format der Nachricht
            definiert werden kann die von <code>getMessages()</code> im Fall einer fehlerhaften Prüfung
            zurückgegeben wird. Das erste Argument dieser Methode ist ein String der die Fehlernachricht
            enthält. Es können Kürzel in den String eingebaut werden welche mit den für die Prüfung relevanten
            Daten aufgefüllt werden. Das Kürzel <code>%value%</code> wird von allen Prüfungen unterstützt;
            es ist verbunden mit dem Wert der an <code>isValid()</code> übergeben wird.
            Andere Kürzel können unterstützt werden von Fall-zu-Fall in jeder Prüfer-Klasse. Zum Beispiel ist
            <code>%max%</code> das Kürzel welches von <classname>Zend_Validate_LessThan</classname> unterstützt wird.
            Die <code>getMessageVariables()</code> Methode give ein Array von variablen Kürzel zurück
            welche vom Prüfer unterstützt werden.
        </para>

        <para>
            Das zweite optionale Argument ist ein String der das Template der fehlerhaften Prüfnachricht
            die gesetzt werden soll identifiziert. Das ist nützlich wenn eine Prüfklasse mehr als einen
            Grund für einen Fehlschlag definiert. Wenn das zweite Argument nicht angegeben wird, nimmt
            <code>setMessage()</code> an das die spezifizierte Nachricht für das erste Messagetemplate
            verwendet werden soll das in der Prüfklasse definiert ist. Viele Prüfklassen haben nur ein
            Template für eine Fehlernachricht definiert, sodas es nicht notwendig ist anzugeben welches
            Template für Fehlernachrichten geändert werden soll.
        </para>

        <para>
            <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8);

$validator->setMessage(
    'Der String \'%value%\' ist zu kurz; er muss mindestens %min% ' .
    'Zeichen sein',
    Zend_Validate_StringLength::TOO_SHORT);

if (!$validator->isValid('word')) {
    $messages = $validator->getMessages();
    echo $messages[0];

    // "Der String 'word' ist zu kurz; er muss mindestens 8 Zeichen sein"
}
]]></programlisting>
        </para>

        <para>
            Es können mehrere Nachrichten gesetzt werden durch Verwendung der <code>setMessages()</code>
            Methode. Dessen Argument ist ein Array welches Schlüssel/Nachrichten Paare enthält.

            <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);

$validator->setMessages( array(
    Zend_Validate_StringLength::TOO_SHORT =>
        'Der String \'%value%\' ist zu kurz',
    Zend_Validate_StringLength::TOO_LONG  =>
        'Der String \'%value%\' ist zu lang'
));
]]></programlisting>

        </para>

        <para>
            Wenn die Anwendung mehr Flexibilität benötigt in der Art und Weise wie Prüffehler
            gemeldet werden, kann auf die Eigenschaften durch den selben Namen zugegriffen
            werden wie mit dem Nachrichten Kürzel das von einer Prüfklasse unterstützt wird.
            Die <code>value</code> Eigenschaft ist immer in einem Prüfer vorhanden; Das ist
            der Wert der als Argument von <code>isValid()</code> definiert wurde. Andere
            Eigenschaften können von Fall zu Fall in jeder Prüfklasse unterstützt werden.

            <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);

if (!validator->isValid('word')) {
    echo 'Wort fehlgeschlaten: '
        . $validator->value
        . '; die Länge ist nicht zwischen '
        . $validator->min
        . ' und '
        . $validator->max
        . "\n";
}
]]></programlisting>
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.static">

        <title>Verwenden der statischen is() Methode</title>

        <para>
            Wenn es nicht gebräuchlich ist eine gegebenen Prüfklasse zu laden und eine Instanz
            des Prüfers zu erstellen, kann die statische Methode <classname>Zend_Validate::is()</classname>
            verwendet werden als alternativer Stil des Aufrufs. Das erste Argument dieser
            Methode ist ein Datenwert, der an die <code>isValid()</code> Methode übergeben werden
            würde. Das zweite Argument ist ein String, welcher mit dem Basisnamen der Prüfklasse
            übereinstimmt, relativ zum Namensraum von <classname>Zend_Validate</classname>. Die <code>is()</code>
            Methode lädt die Klasse automatisch, erstellt eine Instanz und wendet die
            <code>isValid()</code> Methode an den Eingabedaten an.

            <programlisting role="php"><![CDATA[
if (Zend_Validate::is($email, 'EmailAddress')) {
    // Ja, die Email Adresse scheint gültig zu sein
}
]]></programlisting>

        </para>

        <para>
            Es kann auch ein Array von Konstruktor Argumenten übergeben werden, wenn diese für die
            Prüfung benötigt werden.

            <programlisting role="php"><![CDATA[
if (Zend_Validate::is($value, 'Between', array(1, 12))) {
    // Ja, $value ist zwischen 1 und 12
}
]]></programlisting>

        </para>

        <para>
            Die <code>is()</code> Methode gibt einen boolschen Wert zurück, denselben wie die
            <code>isValid()</code> Methode. Wird die statische <code>is()</code> Methode verwendet,
            sind Nachrichten für Prüffehler nicht vorhanden.
        </para>

        <para>
            Die statische Verwendung kann bequem sein für das ad hoc Verwenden eines Prüfers,
            aber wenn ein Prüfer für mehrere Eingaben verwendet werden soll ist es effizienter
            die nicht statische Verwendung zu benutzen, indem eine Instanz des Prüf Objektes
            erstellt wird und dessen <code>isValid()</code> Methode aufgerufen wird.
        </para>

        <para>
            Die <classname>Zend_Filter_Input</classname> Klasse erlaubt es auch mehrfache Filter und Prüfklassen
            zu instanzieren und bei Bedarf aufzurufen um Sets von Eingabedaten zu bearbeiten. Siehe
            <xref linkend="zend.filter.input" />.
        </para>

    </sect2>

    <sect2 id="zend.validate.introduction.translation">

        <title>Meldungen übersetzen</title>

        <para>
            Prüfungsklassen bieten eine <code>setTranslator()</code> Methode mit der man eine
            Instanz von <classname>Zend_Translate</classname> definieren kann die Nachrichten im Falle eines
            Prüfungsfehlers übersetzt. Die <code>getTranslator()</code> Methode gibt die gesetzte
            Übersetzungsinstanz zurück.
        </para>

        <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);
$translate = new Zend_Translate(
    'array',
    array(Zend_Validate_StringLength::TOO_SHORT => 'Übersetzt \'%value%\''),
    'en'
);

$validator->setTranslator($translate);
]]></programlisting>

        <para>
            Mit der statischen Methode <code>setDefaultTranslator()</code> kann eine Instanz von
            <classname>Zend_Translate</classname> gesetzt werden, und mit <code>getDefaultTranslator()</code>
            empfangen. Das verhindert das man den Übersetzer manuell für alle Prüfungsklassen
            setzen muß und vereinfacht den Code.
        </para>

        <programlisting role="php"><![CDATA[
$translate = new Zend_Translate(
    'array',
    array(Zend_Validate_StringLength::TOO_SHORT => 'Übersetzt \'%value%\''),
    'en'
);
Zend_Validate::setDefaultTranslator($translate);
]]></programlisting>

        <note>
            <para>
                Wenn man ein Anwendungsweites Gebietsschema in der Registry gesetzt hat, wird
                dieses Gebietsschema als standardmäßiger Übersetzer verwendet.
            </para>
        </note>

        <para>
            Machmal ist es notwendig den Übersetzer in einer Prüfklasse auszuschalten. Um das zu
            tun kann die <code>setDisableTranslator()</code> Methode verwendet werden, welche einen
            boolschen Wert akzeptiert und <code>translatorIsDisabled()</code> um den gesetzten
            Wert zu erhalten.
        </para>

        <programlisting role="php"><![CDATA[
$validator = new Zend_Validate_StringLength(8, 12);
if (!$validator->isTranslatorDisabled()) {
    $validator->setDisableTranslator();
}
]]></programlisting>

        <para>
            Es ist auch möglich einen Übersetzer zu verwenden statt eigene Meldungen mit
            <code>setMessage()</code> zu setzen. Aber wenn man das tut, sollte man im Kopf behalten
            das der Übersetzer auch mit den Meldungen arbeitet die man selbst gesetzt hat.
        </para>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->