dataclass

PHP- dataclass

dataclass können Sie Ihr einfaches array schnell in eine PHP-Klasse mit Typhinweis ändern und eingebettete Objekte und Sammlungen automatisch denormalisieren, was normalerweise viel Arbeit erfordert, wenn Sie Normalisierer und Denormalisierer verwenden. Die Bibliothek ist vom Python-Pydantic-Modul inspiriert. Es nutzt die seit PHP 7.4 verfügbare Typhinweisfunktion.

Das Hauptziel dieses Pakets besteht darin, eine schnelle Möglichkeit zu bieten, streng typisierte Klassen für die weitere Verwendung bereitzustellen, beispielsweise um die Anforderungsnutzlast einer streng typisierten Klasse zuzuordnen, sodass Sie sie anstelle eines Arrays verwenden können, das möglicherweise Ihren Anforderungen entspricht oder nicht. Es ersetzt nicht Ihre Datenvalidierung, stellt aber sicher, dass fx die empfangene JSON-Nutzlast mit den Typen übereinstimmt, die Ihre Back-End-Vorgänge erwarten. Es ist so etwas wie die oben erwähnte pydantische BaseModel oder TypeScript-Schnittstelle.

Sie müssen lediglich eine oder zwei Klassen erstellen:

 declare (strict_types= 1 );

class MyEmbededClass
{
    public float $ number ;
}

class MyClass
{
    public int $ number ;
    public ? string $ optionalText = null ;
    public MyEmbededClass $ embeded ;
}

Übergeben Sie im nächsten Schritt den Namen der Hauptklasse und die empfangenen Daten, beispielsweise vom empfangenen JSON, an die transform :

 $ data = ' {
    "number": 1,
    "embeded": {
        "number": 1.23
    }
} ' ;
$ object = transform (MyClass::class, json_decode ( $ data , true ));

So ordnen Sie empfangene Daten schnell einer voll funktionsfähigen dataclass zu:

 var_dump ( $ object )

 object (MyClass) {
  [ " number " ]=> int( 1 )
  [ " optionalText " ]=> NULL
  [ " embeded " ]=>
  object(MyEmbededClass) {
    [ " number " ]=>
    float( 1.23 )
  }
}

Sie müssen sich keine Gedanken über die Übergabe von null von json_decode machen, es wird TransformException für root auslösen, wenn es erkannt wird.

Sie müssen sich keine Sorgen über fehlende Felder und ungültige Typen machen, da die Bibliothek alle typbezogenen Anforderungen erkennt und TransformException mit Fehlern auslöst (bereit zur Bereitstellung als Antwort), die auf genaue Felder mit einer einfachen Begründungsmeldung verweist, zum Beispiel:

 echo json_encode ( $ transformException , JSON_PRETTY_PRINT )

{
    "errors" : [
        {
            "field" : " optionalText " ,
            "reason" : " Field must have value "
        },
        {
            "field" : " embeded " ,
            "reason" : " Field must have value "
        }
    ]
}

Sie können auch die Methode Transform::to verwenden, die tatsächlich von transform Hilfsfunktion aufgerufen wird. Die Hilfsfunktion verwendet immer die optimalen Einstellungen für Transform (sobald sie angezeigt werden).

 $ data = ' {
    "number": 1,
    "embeded": {
        "number": 1.23
    }
} ' ;
$ transformer = new Transform ();
$ object = $ transformer -> to (MyClass::class, json_decode ( $ data , true ));

Konstrukteure

Wenn Sie einen Konstruktor mit typbezogenen Argumenten verwenden müssen, können Sie dies tun, jedoch in eingeschränkter Weise. Die Bibliothek unterstützt nur das Ausfüllen von Konstruktorargumenten mit Werten aus der Nutzlast. Das bedeutet, dass der Konstruktor dieselben Typen und Variablennamen wie die Klasseneigenschaften verwenden muss. Zum Beispiel:

 class MyClass
{
    public float $ number ;
    public ? int $ numberTwo = null ;

    public function __construct ( float $ number )
    {
        $ this -> number = $ number ;
    }
}

Die Verwendung eines anderen Namens oder Typs für das Konstruktorargument funktioniert nicht. Ziel ist es, den Bauträger dabei zu unterstützen, die Eigenschaften auszufüllen.

Jeder Konstruktor, der einen anderen Parameter als die Eigenschaften enthält, löst UnsupportedException aus. Parameter müssen denselben Typ wie Eigenschaften haben. Reihenfolge ist irrelevant. Bei Bedarf kann im Konstruktor nur eine Teilmenge der Eigenschaften vorhanden sein.

Weitere Beispiele

Weitere Beispiele finden Sie im Verzeichnis docs/.

Installation

So einfach wie

 composer install rutek/ dataclass

Hinweise zu unterstützten Typen

Achtung: Bitte beachten Sie die Verwendung von array Typ-Hinweisen. Sie können nicht verwendet werden (wird bei Erkennung UnsupportedException auslösen), da PHP keine Möglichkeit bietet, Array-Elemente mit Typhinweisen zu versehen. Weitere Informationen finden Sie im Abschnitt „Sammlungen“ weiter unten.

Skalare

Alle vier PHP-Skalare werden unterstützt.

Nullable-Felder

