smokescreen laravel php

Laravel-Nebelwand

Überblick

Laravel Smokescreen ist ein Paket zur Transformation Ihrer Laravel-Modelle und anderer Entitäten.

• API-Antworten umwandeln
• Transformieren Sie Job- und Ereignisnutzlasten
• Minimale Kesselplatte und Bootstrap
• Unterstützt komplexe Beziehungen für eingebettete Daten
• Unterstützt das eifrige Laden von Beziehungen
• Ermöglicht die Transformation verschiedener Arten von Ressourcen
• Kann die Serialisierung in anpassbare Formate bewältigen

Dieses Paket integriert das Paket rexlabs/smokescreen (Vanilla PHP) eng in das Laravel-Framework, um Komfort und minimale Grundkenntnisse bei der Arbeit mit Laravel-Anwendungen zu bieten.

Verwendung

 <?php
class MyController extends Controller
{
    public function index ()
    {
        return Smokescreen:: transform (Post:: paginate ());
    }
    
     public function show ( Post $ post )
     {
        return Smokescreen:: transform ( $ post );
     }
}

• laravel-smokescreen wird in den App-Container von Laravel gebootstrappt, sodass Sie es auch mit einem Tipp eingeben können, um es in den Konstruktor oder die Methoden Ihres Controllers einzufügen.
• Die Verwendung der Fassade (wie oben) wird innerhalb von Controller-Methoden empfohlen. Verwenden Sie Typhinweise in Serviceklassen (falls erforderlich).
• Sie können es auch wie oben gezeigt direkt aus dem Container per app('smokescreen') nutzen.
• Da wir die Responsable Schnittstelle implementieren, können Sie Smokescreen einfach von jeder Controller-Methode zurückgeben.

Anforderungen

• PHP >= 7.0
• Laravel >= 5,5

Installation

Dieses Paket wird derzeit im privaten Packagist-Repository von RexSoftware gehostet. Stellen Sie zunächst sicher, dass Sie Ihre composer.json für die Verwendung dieses Repositorys konfiguriert haben.

Paket installieren

composer require rexlabs/laravel-smokescreen

Dieses Paket wird automatisch erkannt und es ist keine zusätzliche Konfiguration erforderlich.

Konfiguration

Um die Konfigurationsdatei in Ihrem Ordner app/config zu veröffentlichen, führen Sie den folgenden Befehl aus:

php artisan vendor:publish --provider= ' RexlabsLaravelSmokescreenProvidersServiceProvider --tag=config '

Dadurch wird config/smokescreen.php erstellt:

 <?php
return [
    // Set the default namespace for resolving transformers when
    // they are not explicitly provided.
    ' transformer_namespace ' => ' AppTransformers ' ,
    
    // Override the default serializer to be used.
    // If not specified - the Smokescreen DefaultSerializer will be used.
    ' default_serializer ' => null ,

    // Set the default request parameter key which is parsed for
    // the list of includes.
    ' include_key ' => ' include ' ,
];

API

transform(): Zu transformierende Ressource festlegen

$smokescreen->transform(mixed $resource, mixed $transformer = null);

 <?php
$ smokescreen -> transform (Post:: find ( 1 ));
$ smokescreen -> transform (Post:: all ());
$ smokescreen -> transform (Post:: paginate ());
$ smokescreen -> transform (Post:: find ( 1 ), new SomeOtherTransformer );

• Smokescreen bestimmt automatisch die Art der umgewandelten Ressource.
• Außerdem wird die zu verwendende Transformer-Klasse abgeleitet, sofern diese nicht angegeben wird.

item(): Legen Sie die zu transformierende Einzelelementressource fest

$smokescreen->item(mixed $item, mixed $transformer = null);

 <?php
$ smokescreen -> item (Post:: find ( 1 ));
$ smokescreen -> item (Post:: find ( 1 ), new SomeOtherTransformer );

• Ähnlich wie transform() akzeptiert jedoch nur ein Element.

Collection(): Sammlungsressource festlegen, die transformiert werden soll

