Skip to content

Doku Entwickler Validation

Jump to bottom
blackcoder87 edited this page Nov 23, 2024 · 20 revisions

Validation

Inhaltsverzeichnis

Einfache Nutzung

<?php
/**
 * @copyright Ilch 2.0
 */

namespace Modules\Example\Controllers;

use Ilch\Validation;

class Index extends \Ilch\Controller\Frontend
{
    public function indexAction()
    {
        // ...
    }

    public function saveAction()
    {
        // ...

        $validation = Validation::create($this->getRequest()->getPost(), [
            'name' => 'required',
            'email' => 'required|email',
            'address.street' => 'required',
            'address.zipcode' => 'required|integer',
        ]);

        if ($validation->isValid()) {
            // ...
        }

        // ...
    }
}

Dieses Beispiel zeigt, wie einfach die Validationklasse genutzt werden kann.

Mit den Fehlern arbeiten

Wenn die Validation fehlerhaft war, ist es wichtig zu wissen, wie man mit diesen Fehlern weiterarbeiten kann. Die einfachste Möglichkeit mit den Fehlern zu arbeiten ist es, sich die ErrorBag-Instanz der Validation zu holen.

<?php
    //...

    $errorBag = $validation->getErrorBag();

    //...

Die ErrorBag-Instanz bietet einige Methoden, die das Ausgeben und Prüfen der Fehler vereinfacht.

Auf vorhandene Fehler prüfen

<?php
    //...

    $errorBag->hasErrors();

    //...

Gibt, wie der Name vermuten lässt, einen booleschen Wert zurück. True, wenn Fehler vorhanden sind, oder False, wenn keine vorhanden sind.

Fehlermeldungen auslesen

<?php
    //...

    $errorBag->getErrorMessages();

    //...

Diese Methode gibt ein Array mit allen bereits übersetzten Fehlermeldungen zurück. Wenn keine Fehlermeldungen vorhanden sind, wird ein leeres Array zurück gegeben. Dies verhindert u.a. Fehlermeldungen bei der Nutzung einer foreach()-Schleife.

Prüfen, ob ein bestimmtes Feld einen Fehler hat

<?php
    //...

    $errorBag->hasError('name');

    //...

Diese Method gibt einen booleschen Wert zurück. Als Parameter wird der Name eines Formularfeldes als Zeichenkette erwartet. Diese Funktion ist sinnvoll, wenn man Formularfelder mit, z.B. Bootstrap, entsprechend ihres Validationstatuses gestalten möchte. Beispiel:

&lt;div class="form-group<?= !$errorBag->hasError('name') ?: ' has-error' ?>">

Verfügbare Validatoren

Aktuell sind die folgenden Validatoren vorhanden:

  • captcha
  • date
  • domain
  • email
  • exists
  • integer
  • max
  • min
  • numeric
  • required
  • same
  • size
  • timezone
  • unique
  • url

Mehr zum jeweiligen Validator gibt es im entsprechenden Absatz.

Captcha

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'captchaField' => 'captcha',
]);

// ...

Dieser Validator prüft, ob die Zeichenkette im Feld captchaField dem generierten Captcha entspricht. Er hat keine weiteren Parameter.

Fehlermeldungen
  • validation.errors.captcha.wrongCaptcha

Date

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'dateField' => 'date',
]);

// ...

Dieser Validator prüft, ob das angegebene Datum gültig ist.

Standardmäßig wird geprüft, ob das Datum das Format "Y-m-d" hat. Dem Validator kann das gewünschte Format übergeben werden.

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'dateField' => 'date:d.m.Y',
]);

// ...
Fehlermeldungen
  • validation.errors.date.mustBeDate

Domain

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'domain' => 'domain',
]);

// ...

Dieser Validator prüft, ob es sich um eine gültige Domain handelt.

Standardmäßig wird auf eine gültige Domain geprüft. Auf Wunsch kann geprüft werden, ob die Domain auch ein gültiger Hostname ist.

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'domain' => 'domain:hostname',
]);

// ...
Fehlermeldungen
  • validation.errors.domain.noValidDomain

Email

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'emailField' => 'email',
]);

// ...

Der Email-Validator prüft, ob die in emailField befindliche E-Mail eine gültige E-Mail-Adresse ist.

Wichtig: In diesem Fall zählt ein leeres emailField als valider Wert. Soll eine gültige E-Mail-Adresse jedoch ein Pflichtfeld sein, muss zusätzlich der required-Validator verwendet werden.

Fehlermeldungen
  • validation.errors.email.noValidEmail

Exists

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'existsField' => 'exists:groups,name,id,1',
]);

// ...

Mit diesem Validator kann ein/mehrere Feld/Felder in der Datenbank auf existens überprüft werden

Aufbau
  1. Datenbank Feld
  2. Feld-Spalte
  3. Feld-Spalte,Wert