Typhinweis-Nullfähigkeit wird unterstützt. Sie können beispielsweise sicher ?string verwenden, um sowohl string als auch null zu akzeptieren. Bitte beachten Sie, dass die Verwendung von nur ?string $field nicht bedeutet, dass das transformierte Array dieses Feld möglicherweise nicht enthält. Es bedeutet nur, dass dieser Wert null akzeptiert.

Standardwerte

Wenn Sie die Transformation von Daten akzeptieren müssen, die einige Felder nicht enthalten, können Sie Standardwerte verwenden, zum Beispiel: ?string $field = null . Die dataclass erkennt, dass diese Eigenschaft nicht in der Nutzlast vorhanden ist, und verwendet stattdessen den Standardwert.

Sammlungen

PHP unterstützt keine array -Felder mit Typhinweisen. Wenn Sie eine Sammlung von Objekten oder Skalaren einbetten müssen, müssen Sie Collection Klasse verwenden. Sie müssen es mit einem Konstruktor mit typbezogener Argumentdekonstruktion erweitern, zum Beispiel:

 class Tags extends Collection
{
    public function __construct ( string ... $ names )
    {
        $ this -> items = $ names ;
    }
}

Typhinweis-Arrays wie string[] wurden in RFC abgelehnt, daher wird sich dieses Verhalten wahrscheinlich nicht so schnell ändern.

Die Bibliothek prüft, ob die bereitgestellten Werte mit der Typangabe des Konstruktors übereinstimmen.

Es gibt keine Möglichkeit, Mindest- und Höchstwerte zu überprüfen, aber möglicherweise wird eine solche Funktion in nächsten Versionen verfügbar sein.

Bitte beachten Sie, dass Sie auch Collection als Basisklasse verwenden können, die Sie transformieren möchten, zum Beispiel:

 $ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);

Ausnahmen

TransformException – Daten stimmen nicht mit Ihrem Schema überein

Dies ist die Grundausnahme, die Sie erwarten können. Jedes Mal, wenn Ihre Daten (Nutzlast), die an die Funktion transform(string $class, $data) oder Transform::to übergeben werden, nicht mit Ihren typbezogenen Klassen übereinstimmen, erhalten Sie TransformException mit der Methode getErrors(): FieldError[] die beschreibt, was wirklich passiert.

Jeder FieldError enthält sowohl field das beschreibt, welches Feld die Typprüfung nicht bestanden hat, als auch reason der in einfachen Worten beschreibt, warum es abgelehnt wurde. Wenn verschachtelte Objekte vorhanden sind, können Sie davon ausgehen, dass Sie field wie parentProperty.childrenProperty (durch Punkte getrennte Ebenen) erhalten.

Die Klasse unterstützt die JSON-Serialisierung und gibt immer etwas zurück wie:

{
    "errors" : [
        {
            "field" : " optionalText " ,
            "reason" : " Field must have value "
        },
        {
            "field" : " embeded " ,
            "reason" : " Field must have value "
        }
    ]
}

Bitte beachten Sie, dass das code möglicherweise in Zukunft hinzugefügt wird.

UnsupportedException – nur, wenn Ihre Typhinweise nicht unterstützt werden

Die Bibliothek deckt nicht alle Szenarios ab, da Sie Typhinweise definieren können, die keinen strengen Kontext hätten. Wenn Sie beispielsweise object verwenden, ist eine Validierung nicht möglich, da jedes Objekt mit Ihrem Schema übereinstimmt. In solchen Fällen können Sie mit UnsupportedException rechnen.

(noch?) nicht unterstützt

Schnittpunkt- und Vereinigungstypen

PHP 8.0-Union-Typen und PHP 8.1-Schnittpunkttypen werden derzeit nicht unterstützt.

Aufzählungen

Native PHP 8.1-Enums werden derzeit nicht unterstützt.

Private und geschützte Immobilien

Alle Felder mit Typhinweisen müssen vorerst öffentlich sein. Die Implementierung einer solchen Funktion ist fraglich, da Sie Getter für solche Eigenschaften erstellen müssten, was einen unerwünschten Mehraufwand darstellt. Die Bibliothek soll die Möglichkeit schaffen, interne Schemata für Daten zu definieren, die von Remote-Systemen (APIs, Warteschlangen/Busnachrichten, Browser) empfangen werden.

Reflexions-Cache

Alle Reflexionsprüfungen werden jedes Mal durchgeführt, wenn die Funktion transform oder Transform::to aufgerufen wird. Sie können bald Caching-Funktionalität für eine bessere Leistung erwarten.

Bemerkungen

Bitte beachten Sie, dass das Ziel dieses Pakets nicht darin besteht, die von Ihnen empfangenen Daten vollständig zu validieren, sondern einfache Klassen zu erstellen, die Ihre Nutzdaten auch dann vollständig typgestützt machen, wenn sie eine komplizierte Struktur haben. Sie müssen Ihre Klassen nicht in JSON mit class codieren, da Ihre Typhinweise Ihrem Code mitteilen, welches Objekt oder Array anstelle einiger eingebetteter Werte erstellt werden soll.

Wenn Sie eine API erstellen und eine OpenAPI-Schemavalidierung auf Unternehmensniveau benötigen, sollten Sie hkarlstrom/openapi-validation-middleware überprüfen. Anschließend können Sie die empfangene Nutzlast mithilfe dieser Bibliothek typgekennzeichneten Klassen zuordnen! :) :)