assert Download“ – assert -Quellcode-Download

Behaupten

Eine einfache PHP-Bibliothek, die Zusicherungen und Schutzmethoden zur Eingabevalidierung (nicht zum Filtern!) in Geschäftsmodellen, Bibliotheken und Anwendungscode auf niedriger Ebene enthält. Mit der Bibliothek können Vor-/Nachbedingungen für Eingabedaten implementiert werden.

Die Idee besteht darin, die Menge an Code zum Implementieren von Zusicherungen in Ihrem Modell zu reduzieren und außerdem die Codepfade zum Implementieren von Zusicherungen zu vereinfachen. Wenn Zusicherungen fehlschlagen, wird eine Ausnahme ausgelöst, wodurch die Notwendigkeit von if-Klauseln in Ihrem Code entfällt.

Die Bibliothek verwendet aus gutem Grund weder Symfony- noch Zend-Validatoren: Die Prüfungen müssen Low-Level-, schneller und nicht objektorientierter Code sein, um überall dort eingesetzt werden zu können, wo es notwendig ist. Die Verwendung einer der beiden Bibliotheken erfordert die Instanziierung mehrerer Objekte mithilfe einer Gebietsschemakomponente, Übersetzungen usw. Es ist zu sehr aufgebläht.

Installation

Verwenden von Composer:

composer require beberlei/assert

Beispielverwendungen

 <?php
use Assert  Assertion ;

function duplicateFile ( $ file , $ times )
{
    Assertion :: file ( $ file );
    Assertion :: digit ( $ times );

    for ( $ i = 0 ; $ i < $ times ; $ i ++) {
        copy ( $ file , $ file . $ i );
    }
}

Echtzeitnutzung mit Azure Blob Storage:

 <?php
public function putBlob ( $ containerName = '' , $ blobName = '' , $ localFileName = '' , $ metadata = array (), $ leaseId = null , $ additionalHeaders = array ())
{
    Assertion :: notEmpty ( $ containerName , ' Container name is not specified ' );
    self :: assertValidContainerName ( $ containerName );
    Assertion :: notEmpty ( $ blobName , ' Blob name is not specified. ' );
    Assertion :: notEmpty ( $ localFileName , ' Local file name is not specified. ' );
    Assertion :: file ( $ localFileName , ' Local file name is not specified. ' );
    self :: assertValidRootContainerBlobName ( $ containerName , $ blobName );

    // Check file size
    if ( filesize ( $ localFileName ) >= self :: MAX_BLOB_SIZE ) {
        return $ this -> putLargeBlob ( $ containerName , $ blobName , $ localFileName , $ metadata , $ leaseId , $ additionalHeaders );
    }

    // Put the data to Windows Azure Storage
    return $ this -> putBlobData ( $ containerName , $ blobName , file_get_contents ( $ localFileName ), $ metadata , $ leaseId , $ additionalHeaders );
}

NullOr-Helfer

Eine Hilfsmethode ( Assertion::nullOr* ) wird bereitgestellt, um zu prüfen, ob ein Wert null ist ODER für die Behauptung gilt:

 <?php
Assertion :: nullOrMax ( null , 42 ); // success
Assertion :: nullOrMax ( 1 , 42 );    // success
Assertion :: nullOrMax ( 1337 , 42 ); // exception

Alle Helfer

Die Methode Assertion::all* prüft, ob alle bereitgestellten Werte für die Behauptung gelten. Es wird eine Ausnahme ausgelöst, wenn die Behauptung für einen der Werte nicht gilt:

 <?php
Assertion :: allIsInstanceOf ( array ( new stdClass, new stdClass), ' stdClass ' ); // success
Assertion :: allIsInstanceOf ( array ( new stdClass, new stdClass), ' PDO ' );      // exception

Assert::that() Verkettung

Die Verwendung der statischen API für Werte ist sehr ausführlich, wenn Werte anhand mehrerer Behauptungen überprüft werden. Ab 2.6.7 von Assert bietet die Assert -Klasse eine viel schönere Fluent-API für Assertionen, die mit Assert::that($value) beginnt und dann die Assertionen empfängt, die Sie über die Fluent-Schnittstelle aufrufen möchten. Sie müssen den $value nur einmal angeben.

 <?php