Der dritte Punkt kann beliebig wiederholt angegeben werden

Unterstützt Invertierung/Negierung durch Voranstellung von "NOT".

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'existsField' => 'NOTexists:groups,name,id,1',
]);

// ...
Fehlermeldungen
  • validation.errors.exists.resourceNotFound
  • Bei Invertierung/Negierung: validation.errors.exists.resourceFound

Integer

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'integerField' => 'integer',
]);

// ...

Hier wird einfach nur geprüft, ob es sich bei dem Wert von integerField um eine Ganzzahl handelt.

Wichtig: In diesem Fall zählt ein leeres integerField als valider Wert. Soll ein gültiger Zahlenwert jedoch ein Pflichtfeld sein, muss zusätzlich der required-Validator verwendet werden.

Unterstützt Invertierung/Negierung durch Voranstellung von "NOT".

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'integerField' => 'NOTinteger',
]);

// ...
Fehlermeldungen
  • validation.errors.integer.mustBeInteger
  • Bei Invertierung/Negierung: validation.errors.integer.dontBeInteger

Max

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'name' => 'max:5',
]);

// ...

Dieser Validator prüft den Inhalt von Feld name auf eine maximale Größe von 5.

Numerische Werte

Wenn es sich bei dem Inhalt von name um einen numerischen Wert handelt, dann wird auch auf Basis diese numerischen Wertes geprüft. Das heißt, dass in diesem Fall alles über dem Wert 5 zu einem Fehler führen würde.

Arrays

Handelt es sich um ein Array, also z.B. ein <select>, mit dem mehrere Wert ausgewählt werden können, dann prüft der Validator, ob maximal fünf Optionen ausgewählt wurden.

Zeichenketten

Soll es sich bei dem Inhalt um eine Zeichenkette handeln, so sollte der Validationsregel der Parameter string mitgegeben werden ('max:5,string'). Dieser Parameter sorgt dafür, dass auch Werte von 12345 als Zeichenkette behandelt werden, da diese normalerweise als numerischer Wert zählen würden und somit einen Fehler werfen würden.

Fehlermeldungen
  • validation.errors.max.numeric
  • validation.errors.max.array
  • validation.errors.max.string

Min

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'name' => 'min:5',
]);

// ...

Dieser Validator prüft den Inhalt von Feld name auf eine minimale Größe von 5.

Numerische Werte

Wenn es sich bei dem Inhalt von name um einen numerischen Wert handelt, dann wird auch auf Basis diese numerischen Wertes geprüft. Das heißt, dass in diesem Fall alles unter dem Wert 5 zu einem Fehler führen würde.

Arrays

Handelt es sich um ein Array, also z.B. ein <select>, mit dem mehrere Wert ausgewählt werden können, dann prüft der Validator, ob mindestens fünf Optionen ausgewählt wurden.

Zeichenketten

Soll es sich bei dem Inhalt um eine Zeichenkette handeln, so sollte der Validationsregel der Parameter string mitgegeben werden ('min:5,string'). Dieser Parameter sorgt dafür, dass auch Werte von 1234 als Zeichenkette behandelt werden, da diese normalerweise als numerischer Wert zählen würden und somit keinen Fehler werfen würden.

Fehlermeldungen
  • validation.errors.min.numeric
  • validation.errors.min.array
  • validation.errors.min.string

Numeric

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'numericField' => 'required|numeric',
]);

// ...

Hier wird einfach nur geprüft, ob es sich bei dem Wert von numericField um einen numerischen Wert handelt. Numerische Werte sind alle Ganzzahlen oder auch Fließkommazahlen, also z.B. 5, 5.5, 2.32135, aber nicht 5,5.

Wichtig: In diesem Fall zählt ein leeres numericField als valider Wert. Soll ein gültiger Zahlenwert jedoch ein Pflichtfeld sein, muss zusätzlich der required-Validator verwendet werden.

Unterstützt Invertierung/Negierung durch Voranstellung von "NOT".

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'numericField' => 'required|NOTnumeric',
]);

// ...
Fehlermeldungen
  • validation.errors.numeric.mustBeNumeric
  • Bei Invertierung/Negierung: validation.errors.numeric.dontBeNumeric

Required

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'name' => 'required',
]);

// ...

Dies ist wohl der meistgenutzte Validator überhaupt. Er prüft, ob das Feld name ausgefüllt wurde.

Unterstützt Invertierung/Negierung durch Voranstellung von "NOT".

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'numericField' => 'NOTrequired',
]);

// ...
Fehlermeldungen
  • validation.errors.required.fieldIsRequired
  • Bei Invertierung/Negierung: validation.errors.required.fieldIsNotRequired

Same

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'password' => 'required',
    'password_confirmation' => 'same:password',
]);

// ...

