request parser Download - request parser Source Code Download

Parser anfordern

Kleine PHP-Bibliothek für die Eingangsbehandlung vom Typ.

Das Problem
Beispiele
Erste Schritte
Integrationen
Symfony httpfoundation
PSR7
Optionale Parameter
Ganzzahlen, Aufzüge, DateTimes und JSON -Nutzlasten
Unterstützte Datentypen
Anfragen erhalten
Postanfragen
Autoperation
Statische Analyse
Fehlerbehandlung
Verwenden Sie benutzerdefinierte Ausnahmegeräte
Verwenden von benutzerdefinierten Ausnahmemachtungen
Ist es die Produktion bereit?
Tests
Beitragen

Das Problem

Angenommen, Sie haben eine Aktion, die einige Entitäten auflistet. Dies beinhaltet das Paging, Aufstieg oder absteigende Bestellung und optionale Filterung zum Zeitpunkt des Erstellens des Entität. Diese Aktion wird eine Art Eingabe -Parsen haben, was so aussehen kann:

 public function index ()
{
    $ page = $ this -> request -> query -> get ( ' page ' );
    if ( $ page === null || ! is_integer ( $ page )) {
        throw new Exception ( " Parameter page not found " );
    }
    
    $ order = $ this -> request -> query -> get ( ' order ' );
    if ( $ order === null || ! in_array ( $ order , [ ' asc ' , ' desc ' ])) {
        throw new Exception ( " Parameter order not found " );
    }
    
    // Optional parameter
    $ createdAt = $ this -> query -> query -> get ( ' createdAt ' );
    if ( is_string ( $ createdAt )) {
        $ createdAt = new DateTime ( $ createdAt );
    } else {
        $ createdAt = null ;
    }
}

Offensichtlich ist dieser Code nicht sehr schön zu lesen, weil er nicht sehr beschreibend ist. Es ist auch ziemlich ausführlich für das, was es tut. Und wenn Sie nicht genau darauf achten, werden Sie wahrscheinlich einen Null -Check oder einen Typprüfungen verpassen.

Vergleichen Sie nun den obigen Code mit dieser Version:

 public function index ()
{
    $ page = $ this -> queryParameter ( ' page ' )-> int ()-> required ();
    $ order = $ this -> queryParameter ( ' order ' )-> oneOf ([ ' asc ' , ' desc ' ])-> required ();
    $ createdAt = $ this -> queryParameter ( ' createdAt ' )-> dateTime ()-> defaultsTo ( null );
}

Das bietet diese Bibliothek. Sie können " Diese Aktion erfordert einen Seitenparameter vom Typ int " oder " Diese Aktion enthält einen optionalen Parameter, der von Typ DateTime erstellt wurde, und wird bei Abwesenheit auf einen Standardwert festgelegt ".

Beispiele

Wenn Sie jetzt direkt zum Code gehen möchten, können Sie einfach mit den Beispielen herumspielen.

cd /tmp
git clone [email protected]:mpscholten/request-parser.git
cd request-parser
composer install
cd examples
php -S localhost:8080
Öffnen Sie es: http: // localhost: 8080/symfony.php? Action = Hallo

Es gibt auch mehrere andere PHP -Dateien im Beispielverzeichnis. Um Ihre Hände schmutzig zu machen, schlage ich vor, nur die Beispiele ein wenig zu ändern.

Erste Schritte

Installieren Sie über Komponist

 composer require mpscholten/request-parser

Integrationen

Wenn Sie symfony/http-foundation verwenden, klicken Sie hier.
Wenn Sie eine PSR7 ServerRequestInterface -Implementierung verwenden, klicken Sie hier.
Wenn Sie eine andere Request verwenden (oder möglicherweise nur alte $_GET und Freunde), lesen Sie dieses Beispiel.

Symfony httpfoundation

Das folgende Beispiel wird davon ausgegangen, dass Sie die Symfony Request verwenden:

 class MyController
{
    use  MPScholten  RequestParser  Symfony ControllerHelperTrait;
    
    public function __construct ( Request $ request )
    {
        $ this -> initRequestParser ( $ request );
    }
}

Dann können Sie die Bibliothek wie diese verwenden:

 class MyController
{
    use  MPScholten  RequestParser  Symfony ControllerHelperTrait;
    