Assert :: that ( $ value )-> notEmpty ()-> integer ();
Assert :: that ( $ value )-> nullOr ()-> string ()-> startsWith ( " Foo " );
Assert :: that ( $ values )-> all ()-> float ();

Es gibt auch zwei Verknüpfungsfunktionen Assert::thatNullOr() und Assert::thatAll() die den „nullOr“- bzw. „all“-Helfer aktivieren.

Faule Behauptungen

In der Webentwicklung, insbesondere bei Formularen, kommt es häufig vor, dass Sie mehrere Fehler sammeln möchten, anstatt direkt beim ersten Fehler abzubrechen. Dafür sind faule Behauptungen da. Ihre API funktioniert genau wie die Fluent Assert::that() API, aber anstatt direkt eine Ausnahme auszulösen, sammeln sie alle Fehler und lösen die Ausnahme nur aus, wenn die Methode verifyNow() für das AssertSoftAssertion Objekt aufgerufen wird.

 <?php
Assert :: lazy ()
    -> that ( 10 , ' foo ' )-> string ()
    -> that ( null , ' bar ' )-> notEmpty ()
    -> that ( ' string ' , ' baz ' )-> isArray ()
    -> verifyNow ();

Die Methode that($value, $propertyPath) benötigt einen Eigenschaftspfad (Name), damit Sie im Nachhinein wissen, wie Sie die Fehler unterscheiden können.

Bei einem Fehler löst verifyNow() eine Ausnahme Assert\LazyAssertionException mit einer kombinierten Meldung aus:

 The following 3 assertions failed:
1) foo: Value "10" expected to be string, type integer given.
2) bar: Value "<NULL>" is empty, but non empty value was expected.
3) baz: Value "string" is not an array.

Sie können auch alle AssertionFailedException s abrufen, indem Sie getErrorExceptions() aufrufen. Dies kann beispielsweise nützlich sein, um eine Fehlerantwort für den Benutzer zu erstellen.

Für diejenigen, die bei Verwendung einer Lazy-Assertion-Kette mehrere Fehler für einen einzelnen Wert erfassen möchten, können Sie Ihrem Aufruf that tryAll folgen, um alle Assertionen für den Wert auszuführen und alle daraus resultierenden Fehlermeldungen zu fehlgeschlagenen Assertionen zu erfassen. Hier ist ein Beispiel:

 Assert :: lazy ()
    -> that ( 10 , ' foo ' )-> tryAll ()-> integer ()-> between ( 5 , 15 )
    -> that ( null , ' foo ' )-> tryAll ()-> notEmpty ()-> string ()
    -> verifyNow ();

Das Obige zeigt, wie Sie diese Funktionalität verwenden, um das Verhalten bei der Meldung von Fehlern fein abzustimmen. Um das Erkennen aller Fehler jedoch noch einfacher zu machen, können Sie auch tryAll aufrufen, bevor Sie Behauptungen wie unten aufstellen. Dies hilft, Methodenaufrufe zu reduzieren und hat das gleiche Verhalten wie oben.

 Assert :: lazy ()-> tryAll ()
    -> that ( 10 , ' foo ' )-> integer ()-> between ( 5 , 15 )
    -> that ( null , ' foo ' )-> notEmpty ()-> string ()
    -> verifyNow ();

Funktionale Konstruktoren

Die folgenden Funktionen existieren als Aliase für statische Assert -Konstruktoren:

Assertthat()
AssertthatAll()
AssertthatNullOr()
Assertlazy()

Die Verwendung der funktionalen oder statischen Konstruktoren ist eine ganz persönliche Präferenz.

Hinweis: Die funktionalen Konstruktoren funktionieren nicht mit einer Assertion -Erweiterung. Es ist jedoch trivial, diese Funktionen so neu zu erstellen, dass sie auf die erweiterte Klasse verweisen.

Liste der Behauptungen

 <?php