Dieser Validator prüft, ob das Feld password_confirmation den gleichen Wert wie das Feld password hat.

Unterstützt Invertierung/Negierung durch Voranstellung von "NOT".

Fehlermeldungen
  • validation.errors.same.fieldsDontMatch
  • Bei Invertierung/Negierung: validation.errors.same.fieldsMatch

Size

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'name' => 'size:5',
]);

// ...

Dieser Validator prüft den Inhalt von Feld name auf eine exakte Größe von 5.

Numerische Werte

Wenn es sich bei dem Inhalt von name um einen numerischen Wert handelt, dann wird auch auf Basis diese numerischen Wertes geprüft. Das heißt, dass in diesem Fall alles außer dem Wert 5 zu einem Fehler führen würde.

Arrays

Handelt es sich um ein Array, also z.B. ein <select>, mit dem mehrere Wert ausgewählt werden können, dann prüft der Validator, ob exakt fünf Optionen ausgewählt wurden.

Zeichenketten

Soll es sich bei dem Inhalt um eine Zeichenkette handeln, so sollte der Validationsregel der Parameter string mitgegeben werden ('size:5,string'). Dieser Parameter sorgt dafür, dass auch Werte von 12345 als Zeichenkette behandelt werden, da diese normalerweise als numerischer Wert zählen würden und somit einen Fehler werfen würden.

Fehlermeldungen
  • validation.errors.size.numeric
  • validation.errors.size.array
  • validation.errors.size.string

Timezone

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'timezone' => 'timezone',
]);

// ...

Dieser Validator prüft, ob es sich um eine gültige Zeitzone handelt.

Standardmäßig wird auf eine aktuell gültige Zeitzone geprüft. Auf Wunsch können aus Gründen der Abwärtskompatibilität auch inzwischen nicht mehr gültige Zeitzonen akzeptiert werden.

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'timezone' => 'timezone,backwardsCompatible',
]);

// ...
Fehlermeldungen
  • validation.errors.timezone.notAValidTimezone

Unique

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'email' => 'required|unique:users',
]);

// ...

Dieser Validator prüft, ob der Wert des Feldes email bereits in der Datenbank vorhanden ist. Als ersten Parameter wird die Tabelle in der Datenbank angegeben, in diesem Fall [prefix]_users.

Unterstützt Invertierung/Negierung durch Voranstellung von "NOT".

Andere Spalte in der Datenbank

Normalerweise wird davon ausgegangen, dass die Spalte den gleichen Namen hat, wie das Formularfeld, also in diesem Fall email. Sollte dies einmal nicht der Fall sein, kann ein weiterer Parameter mit dem Namen der Spalte angefügt werden.

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'email' => 'required|unique:users,emailaddress',
]);

// ...

In diesem Fall würde nun geprüft werden, ob der Inhalt des Feldes email bereits irgendwo in der Tabelle [prefix]_users in der Spalte emailaddress vorhanden ist.

Einen Datensatz von der Überprüfung ausnehmen

Ein weiteres Szenario ist das Bearbeiten eines bestehenden Datensatzes. Wendet man in diesem Fall den unique-Validator an, bekommt man zwangsweise einen Fehler, da sich die E-Mail-Adresse bereits in der Datenbank befindet.

Da man den Datensatz lediglich verändern will und keinen weiteren mit diesem Wert hinzufügen will, kann man einen weiteren Parameter anhängen, der einen bestimmten Datensatz von der Überprüfung ausnimmt.

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'email' => 'required|unique:users,emailaddress,1',
]);

// ...

In diesem Fall würde nun der Datensatz mit der Id 1 nicht überprüft. Wäre also die emailaddress des Datensatzes mit der Id 1 die gleiche, wie im Feld email, würde es keinen Fehler geben, da dieser Datensatz eine Ausnahme bildet.

Handelt es sich bei dem Feld, das eine Ausnahme angeben soll, nicht um die Spalte id, kann mit einem weiteren Parameter auch dieser Wert überschrieben werden.

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'email' => 'required|unique:users,emailaddress,1,user_id',
]);

// ...

So würde nun der Datensatz mit der user_id=1 nicht in die Überprüfung einfließen.

Fehlermeldungen
  • validation.errors.unique.valueExists
  • Bei Invertierung/Negierung: validation.errors.unique.valueNotExists

Url

<?php
// ...

$validation = Validation::create($this->getRequest()->getPost(), [
    'homepage' => 'required|url',
]);

// ...

Hier wird einfach nur geprüft, ob es sich bei dem Wert von homepage um eine gültige URL handelt.

Wichtig: In diesem Fall zählt ein leeres homepage Feld als valider Wert. Soll eine gültige Homepage jedoch ein Pflichtfeld sein, muss zusätzlich der required-Validator verwendet werden.

Fehlermeldungen
  • validation.errors.url.noValidUrl

Eigene Validatoren

