dataclass
v0.1.2: Support for constructor parameters
dataclass permite que você altere rapidamente seu array simples para uma classe PHP com sugestão de tipo, com desnormalização automática de objetos e coleções incorporados, o que normalmente requer muito trabalho se você usar normalizadores e desnormalizadores. A biblioteca é inspirada no módulo Python pydantic. Ele usa o poder de dicas de tipo disponível desde o PHP 7.4.
O objetivo principal deste pacote é fornecer uma maneira rápida de ter classes estritamente com dicas de tipo para uso posterior, por exemplo, para mapear a carga útil da solicitação para uma classe estritamente digitada para que você possa usá-la em vez de um array que pode ou não atender aos seus requisitos. Isso não substituirá a validação de dados, mas garantirá que a carga útil JSON recebida por fx corresponda aos tipos que suas operações de back-end esperam receber. É algo como a interface pydantic BaseModel ou TypeScript mencionada acima.
Tudo que você precisa é criar uma ou duas classes:
declare (strict_types= 1 );
class MyEmbededClass
{
public float $ number ;
}
class MyClass
{
public int $ number ;
public ? string $ optionalText = null ;
public MyEmbededClass $ embeded ;
} Como próximo passo, passe o nome da classe principal e os dados recebidos, por exemplo, do JSON recebido para o método transform :
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ object = transform (MyClass::class, json_decode ( $ data , true ));Para mapear rapidamente os dados recebidos para dataclass totalmente funcional:
var_dump ( $ object ) object (MyClass) {
[ " number " ]=> int( 1 )
[ " optionalText " ]=> NULL
[ " embeded " ]=>
object(MyEmbededClass) {
[ " number " ]=>
float( 1.23 )
}
} Você não precisa se preocupar em passar null de json_decode , ele lançará TransformException para o campo root se for detectado.
Você não precisa se preocupar com campos ausentes e tipos inválidos, pois a biblioteca detecta todos os requisitos sugeridos por tipo e lança TransformException com erros (prontos para serem servidos como resposta) apontando para campos exatos com uma mensagem de motivo simples, por exemplo:
echo json_encode ( $ transformException , JSON_PRETTY_PRINT ){
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} Você também pode usar o método Transform::to que é de fato chamado pela função auxiliar transform . A função auxiliar sempre usará configurações ideais para objetos Transform (assim que eles aparecerem).
$ data = ' {
"number": 1,
"embeded": {
"number": 1.23
}
} ' ;
$ transformer = new Transform ();
$ object = $ transformer -> to (MyClass::class, json_decode ( $ data , true ));Se você precisar usar o construtor com argumentos sugeridos por tipo, poderá fazê-lo, mas de maneira limitada. A biblioteca suporta apenas o preenchimento de argumentos do construtor com valores da carga útil. Isso significa que o construtor deve usar os mesmos tipos e nomes de variáveis que as propriedades da classe. Por exemplo:
class MyClass
{
public float $ number ;
public ? int $ numberTwo = null ;
public function __construct ( float $ number )
{
$ this -> number = $ number ;
}
}Usar um nome ou tipo diferente para o argumento do construtor não funcionará. O objetivo é apoiar a obrigatoriedade do desenvolvedor preencher as propriedades.
Qualquer construtor que contenha qualquer outro parâmetro além das propriedades lançará UnsupportedException . Os parâmetros devem ter o mesmo tipo das propriedades. A ordem é irrelevante. Se for necessário, apenas algum subconjunto de propriedades poderá existir no construtor.
Por favor, verifique o diretório docs/ para mais exemplos.
Tão simples quanto
composer install rutek/ dataclass
Atenção: esteja ciente de usar dicas de tipo de array . Eles não podem ser usados (lançarão UnsupportedException se detectados), pois o PHP não fornece uma maneira de sugerir itens do array. Por favor, verifique a seção Coleções abaixo para obter mais informações.
Todos os quatro escalares PHP são suportados.
A nulidade da sugestão de tipo é suportada. Você pode usar com segurança, por exemplo ?string para aceitar string e null . Esteja ciente de que usar apenas ?string $field não significa que o array transformado não possa conter este campo. Significa apenas que este valor aceita null .
Se você precisar aceitar a transformação de dados que não contenham alguns campos você pode usar valores padrão, por exemplo: ?string $field = null . a biblioteca dataclass detectará que esta propriedade não existe na carga útil e usará o valor padrão.
O PHP não oferece suporte a campos array com dicas de tipo. Se você precisar incorporar uma coleção de objetos ou escalares, precisará usar a classe Collection . Você precisa estendê-lo com construtor com desconstrução de argumentos sugeridos por tipo, por exemplo:
class Tags extends Collection
{
public function __construct ( string ... $ names )
{
$ this -> items = $ names ;
}
} Matrizes com sugestões de tipo, como string[] foram rejeitadas na RFC, portanto, provavelmente esse comportamento não mudará em breve.
A biblioteca verificará se os valores fornecidos correspondem à sugestão de tipo do construtor.
Não há possibilidade de verificar itens mínimos e máximos, mas poderá haver tal recurso em próximas versões.
Observe que você também pode usar Collection como classe base que deseja transformar, por exemplo:
$ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);TransformException – os dados não correspondem ao seu esquema Esta é a exceção básica que você pode esperar. Cada vez que seus dados (carga útil) passados para a função transform(string $class, $data) ou Transform::to não corresponderem às suas classes sugeridas por tipo, você receberá TransformException com o método getErrors(): FieldError[] que descreve o que realmente ocorrido.
Cada FieldError contém o field que descreve qual campo falhou na verificação de tipo e reason que descreve em palavras simples por que ele foi rejeitado. Se houver objetos aninhados, você receberá valores field como parentProperty.childrenProperty (níveis separados por ponto).
A classe suporta serialização JSON e sempre retornará algo como:
{
"errors" : [
{
"field" : " optionalText " ,
"reason" : " Field must have value "
},
{
"field" : " embeded " ,
"reason" : " Field must have value "
}
]
} Observe que o campo code pode ser adicionado no futuro.
UnsupportedException - somente se suas dicas de tipo não forem suportadas A biblioteca não cobre todos os cenários, pois você pode definir dicas de tipo que não teriam contexto estrito. Por exemplo, se você usar a propriedade object , não será possível validá-la, pois qualquer objeto corresponderá ao seu esquema. Nesses casos, você pode esperar UnsupportedException .
Os tipos de união do PHP 8.0 e os tipos de interseção do PHP 8.1 não são suportados no momento.
Enums nativos do PHP 8.1 não são suportados no momento.
Todos os campos sugeridos por tipo devem ser públicos por enquanto. A implementação desse recurso é questionável, pois você teria que criar getters para essas propriedades, o que representa uma sobrecarga indesejada. A biblioteca tem como objetivo criar a possibilidade de definir esquemas internos para dados recebidos de sistemas remotos (APIs, filas/mensagens de barramento, navegadores).
Todas as verificações de reflexão são feitas sempre que a função transform ou Transform::to é chamada. Você pode esperar funcionalidade de cache para melhor desempenho em breve.
Lembre-se de que o objetivo deste pacote não é validar totalmente os dados que você recebe, mas criar classes simples que tornem suas cargas totalmente orientadas por tipo, mesmo quando elas têm alguma estrutura complicada. Você não precisará codificar suas classes em JSON com campos class , pois suas dicas de tipo informarão ao seu código qual objeto ou array deve ser criado no lugar de alguns valores incorporados.
Se você estiver criando uma API e precisar de validação de esquema OpenAPI de nível empresarial, verifique hkarlstrom/openapi-validation-middleware e depois poderá mapear a carga recebida para classes com sugestão de tipo usando esta biblioteca! :)