use Assert  Assertion ;

Assertion :: alnum (mixed $ value );
Assertion :: base64 (string $ value );
Assertion :: between (mixed $ value , mixed $ lowerLimit , mixed $ upperLimit );
Assertion :: betweenExclusive (mixed $ value , mixed $ lowerLimit , mixed $ upperLimit );
Assertion :: betweenLength (mixed $ value , int $ minLength , int $ maxLength );
Assertion :: boolean (mixed $ value );
Assertion :: choice (mixed $ value , array $ choices );
Assertion :: choicesNotEmpty (array $ values , array $ choices );
Assertion :: classExists (mixed $ value );
Assertion :: contains (mixed $ string , string $ needle );
Assertion ::count(array| Countable | ResourceBundle | SimpleXMLElement $ countable , int $ count );
Assertion :: date (string $ value , string $ format );
Assertion :: defined (mixed $ constant );
Assertion :: digit (mixed $ value );
Assertion :: directory (string $ value );
Assertion :: e164 (string $ value );
Assertion :: email (mixed $ value );
Assertion :: endsWith (mixed $ string , string $ needle );
Assertion :: eq (mixed $ value , mixed $ value2 );
Assertion :: eqArraySubset (mixed $ value , mixed $ value2 );
Assertion :: extensionLoaded (mixed $ value );
Assertion :: extensionVersion (string $ extension , string $ operator , mixed $ version );
Assertion :: false (mixed $ value );
Assertion :: file (string $ value );
Assertion :: float (mixed $ value );
Assertion :: greaterOrEqualThan (mixed $ value , mixed $ limit );
Assertion :: greaterThan (mixed $ value , mixed $ limit );
Assertion :: implementsInterface (mixed $ class , string $ interfaceName );
Assertion :: inArray (mixed $ value , array $ choices );
Assertion :: integer (mixed $ value );
Assertion :: integerish (mixed $ value );
Assertion :: interfaceExists (mixed $ value );
Assertion :: ip (string $ value , int $ flag = null );
Assertion :: ipv4 (string $ value , int $ flag = null );
Assertion :: ipv6 (string $ value , int $ flag = null );
Assertion :: isArray (mixed $ value );
Assertion :: isArrayAccessible (mixed $ value );
Assertion :: isCallable (mixed $ value );
Assertion ::isCountable(array| Countable | ResourceBundle | SimpleXMLElement $ value );
Assertion :: isInstanceOf (mixed $ value , string $ className );
Assertion :: isJsonString (mixed $ value );
Assertion :: isObject (mixed $ value );
Assertion :: isResource (mixed $ value );
Assertion :: isTraversable (mixed $ value );
Assertion :: keyExists (mixed $ value , string|int $ key );
Assertion :: keyIsset (mixed $ value , string|int $ key );
Assertion :: keyNotExists (mixed $ value , string|int $ key );
Assertion :: length (mixed $ value , int $ length );
Assertion :: lessOrEqualThan (mixed $ value , mixed $ limit );
Assertion :: lessThan (mixed $ value , mixed $ limit );
Assertion :: max (mixed $ value , mixed $ maxValue );
Assertion ::maxCount(array| Countable | ResourceBundle | SimpleXMLElement $ countable , int $ count );
Assertion :: maxLength (mixed $ value , int $ maxLength );
Assertion :: methodExists (string $ value , mixed $ object );
Assertion :: min (mixed $ value , mixed $ minValue );
Assertion ::minCount(array| Countable | ResourceBundle | SimpleXMLElement $ countable , int $ count );
Assertion :: minLength (mixed $ value , int $ minLength );
Assertion :: noContent (mixed $ value );
Assertion :: notBlank (mixed $ value );
Assertion :: notContains (mixed $ string , string $ needle );
Assertion :: notEmpty (mixed $ value );
Assertion :: notEmptyKey (mixed $ value , string|int $ key );
Assertion :: notEq (mixed $ value1 , mixed $ value2 );
Assertion :: notInArray (mixed $ value , array $ choices );
Assertion :: notIsInstanceOf (mixed $ value , string $ className );
Assertion :: notNull (mixed $ value );
Assertion :: notRegex (mixed $ value , string $ pattern );
Assertion :: notSame (mixed $ value1 , mixed $ value2 );
Assertion :: null (mixed $ value );
Assertion :: numeric (mixed $ value );
Assertion :: objectOrClass (mixed $ value );
Assertion :: phpVersion (string $ operator , mixed $ version );
Assertion :: propertiesExist (mixed $ value , array $ properties );
Assertion :: propertyExists (mixed $ value , string $ property );
Assertion :: range (mixed $ value , mixed $ minValue , mixed $ maxValue );
Assertion :: readable (string $ value );
Assertion :: regex (mixed $ value , string $ pattern );
Assertion :: same (mixed $ value , mixed $ value2 );
Assertion :: satisfy (mixed $ value , callable $ callback );
Assertion :: scalar (mixed $ value );
Assertion :: startsWith (mixed $ string , string $ needle );
Assertion :: string (mixed $ value );
Assertion :: subclassOf (mixed $ value , string $ className );
Assertion :: true (mixed $ value );
Assertion :: uniqueValues (array $ values );
Assertion :: url (mixed $ value );
Assertion :: uuid (string $ value );
Assertion :: version (string $ version1 , string $ operator , string $ version2 );
Assertion :: writeable (string $ value );