    public function __construct ( Request $ request )
    {
        $ this -> initRequestParser ( $ request );
    }
    
    public function myAction ()
    {
        $ someParameter = $ this -> queryParameter ( ' someParameter ' )-> string ()-> required ();
    }
}

Bei GET /MyController/myAction?someParameter=example enthält die $someParameter -Variable die Zeichenfolge "example" .

Sie fragen sich vielleicht, was passiert, wenn wir den Teil des ?someParameter weglassen, wie GET /MyController/myAction . In diesem Fall wirft das $this->queryParameter('someParameter')->string()->required() eine NotFoundException aus. Diese Ausnahme kann von Ihrer Anwendung behandelt werden, um eine Fehlermeldung anzuzeigen.

Schauen Sie sich die Beispiele an.

PSR7

Das folgende Beispiel wird davon ausgegangen, dass Sie das PSR7 ServerRequestInterface verwenden:

 class MyController
{
    use  MPScholten  RequestParser  Psr7 ControllerHelperTrait;
    
    public function __construct ( ServerRequestInterface $ request )
    {
        $ this -> initRequestParser ( $ request );
    }
}

Dann können Sie die Bibliothek wie diese verwenden:

 class MyController
{
    use  MPScholten  RequestParser  Psr7 ControllerHelperTrait;
    
    public function __construct ( ServerRequestInterface $ request )
    {
        $ this -> initRequestParser ( $ request );
    }
    
    public function myAction ()
    {
        $ someParameter = $ this -> queryParameter ( ' someParameter ' )-> string ()-> required ();
    }
}

Bei GET /MyController/myAction?someParameter=example enthält die $someParameter -Variable die Zeichenfolge "example" .

Schauen Sie sich die Beispiele an.

Optionale Parameter

Um den someParameter optional zu machen, können wir nur required() durch defaultsTo($someDefaultValue) ersetzen:

 class MyController
{
    use  MPScholten  RequestParser  Symfony ControllerHelperTrait;
    
    public function __construct ( Request $ request )
    {
        $ this -> initRequestParser ( $ request );
    }
    
    public function myAction ()
    {
        $ someParameter = $ this -> queryParameter ( ' someParameter ' )-> string ()-> defaultsTo ( ' no value given ' );
    }
}

Bei GET /MyController/myAction enthält die $someParameter -Variable nun die Zeichenfolge "no value given" . Es wird keine Ausnahme ausgelöst, da wir einen Standardwert angegeben haben.

Im Allgemeinen geben Sie zuerst den Parameternamen an, gefolgt vom Typ und dann, ob der Parameter erforderlich ist oder mit einem Standardwert optional ist.

Weitere Beispiele finden Sie in den examples/ dem Verzeichnis dieses Repositorys. Es enthält mehrere laufbare Beispiele.

Ganzzahlen, Aufzüge, DateTimes und JSON -Nutzlasten

Oft brauchen wir mehr als nur Saiten. RequestParser bietet auch Methoden für andere Datentypen:

 class DashboardController
{
    public function show ()
    {
        $ dashboardId = $ this -> queryParameter ( ' id ' )-> int ()-> required ();
        
        // GET /dashboard?name=Hello   =>   $dashboardName == "Hello"
        $ dashboardName = $ this -> queryParameter ( ' name ' )-> string ()-> required ();
        
        // Get /dashboard?name=   => $dashboardName == "default value"
        $ dashboardName = $ this -> queryParameter ( ' name ' )-> string ()-> defaultsToIfEmpty ( " default value " );
        
        // GET /dashboard?status=private  =>   $dashboardStatus == "private"
        // GET /dashboard?status=public   =>   $dashboardStatus == "public"
        // GET /dashboard?status=invalid  =>   A NotFoundException will be thrown
        $ dashboardStatus = $ this -> queryParameter ( ' status ' )-> oneOf ([ ' private ' , ' public ' ])-> required ();
        
        // GET /dashboard?createdAt=01.01.2016     =>   $dateTime == new DateTime("01.01.2016")
        // GET /dashboard?createdAt=invalid_date   =>   A NotFoundException will be thrown
        $ dateTime = $ this -> queryParameter ( ' createdAt ' )-> dateTime ()-> required ();
        
        // GET /dashboard?config={"a":true}     =>   $json == ['a' => true]
        $ json = $ this -> queryParameter ( ' config ' )-> json ()-> required ();
        
        // GET /dashboard?includeWidgets=true    =>   $includeWidgets == true
        // GET /dashboard?includeWidgets=false   =>   $includeWidgets == false
        // GET /dashboard?includeWidgets=0       =>   $includeWidgets == false
        // GET /dashboard?includeWidgets=abcde   =>   A NotFoundException will be thrown
        $ includeWidgets = $ this -> queryParameter ( ' includeWidgets ' )-> boolean ()-> required ();
        
        // GET /dashboard?includeWidgets=yes   =>   $includeWidgets == true
        // GET /dashboard?includeWidgets=no    =>   $includeWidgets == false
        $ includeWidgets = $ this -> queryParameter ( ' includeWidgets ' )-> yesNoBoolean ()-> required ();
        
        // GET /image?scale=2.5   =>   $scale == 2.5
        $ scale = $ this -> queryParameter ( ' scale ' )-> float ()-> required ();
    }
}