$smokescreen->collection(mixed $collection, mixed $transformer = null);

 <?php
$ smokescreen -> collection (Post:: all ());
$ smokescreen -> collection (Post:: paginate ());
$ smokescreen -> collection (Post:: paginate (), new SomeOtherTransformer );

• Ähnlich wie transform() akzeptiert jedoch nur eine Sammlung.

transformWith(): Legen Sie den Transformator fest, der für die zuvor festgelegte Ressource verwendet werden soll

$smokescreen->transformWith(TransformerInterface|callable $transformer);

 <?php
$ smokescreen -> transform (Post:: find ( 1 ))
    -> transformWith ( new SomeOtherTransformer );

• Dies ist eine Alternative zur direkten Übergabe des Transformators an Ressourcenmethoden.

serializeWith(): Überschreibt den zu verwendenden Serializer

 <?php
$ smokescreen -> serializeWith ( new MyCustomSerializer );

• Sie müssen dies nur festlegen, wenn Sie eine andere Serialisierung als die Standardeinstellung verwenden möchten.
• Wir stellen DefaultSerializer als Standard bereit. Es gibt Sammlungen zurück, die unter einem "data" -Knoten verschachtelt sind, und eine Elementressource ohne jegliche Verschachtelung.
• Ihr benutzerdefinierter Serializer sollte die SerializerInterface Schnittstelle implementieren.

loadRelationsVia(): Überschreibt den standardmäßigen Laravel-Beziehungslader

$smokescreen->loadRelationsVia(RelationsLoaderInterface $loader);

 <?php
$ smokescreen -> loadRelationsVia ( new MyRelationsLoader );

• Sie müssen dies nur festlegen, wenn Sie einen anderen Loader als den Standard verwenden möchten.
• Wir stellen RelationsLoader als Standard bereit, der Beziehungen für Sammlungsressourcen eifrig lädt.
• Ihr benutzerdefinierter Loader sollte die RelationsLoaderInterface -Schnittstelle implementieren und eine load() Methode bereitstellen.

discoverTransformerVia(): Überschreibt den Standard-Transformer-Resolver

$smokescreen->loadTransformersVia(TransformerResolverInterface $loader);

 <?php
$ smokescreen -> loadTransformersVia ( new MyTransformerResolver );

• Der Resolver wird verwendet, wenn ein Transformator nicht explizit für eine Ressource definiert ist.
• Der Standard-Resolver in diesem Paket versucht, eine passende Transformer-Klasse innerhalb des in „ smokescreen.transformer_namespace path“ definierten Pfads zu finden und instanziiert sie über den App-Container.
• Sie müssen dies nur festlegen, wenn Sie einen anderen Resolver als den Standard verwenden möchten.
• Ihr benutzerdefinierter Resolver sollte die Schnittstelle TransformersLoaderInterface implementieren und eine Methode resolve(ResourceInterface) bereitstellen.

Antwort (): Greifen Sie auf das generierte Antwortobjekt zu

$response = $smokescreen->response(int $statusCode = 200, array $headers = [], int $options = 0);

 <?php
$ smokescreen -> response ()
    -> header ( ' X-Custom-Header ' , ' boo ' )
    -> setStatusCode ( 405 );

• Diese Methode gibt ein IlluminateHttpJsonResponse Objekt zurück, sodass es nicht verkettet werden kann.
• Alle unterstützten JsonResponse -Methoden können angewendet werden.
• Sie können response() weiterhin direkt von Ihrem Controller zurückgeben, da es sich um ein JsonResponse Objekt handelt.
• Alternativ können Sie withResponse($callback) verwenden, um Änderungen anzuwenden und trotzdem die Verkettbarkeit zu unterstützen.
• Hinweis: Beim ersten Aufruf von response() wird das Ergebnis zwischengespeichert, sodass nicht jedes Mal der gesamte Datensatz neu generiert wird. Dies bedeutet, dass die Übergabe von Parametern bei nachfolgenden Aufrufen ignoriert wird. Sie können clearResponse() verwenden oder das JsonResponse Objekt direkt bearbeiten.