Denken Sie daran: Wenn ein Konfigurationsparameter erforderlich ist, wird er immer NACH dem Wert übergeben. Der Wert ist immer der erste Parameter.

Ausnahme- und Fehlerbehandlung

Wenn eine der Behauptungen fehlschlägt, wird eine AssertAssertionFailedException ausgelöst. Sie können an jede Assertion ein Argument namens $message übergeben, um die Ausnahmemeldung zu steuern. Jede Ausnahme enthält standardmäßig eine Standardnachricht und einen eindeutigen Nachrichtencode.

 <?php
use Assert  Assertion ;
use Assert  AssertionFailedException ;

try {
    Assertion :: integer ( $ value , " The pressure of gas is measured in integers. " );
} catch ( AssertionFailedException $ e ) {
    // error handling
    $ e -> getValue (); // the value that caused the failure
    $ e -> getConstraints (); // the additional constraints of the assertion.
}

AssertAssertionFailedException ist nur eine Schnittstelle und die Standardimplementierung ist AssertInvalidArgumentException , die die SPL InvalidArgumentException erweitert. Sie können die verwendete Ausnahme auf Paketebene ändern.

Benutzerdefinierte Ausnahmemeldungen

Sie können einen Rückruf als Nachrichtenparameter übergeben, sodass Sie Ihre eigene Nachricht nur dann erstellen können, wenn eine Behauptung fehlschlägt, und nicht jedes Mal, wenn Sie den Test ausführen.

Der Rückruf wird mit einem Array von Parametern versorgt, die für die Behauptung dienen.

Da einige Zusicherungen andere Zusicherungen aufrufen, muss Ihr Rückruf ein Beispiel für das Array sein, um festzustellen, welche Zusicherung fehlgeschlagen ist.

Das Array enthält einen Schlüssel namens ::assertion , der angibt, welche Assertion fehlgeschlagen ist.

Der Rückruf sollte die Zeichenfolge zurückgeben, die als Ausnahmemeldung verwendet wird.

Ihre eigene Assertion-Klasse

Um Ihre Bibliothek vor möglichen Fehlern, Fehlinterpretationen oder BC-Brüchen in Assert zu schützen, sollten Sie eine bibliotheks-/projektbasierte Assertion-Unterklasse einführen, in der Sie auch die ausgelöste Ausnahme überschreiben können.

Darüber hinaus können Sie die Methode AssertAssertion::stringify() überschreiben, um während der Fehlerbehandlung Ihre eigenen Interpretationen der Typen bereitzustellen.

 <?php
namespace MyProject ;

use Assert  Assertion as BaseAssertion ;

class Assertion extends BaseAssertion
{
    protected static $ exceptionClass = ' MyProjectAssertionFailedException ' ;
}