Alle diese Typen liefern auch eine defaultsTo -Variante.

Unterstützte Datentypen

Typ	Codebeispiel	Eingabebeispiel
Saite	`$this->queryParameter('name')->string()->required();`	`'John Doe'`
Komma getrennte Zeichenfolge	`$this->queryParameter('names')->commaSeparated()->string()->required();`	`'John Doe,John Oliver'`
Ganze Zahl	`$this->queryParameter('id')->int()->required();`	`'5'`
Komma getrennte Ganzzahl	`$this->queryParameter('groupIds')->commaSeparated()->int()->required();`	`'5,6,7,8'`
Schweben	`$this->queryParameter('ratio')->float()->required();`	`'0.98'`
Komma-getrennter Float	`$this->queryParameter('precipitation')->commaSeparated()->float()->required();`	`'0.98,1.24,5.21'`
Datetime	`$this->queryParameter('timestamp')->dateTime()->required();`	`'2016-07-20'`
Komma getrennte DateTime	`$this->queryParameter('eventTimes')->commaSeparated()->dateTime()->required();`	`'2016-07-20 13:10:50,2016-07-21 12:01:07'`
Boolean	`$this->queryParameter('success')->boolean()->required();`	`'true'`
Komma-getrennter Booleschen	`$this->queryParameter('answers')->commaSeparated()->boolean()->required();`	`'1,0,0,1'`
Ja/Nein Boolean	`$this->queryParameter('success')->yesNoBoolean()->required();`	`'yes'`
Komma-getrennter Ja/Nein Boolean	`$this->queryParameter('answers')->commaSeparated()->yesNoBoolean()->required();`	`'y,n,n,y,n'`
JSON	`$this->queryParameter('payload')->json()->required();`	`'{"event":"click","timestamp":"2016-07-20 13:10:50"}'`
Komma-getrennter JSON	`$this->queryParameter('events')->commaSeparated()->json()->required();`	`'{"event":"click","timestamp":"2016-07-20 13:10:50"},{"event":"add_to_basket","timestamp":"2016-07-20 13:11:01"}'`

Erhalten Sie Anfragen:

$this->queryParameter($name) teilt dem Controller mit, dass wir einen Abfrageparameter wollen (alles nach der "?" heißt Abfragezeichenfolge). Dies ist normalerweise das, was wir beim Umgang mit Get -Anfragen wollen

Postanfragen:

Wenn wir uns mit einer Postanfrage befassen, müssen wir $this->bodyParameter($name) verwenden, um auf Formularfelder oder die AJAX-Nutzlast zuzugreifen.

Autoperation