freshResponse(): Erzeugt ein neues Response-Objekt

$response = $smokescreen->freshResponse(int $statusCode = 200, array $headers = [], int $options = 0);

• Im Gegensatz zu response() gibt diese Methode ein neues, nicht zwischengespeichertes JsonResponse-Objekt zurück (indem zuerst clearResponse() aufgerufen wird).
• Diese Methode gibt ein IlluminateHttpJsonResponse Objekt zurück, sodass es nicht verkettet werden kann. Eine verkettbare Methode finden Sie unter withResponse() .
• Alle unterstützten JsonResponse -Methoden können angewendet werden.

withResponse(): Änderungen auf das generierte Antwortobjekt anwenden

$smokescreen->withResponse(callable $apply);

 <?php
$ smokescreen -> withResponse ( function ( JsonResponse $ response ) {
    $ response -> header ( ' X-Crypto-Alert ' , ' all your coins are worthless! ' );
});

• Stellen Sie einen Rückruf bereit, der ein JsonResponse -Objekt akzeptiert und die Antwort manipuliert
• Diese Methode ist im Gegensatz zu response() verkettbar.

clearResponse(): Alle zwischengespeicherten Antworten löschen

$smokescreen->clearResponse();

 <?php
$ smokescreen -> response ();       // Data is generated, response object is built and cached
$ smokescreen -> response ( 500 );    // NOPE - Cached, wont be changed!
$ smokescreen -> clearResponse ();
$ smokescreen -> response ( 500 );    // Response is re-generated

• Setzt jedes zwischengespeicherte Antwortobjekt zurück

Transformatoren

Beispieltransformator

 <?php
class PostTransformer extends AbstractTransformer
{
    protected $ includes = [
        ' user ' => ' default|relation:user|method:includeTheDamnUser ' ,
        ' comments ' => ' relation ' ,
    ];

    public function transform ( Post $ post ): array
    {
        return [
            ' id ' => $ post -> id ,
            ' user ' => $ this -> when ( $ post -> user_id , [
                ' id ' => $ post -> user_id ,
            ]),
            ' title ' => $ post -> title ,
            ' summary ' => $ post -> summary ,
            ' body ' => $ post -> body ,
            ' created_at ' => utc_datetime ( $ post -> created_at ),
            ' updated_at ' => utc_datetime ( $ post -> updated_at ),
        ];
    }

    public function includeTheDamnUser ( Post $ post )
    {
        return $ this -> item ( $ post -> user ); // Infer Transformer
    }

    public function includeComments ( Post $ post )
    {
        return $ this -> collection ( $ post -> comments , new CommentTransformer );
    }
}

• Sie deklarieren Ihre verfügbaren Includes über das Array $includes
• Jedes Include akzeptiert 0 oder mehr der folgenden Anweisungen:
  • default : Dieses Include ist immer aktiviert, unabhängig von den angeforderten Includes
  • relation : Gibt an, dass eine Relation eifrig geladen werden soll. Wenn der Beziehungsname unterschiedlich ist, geben Sie ihn als relation:othername
  • method : Standardmäßig ist der Include-Schlüssel include{IncludeKey} zugeordnet. Sie können stattdessen die zu verwendende Methode angeben
• Ihre transform() -Methode sollte ein Array zurückgeben.
• Definieren Sie Ihre Include-Methoden im Format include{IncludeKey}(Model) – sie sollten entweder eine collection() oder ein item() zurückgeben.
• when() ist eine einfache Hilfsmethode, die eine Bedingung akzeptiert und entweder den angegebenen Wert zurückgibt, wenn sie wahr ist, oder null (standardmäßig), wenn sie falsch ist. Im obigen Beispiel ist der Knoten "user" null , wenn für das $post -Objekt keine user_id festgelegt ist.

Mitwirken

Pull-Requests sind willkommen. Bitte stellen Sie sicher, dass der Code PSR-kompatibel ist. Github-Repository

Um

• Autor: Jodie Dunlop
• Lizenz: MIT
• Copyright (c) 2018 Rex Software Pty Ltd