Zend Framework 1.7.9 Manual

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.

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.

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

Wenn isValid() false zurück gibt, bietet getMessages() 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 const Definition die jedem Identifikator für eine fehlgeschlagene Prüfung entspricht.

Note:

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

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

$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";
    }
}

Prüf Klassen bieten eine setMessage() Methode mit der das Format der Nachricht definiert werden kann die von getMessages() 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 %value% wird von allen Prüfungen unterstützt; es ist verbunden mit dem Wert der an isValid() übergeben wird. Andere Kürzel können unterstützt werden von Fall-zu-Fall in jeder Prüfer-Klasse. Zum Beispiel ist %max% das Kürzel welches von Zend_Validate_LessThan unterstützt wird. Die getMessageVariables() Methode give ein Array von variablen Kürzel zurück welche vom Prüfer unterstützt werden.

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 setMessage() 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. Das zweite optionale Argument ist ein String der mit dem Fehler Identifizierer korrespondiert der von der getErrors() Methode zurückgegeben wird. Wenn das zweite Argument ausgelassen wird nimmt setMessage() an das die Nachricht die spezifiziert wurde für die erste definierte Nachricht genommen werden soll die in der Prüfer-Klasse definiert ist. Diese Prüfer-Klassen haben nur eine einzige Fehlernachricht, so das keine Notwendigkeit besteht die definierten Nachricht speziell auszuwählen.

$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"
}

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

$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'
));

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 value Eigenschaft ist immer in einem Prüfer vorhanden; Das ist der Wert der als Argument von isValid() definiert wurde. Andere Eigenschaften können von Fall zu Fall in jeder Prüfklasse unterstützt werden.

$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";
}

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

if (Zend_Validate::is($email, 'EmailAddress')) {
    // Ja, die Email Adresse scheint gültig zu sein
}

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

if (Zend_Validate::is($value, 'Between', array(1, 12))) {
    // Ja, $value ist zwischen 1 und 12
}

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

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 isValid() Methode aufgerufen wird.

Die Zend_Filter_Input Klasse erlaubt es auch mehrfache Filter und Prüfklassen zu instanzieren und bei Bedarf aufzurufen um Sets von Eingabedaten zu bearbeiten. Siehe Zend_Filter_Input.