Mit der Bibliothek können Sie eine umfassende Verwendung von Autokompetenzfunktionen Ihrer IDE verwenden. ZB nach dem Eingeben von $this->queryParameter('someParameter)-> Ihre IDE bietet Ihnen alle möglichen Eingangstypen, z. B. string() oder int() . Nach der Auswahl eines Typs, z. B. string() , bietet Ihre IDE required() oder defaultsTo(defaultValue) an, um das Verhalten anzugeben, wenn der Parameter nicht festgelegt ist.

Statische Analyse

Die Bibliothek unterstützt eine statische Analyse durch Ihre IDE. ZB, wenn ein Parameter wie $createdAt = $this->queryParameter('createdAt')->dateTime()->required(); Ihre IDE wird wissen, dass $createdAt ein DateTime -Objekt ist. Auf diese Weise können Sie beim Bearbeiten Typfehler erkennen und die Wartungskosten einer Aktion verringern, da die Typen die Lesbarkeit verbessern.

Die Bibliothek verringert auch das Risiko unerwarteter Nullwerte, da Parameter immer einen expliziten Standardwert haben oder erforderlich sind.

Fehlerbehandlung

Wenn ein Parameter erforderlich ist, aber nicht gefunden wird oder wenn die Validierung fehlschlägt, wird die Bibliothek eine Ausnahme ausgelegt. Die Standardausnahmen sind MPScholtenRequestParserNotFoundException und MPScholtenRequestParserInvalidValueException . Die vorgeschlagene Möglichkeit, die von der Bibliothek geworfenen Fehler zu bewältigen, besteht darin, sie in Ihrem Frontcontroller zu fangen:

 try {
    $ controller -> $ action ();
} catch ( NotFoundException $ e ) {
    echo $ e -> getMessage ();
} catch ( InvalidValueException $ e ) {
    echo $ e -> getMessage ();
}

Verwenden Sie benutzerdefinierte Ausnahmegeräte

 class MyController
{
    use  MPScholten  RequestParser  Symfony ControllerHelperTrait;
    
    public function __construct ( Request $ request )
    {
        $ exceptionFactory = new ExceptionFactory (CustomNotFoundException::class, CustomInvalidValueException::class));

        $ config = new  MPScholten  RequestParser  Config ();
        $ config -> setExceptionFactory ( $ exceptionFactory );

        $ this -> initRequestParser ( $ request , $ config );
    }
}

Verwenden von benutzerdefinierten Ausnahmemachtungen

Übergeordnete einzelne Nachrichten

Wenn Sie die von der Bibliothek geworfene Ausnahmenachricht nur ein- oder zweimal überschreiben müssen, können Sie dies tun, indem Sie die Ausnahmemeldungen als erstes und zweites Argument an ->required() übergeben:

 class DashboardController
{
    public function show ()
    {
        $ dashboardId = $ this -> queryParameter ( ' id ' )-> int ()-> required ( " The dashboard id has to be a valid number " , " No dashboard id given " );
    }
}

Alle Nachrichten überschreiben

Wenn Sie keine benutzerdefinierte Ausnahmemeldung für alle Ihre Aktionen angeben möchten, aber dennoch nicht die integrierten Ausnahmemachtungen verwenden möchten, können Sie Ihren eigenen Ausnahmenachrichtengenerator angeben:

 class FriendlyExceptionMessageFactory extends  MPScholten  RequestParser ExceptionMessageFactory
{
    protected function createNotFoundMessage ( $ parameterName )
    {
        return " Looks like $ parameterName is missing :) " ;
    }

    protected function createInvalidValueMessage ( $ parameterName , $ parameterValue , $ expected )
    {
        return " Whoops :) $ parameterName seems to be invalid. We're looking for $ expected but you provided ' $ parameterValue ' " ;
    }
}

class MyController
{
    use  MPScholten  RequestParser  Symfony ControllerHelperTrait;
    
    public function __construct ( Request $ request )
    {
        $ config = new  MPScholten  RequestParser  Config ();
        $ config -> setExceptionMessageFactory ( new FriendlyExceptionMessageFactory ());

        $ this -> initRequestParser ( $ request , $ config );
    }
}

Schauen Sie sich dieses Beispiel über benutzerdefinierte Ausnahmen an.

Ist es die Produktion bereit?

Absolut. Diese Bibliothek wurde ursprünglich bei Quintly entwickelt und wird seit April 2015 ausgiebig in der Produktion verwendet. Sie in der Produktion in der Produktion in großem Umfang in der Produktion eingesetzt. Es gibt einen großen Fokus auf Rückwärtskompatibilität und nicht auf Breaking -Sachen.