Eigene Validatoren können ganz einfach erstellt werden. Zunächst müssen sie jedoch von \Ilch\Validation\Validators\Base erben.

Als Beispiel, wie ein Validator mindestens aufgebaut sein muss, dient der Integer-Validator:

<?php
/**
 * @copyright Ilch 2.0
 */

namespace Ilch\Validation\Validators;

/**
 * Integer validation class.
 */
class Integer extends Base
{
    /**
     * Default error key for this validator.
     *
     * @var string
     */
    protected $errorKey = 'validation.errors.integer.mustBeInteger';

    /**
     * Runs the validation.
     *
     * @return self
     */
    public function run()
    {
        $this->setIsValid($this->getValue() === '' || filter_var($this->getValue(), FILTER_VALIDATE_INT) !== false);

        return $this;
    }
}

Im Einzelnen:

protected $errorKey = 'validation.errors.integer.mustBeInteger';

Hier muss ein gültiger Übersetzungsschlüssel eingetragen werden. Dieser dient als Standardfehlermeldung, wenn keine andere Fehlermeldung gesetzt wird. Dies kann nämlich mit $this->setErrorKey('new.validation.error.translation.key') überall in der Validatorklasse überschrieben werden.

Die Validationklasse ruft immer nur die run()-Methode des Validators auf. Sie muss immer die aktuelle Validatorinstanz ($this) zurückgeben.

Inhalte bekommen

<?php
    //...

    $this->getField(); // Das Feld, das durch den Validator geprüft wird
    $this->getValue(); // Gibt den Wert des zu prüfenden Feldes zurück
    $this->getInput(); // Gibt ein Array mit allen der Validation gegebenen Inhalte zurück ($this->getRequest()->getPost())
    $this->getParameters(); // Gibt ein Array mit allen Parametern des Validators zurück
    $this->getParameter($n); // Gibt den Paramter '$n' zurück, wenn dieser nicht existiert, wird null zurückgegeben. (z.B. 0, 1, 2, 3)

    //...

Ergebnis setzen

Das Ergebnis der Validation wird immer mit $this->setIsValid(true) // or false gesetzt.

Weitere Parameter für die Übersetzung übergeben

Manchmal möchte man der Übersetzung noch weitere Parameter übergeben, dies ist z.B. der Fall, wenn man etwas auf eine bestimmte Länge prüft und in der Fehlermeldung die notwendige Länge angeben möchte (Feld muss mindestens 10 Zeichen lang sein, nicht 5.). Dies geschieht mit $this->setErrorParameters([10, 5]).

Es muss immer ein Array an die Methode setErrorparameters übergeben werden.

Feldnamenübersetzung überschreiben

Stimmen Feldnamen und Übersetzungsschlüssel nicht überein, können die Übersetzungsschlüssel auch überschrieben werden.

<?php
    //...
        Validation::setCustomFieldAliases([
            'homepage' => 'page',
        ]);
    //...

Wichtig ist, dass dies vor dem Erstellen der Validation (Validation::create()) ausgeführt werden muss. In diesem Fall wird der Übersetzungsschlüssel des Feldes homepage von homepage auf page geändert.

Fehlermeldungen überschreiben

Alle Fehlermeldungen können durch eigene Fehlermeldungen ersetzt werden.

<?php
    //...
        Validation::setCustomErrorKeys([
            'name' => [
                'required' => [
                    'validation.errors.required.fieldIsRequired' => 'guestbook.custom.error',
                ],
                'min' => [
                    'validation.errors.min.string' => 'another.custom.error',
                ],
            ],
        ]);
    //...

In diesem Fall werden nur beim Feld name die Fehlermeldungen validation.errors.required.fieldIsRequired des required-Validators sowie validation.errors.min.string des min-Validators überschrieben.

Die möglichen Fehlermeldungen können aus den entsprechenden Absätzen über die einzelnen Validatoren entnommen werden.

BreakChain

Normalerweise wird die Ausführung von Validatoren eines bestimmten Feldes gestoppt, wenn ein Validator fehlschlägt.

Möchte man dieses Verhalten überschreiben, kann vor Ausführung der Validation (Validation::create()), breakChain deaktiviert werden.

<?php
    Validation::setBreakChain(false);

Dokumentation für ilch 2 | Content-Management-System | Copyright © 2004-2024 by ilch.de

Wiki für ilch-2

Benutzer

  • Inhaltsverzeichnis
    Hier findet man u.a. die Installationsanleitung, sowie Fehler- und Problem-behebungen

Entwickler

  • Inhaltsverzeichnis
    Hier findet man Informationen zum Script, Konzept und dem Programmierstil

Designer

  • Inhaltsverzeichnis
    Hier findet man Informationen über den Aufbau und Anpassung von Layouts und Modulen

Video-Tutorials


Clone this wiki locally