dataclass
v0.1.2: Support for constructor parameters
dataclass le permite cambiar rápidamente su array simple a una clase PHP con sugerencias de tipo con desnormalización automática de objetos y colecciones incrustados, lo que normalmente requiere mucho trabajo si usa normalizadores y desnormalizadores. La biblioteca está inspirada en el módulo pydantic de Python. Utiliza el poder de sugerencias de tipo disponible desde PHP 7.4.
El objetivo principal de este paquete es proporcionar una manera rápida de tener clases estrictamente con sugerencias de tipo para su uso posterior, por ejemplo, para asignar la carga útil de la solicitud a una clase estrictamente escrita para que pueda usarla en lugar de una matriz que puede o no cumplir con sus requisitos. No reemplazará su validación de datos, pero le asegurará que la carga útil JSON recibida por FX coincida con los tipos que sus operaciones de backend esperan recibir. Es algo como lo mencionado anteriormente Pydantic BaseModel o la interfaz TypeScript.
Todo lo que necesitas es crear una clase o dos:
declare (strict_types= 1 );
class MyEmbededClass
{
public float $ number ;
}
class MyClass
{
public int $ number ;
public ? string $ optionalText = null ;
public MyEmbededClass $ embeded ;
} Como siguiente paso, pase el nombre de la clase principal y los datos recibidos, por ejemplo, del JSON recibido al método transform :
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ object = transform (MyClass::class, json_decode ( $ data , true ));Para asignar rápidamente los datos recibidos a dataclass completamente funcional:
var_dump ( $ object ) object (MyClass) {
[ " number " ]=> int( 1 )
[ " optionalText " ]=> NULL
[ " embeded " ]=>
object(MyEmbededClass) {
[ " number " ]=>
float( 1.23 )
}
} No tiene que preocuparse por pasar null desde json_decode , arrojará TransformException para el campo root si se detecta.
No tiene que preocuparse por los campos faltantes y los tipos no válidos, ya que la biblioteca detecta todos los requisitos de sugerencias de tipo y genera TransformException con errores (listo para ser entregado como respuesta) que apunta a campos exactos con un mensaje de motivo simple, por ejemplo:
echo json_encode ( $ transformException , JSON_PRETTY_PRINT ){
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} También puede utilizar el método Transform::to que, de hecho, es llamado por la función auxiliar transform . La función auxiliar siempre utilizará la configuración óptima para Transform objetos (tan pronto como aparezcan).
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ transformer = new Transform ();
$ object = $ transformer -> to (MyClass::class, json_decode ( $ data , true ));Si necesita utilizar un constructor con argumentos con sugerencias de tipo, puede hacerlo, pero de forma limitada. La biblioteca solo admite completar argumentos del constructor con valores de la carga útil. Significa que el constructor debe usar los mismos tipos y nombres de variables que las propiedades de la clase. Por ejemplo:
class MyClass
{
public float $ number ;
public ? int $ numberTwo = null ;
public function __construct ( float $ number )
{
$ this -> number = $ number ;
}
}Usar un nombre o tipo diferente para el argumento del constructor no funcionará. El objetivo es apoyar a los desarrolladores para que llenen las propiedades.
Cualquier constructor que contenga cualquier otro parámetro además de las propiedades arrojará UnsupportedException . Los parámetros deben tener el mismo tipo que las propiedades. El orden es irrelevante. Si es necesario, sólo puede existir algún subconjunto de propiedades en el constructor.
Consulte el directorio docs/ para ver más ejemplos.
Tan simple como
composer install rutek/ dataclass
Atención: tenga en cuenta el uso de sugerencias de tipo array . No se pueden usar (arrojarán una UnsupportedException si se detectan) ya que PHP no proporciona una forma de escribir sugerencias de elementos de la matriz. Consulte la sección Colecciones a continuación para obtener más información.
Se admiten los cuatro escalares de PHP.
Se admite la posibilidad de nulidad de sugerencias de tipo. Puede utilizar de forma segura, por ejemplo ?string para aceptar tanto string como null . Tenga en cuenta que utilizar solo ?string $field no significa que la matriz transformada no pueda contener este campo. Solo significa que este valor acepta null .
Si necesita aceptar la transformación de datos que no contienen algunos campos, puede utilizar valores predeterminados, por ejemplo: ?string $field = null . La biblioteca dataclass detectará que esta propiedad no existe en la carga útil y utilizará el valor predeterminado en su lugar.
PHP no admite campos array de sugerencias de tipo. Si necesita incrustar una colección de objetos o escalares, debe usar la clase Collection . Debe ampliarlo con un constructor con deconstrucción de argumentos con sugerencias de tipo, por ejemplo:
class Tags extends Collection
{
public function __construct ( string ... $ names )
{
$ this -> items = $ names ;
}
} Las matrices con sugerencias de tipo como string[] fueron rechazadas en RFC, por lo que probablemente este comportamiento no cambiará pronto.
La biblioteca comprobará si los valores proporcionados coinciden con las sugerencias de tipo del constructor.
No existe la posibilidad de verificar los elementos mínimos y máximos, pero es posible que exista dicha función en las próximas versiones.
Tenga en cuenta que también puede utilizar Collection como clase base que desea transformar, por ejemplo:
$ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);TransformException : los datos no coinciden con su esquema Esta es la excepción básica que puede esperar. Cada vez que sus datos (carga útil) pasen a la función transform(string $class, $data) o Transform::to no coincidan con sus clases con sugerencias de tipo, recibirá TransformException con el método getErrors(): FieldError[] que describe lo que realmente sucedió.
Cada FieldError contiene un field que describe qué campo falló en la verificación de tipo y reason que describe en palabras simples por qué se rechazó. Si hay objetos anidados, puede esperar recibir valores field como parentProperty.childrenProperty (niveles separados por puntos).
La clase admite la serialización JSON y siempre devolverá algo como:
{
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} Tenga en cuenta que es posible que se agregue el campo code en el futuro.
UnsupportedException : solo si sus sugerencias de escritura no son compatibles La biblioteca no cubre todos los escenarios, ya que puede definir sugerencias de tipo que no tendrían un contexto estricto. Por ejemplo, si utiliza la propiedad object , no será posible validarla ya que cualquier objeto coincidirá con su esquema. En tales casos, puede esperar UnsupportedException .
Los tipos de unión de PHP 8.0 y los tipos de intersección de PHP 8.1 no son compatibles en este momento.
Las enumeraciones nativas de PHP 8.1 no son compatibles en este momento.
Todos los campos con sugerencias de tipo deben ser públicos por ahora. La implementación de dicha característica es cuestionable, ya que tendría que crear captadores para dichas propiedades, lo que supone una sobrecarga no deseada. La biblioteca está destinada a crear la posibilidad de definir esquemas internos para los datos recibidos de sistemas remotos (API, colas/mensajes de bus, navegadores).
Todas las comprobaciones de reflexión se realizan cada vez que se llama a la función transform o Transform::to . Puede esperar una funcionalidad de almacenamiento en caché para un mejor rendimiento pronto.
Recuerde que el objetivo de este paquete no es validar completamente los datos que recibe, sino crear clases simples que hagan que sus cargas útiles estén completamente escritas incluso cuando tengan alguna estructura complicada. No tendrá que codificar sus clases en JSON con campos class , ya que sus sugerencias de tipo le indicarán a su código qué objeto o matriz debe crearse en lugar de algunos valores incrustados.
Si está creando una API y necesita una validación del esquema OpenAPI de nivel empresarial, debe verificar hkarlstrom/openapi-validation-middleware y luego puede asignar la carga útil recibida a clases con sugerencias de tipo usando esta biblioteca. :)
