dataclass
v0.1.2: Support for constructor parameters
dataclass使用すると、埋め込みオブジェクトとコレクションの自動非正規化を使用して、プレーンなarrayタイプヒント付きの PHP クラスにすばやく変更できます。ノーマライザーとデノーマライザーを使用する場合、通常は多くの作業が必要になります。ライブラリは Python pydantic モジュールからインスピレーションを得ています。 PHP 7.4 以降で利用できるタイプヒンティング機能を使用します。
このパッケージの主な目的は、厳密に型ヒントされたクラスをさらに使用するための高速な方法を提供することです。たとえば、リクエストのペイロードを厳密に型指定されたクラスにマップして、要件に一致するかどうかわからない配列の代わりにそれを使用できるようにすることです。これはデータ検証に代わるものではありませんが、fx が受信した JSON ペイロードがバックエンド操作で受信することが予想される型と一致することを確認します。これは、上で述べた pydantic BaseModelまたは TypeScript インターフェイスのようなものです。
必要なのは、クラスを 1 つまたは 2 つ作成することだけです。
declare (strict_types= 1 );
class MyEmbededClass
{
public float $ number ;
}
class MyClass
{
public int $ number ;
public ? string $ optionalText = null ;
public MyEmbededClass $ embeded ;
}次のステップとして、メインクラス名と受信したデータを渡します（たとえば、受信した JSON からtransformメソッドに渡します）。
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ object = transform (MyClass::class, json_decode ( $ data , true ));受信したデータを完全に機能するdataclassにすばやくマッピングするには:
var_dump ( $ object ) object (MyClass) {
[ " number " ]=> int( 1 )
[ " optionalText " ]=> NULL
[ " embeded " ]=>
object(MyEmbededClass) {
[ " number " ]=>
float( 1.23 )
}
} json_decodeからnullを渡すことを心配する必要はありません。 rootフィールドが検出された場合は、そのフィールドに対してTransformExceptionがスローされます。
ライブラリはタイプヒント付きの要件をすべて検出し、単純な理由メッセージとともに正確なフィールドを指すエラー (応答として提供される準備ができている) とともにTransformExceptionスローするため、フィールドの欠落や無効な型について心配する必要はありません。次に例を示します。
echo json_encode ( $ transformException , JSON_PRETTY_PRINT ){
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
}実際にtransformヘルパー関数によって呼び出されるTransform::toメソッドを使用することもできます。ヘルパー関数は、 Transformオブジェクトに対して (表示されるとすぐに) 常に最適な設定を使用します。
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ transformer = new Transform ();
$ object = $ transformer -> to (MyClass::class, json_decode ( $ data , true ));タイプヒント付きの引数を指定してコンストラクターを使用する必要がある場合は、それを行うこともできますが、方法は限られています。ライブラリは、コンストラクター引数にペイロードからの値を入力することのみをサポートします。これは、コンストラクターがクラス プロパティと同じ型と変数名を使用する必要があることを意味します。例えば：
class MyClass
{
public float $ number ;
public ? int $ numberTwo = null ;
public function __construct ( float $ number )
{
$ this -> number = $ number ;
}
}コンストラクター引数に別の名前または型を使用すると機能しません。目標は、開発者によるプロパティの入力の強制をサポートすることです。
プロパティ以外のパラメーターを含むコンストラクターはUnsupportedExceptionをスローします。パラメータはプロパティと同じ型である必要があります。順序は関係ありません。必要な場合、コンストラクターにはプロパティの一部のサブセットのみが存在できます。
その他の例については、 docs/ ディレクトリを確認してください。
とてもシンプルです
composer install rutek/ dataclass
注意: array型ヒントの使用には注意してください。 PHP では配列の項目をタイプヒントする方法が提供されていないため、これらは使用できません (検出された場合はUnsupportedExceptionがスローされます)。詳細については、以下の「コレクション」セクションをご覧ください。
4 つの PHP スカラーがすべてサポートされています。
タイプヒンティングの null 可能性がサポートされています。たとえば?string使用してstringとnull両方を安全に受け入れることができます。 ?string $fieldのみを使用しても、変換された配列にこのフィールドが含まれない可能性があるという意味ではないことに注意してください。これは、この値がnullを受け入れることを意味するだけです。
一部のフィールドを含まないデータの変換を受け入れる必要がある場合は、デフォルト値 (例: ?string $field = nullを使用できます。 dataclassライブラリは、このプロパティがペイロードに存在しないことを検出し、代わりにデフォルト値を使用します。
PHP は、型ヒントarrayフィールドをサポートしていません。オブジェクトまたはスカラーのコレクションを埋め込む必要がある場合は、 Collectionクラスを使用する必要があります。型ヒント付き引数の分解を伴うコンストラクターを使用して拡張する必要があります。次に例を示します。
class Tags extends Collection
{
public function __construct ( string ... $ names )
{
$ this -> items = $ names ;
}
} string[]のようなタイプヒント配列は RFC で拒否されたため、おそらくこの動作はすぐには変わらないでしょう。
ライブラリは、指定された値がコンストラクターの型ヒントと一致するかどうかを確認します。
最小項目と最大項目をチェックすることはできませんが、次のバージョンではそのような機能が搭載される可能性があります。
たとえば、変換する基本クラスとして Collection を使用することもできることに注意してください。
$ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);TransformException - データがスキーマと一致しませんこれは予期される基本的な例外です。関数transform(string $class, $data)またはTransform::toに渡されたデータ (ペイロード) がタイプヒンテッド クラスと一致しないたびに、 getErrors(): FieldError[]メソッドでTransformException受け取ります。起こった。
すべてのFieldErrorには、どのフィールドがタイプ チェックに失敗したかを説明するfieldと、それが拒否された理由を簡単な言葉で説明するreasonの両方が含まれています。ネストされたオブジェクトがある場合は、 parentProperty.childrenProperty (ドットで区切られたレベル) のようなfield値を受け取ることが期待できます。
クラスは JSON シリアル化をサポートしており、常に次のようなものを返します。
{
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} codeフィールドは将来追加される可能性があることに注意してください。
UnsupportedException - タイプヒントがサポートされていない場合のみ厳密なコンテキストを持たない型ヒントを定義できるため、ライブラリはすべてのシナリオをカバーしているわけではありません。たとえば、 objectプロパティを使用する場合、どのオブジェクトもスキーマに一致するため、それを検証することはできません。このような場合、 UnsupportedException発生する可能性があります。
PHP 8.0 共用体型と PHP 8.1 交差型は現在サポートされていません。
ネイティブ PHP 8.1 列挙型は現在サポートされていません。
現時点では、タイプヒント付きフィールドはすべてパブリックである必要があります。このようなプロパティのゲッターを作成する必要があり、不要なオーバーヘッドが発生するため、このような機能の実装には疑問があります。ライブラリは、リモート システム (API、キュー/バス メッセージ、ブラウザ) から受信したデータの内部スキーマを定義できるようにすることを目的としています。
すべてのリフレクション チェックは、 transformまたはTransform::to関数が呼び出されるたびに行われます。キャッシュ機能によりパフォーマンスが向上する予定です。
このパッケージの目的は、受け取ったデータを完全に検証することではなく、ペイロードが複雑な構造を持っている場合でも完全にタイプヒント化される単純なクラスを作成することであることに注意してください。型ヒントによって、一部の埋め込み値の代わりにどのオブジェクトまたは配列を作成する必要があるかがコードに指示されるため、 classフィールドを使用してクラスを JSON でエンコードする必要はありません。
API を作成していて、エンタープライズ グレードの OpenAPI スキーマ検証が必要な場合は、hkarlstrom/openapi-validation-middleware を確認してください。その後、このライブラリを使用して、受信したペイロードをタイプヒント クラスにマップできます。 :)
