Zec Data Parsing
v1.0.0
A biblioteca Zec Data Parsing e declaração de esquema foi projetada para trazer definição de esquema e recursos de validação para aplicativos PHP.
composer require mohamed-amine-sayagh/zecAqui está um exemplo de como usar a biblioteca Zec para definir e validar um esquema de perfil de usuário:
use function Zec Utils z ;
// Define the user profile schema
$ userProfileParser = z ()-> options ([
' name ' => z ()-> string ()-> min ( 3 )-> max ( 50 ), // Name must be a string between 3 and 50 characters
' age ' => z ()-> number ()-> min ( 18 ), // Age must be a number and at least 18
' email ' => z ()-> email (), // Email must be a valid email address
' address ' => z ()-> options ([
' street ' => z ()-> string (),
' city ' => z ()-> string ()
]),
' hobbies ' => z ()-> each ( z ()-> string ()), // Hobbies must be an array of strings
' metadata ' => z ()-> optional ()-> each ( z ()-> options ([ // Metadata is optional and must be an array of objects
' key ' => z ()-> string (), // Each object must have a key as a string
' value ' => z ()-> string () // Each object must have a value as a string
]))
]); // Parse and validate user data
$ userData = [
' name ' => ' Jane Doe ' ,
' age ' => 1 , // 1 is not a valid age
' email ' => ' jane.doe@examplecom ' , // missing dot
' address ' => [
' street ' => ' 123 Elm St ' ,
' city ' => 3 // city is not a string
],
' hobbies ' => [ ' photography ' , ' traveling ' , ' reading ' , 5 ], // 5 is not a string
' metadata ' => [
[ ' key ' => ' memberSince ' , ' value ' => ' 2019 ' ],
[ ' key ' => ' newsletter ' , ' value ' => ' true ' ]
]
];
try {
$ userProfileParser -> parseOrThrow ( $ userData ); // Throws an error
echo " User data is valid n" ;
} catch ( Zec ZecError $ e ) {
echo " User data is invalid: " ;
$ e -> log (); // Log the error
} User data is invalid: [
{
"parser": "min",
"value": 1,
"min": 18,
"message": "Invalid value",
"path": [
"age"
]
},
{
"parser": "email",
"value": "jane.doe@examplecom",
"message": "Invalid email address",
"path": [
"email"
]
},
{
"parser": "string",
"value": 5,
"message": "Invalid string value",
"path": [
"hobbies",
"3"
]
}
]
Versão atual: v1.0.0, Data de lançamento: 01/10/2024, Autor: Mohamed Amine SAYAGH, Notas de versão: Versão inicial da biblioteca de análise de dados Zec PHP., Link de lançamento: [Zec 1.0.0](
Nota: Esta biblioteca está atualmente em desenvolvimento. Documentação oficial e mais recursos estarão disponíveis em breve.
Informações do autor:
Estamos totalmente abertos à colaboração! Se você estiver interessado em contribuir com a Biblioteca de Análise de Dados PHP, adoraríamos ouvir sua opinião. Seja por meio de contribuições de código, melhorias na documentação ou sugestões de recursos, sua contribuição é muito bem-vinda.
Para obter mais detalhes, verifique nossas diretrizes de contribuição (link para diretrizes detalhadas de contribuição, se disponível).
Estamos ansiosos para construir uma ferramenta poderosa de análise de dados com uma comunidade vibrante de colaboradores!
Defina e valide tipos de dados usando definições de esquema simples:
use function Zec Utils z ;
$ my_schema = z ()-> string ();
$ response_valid = $ my_schema -> parse ( " Hello, World! " ); // Returns Zec data object
$ value = $ response_valid -> value ; // Returns "Hello, World!"
$ response_invalid = $ my_schema -> parse ( 123 ); // Returns Zec data object
$ errors = $ response_invalid -> errors ; // Returns an array of ZecError object an exception extends classValide os dados rapidamente após a análise:
$ is_valid = $ my_schema -> parse ( " Hello, World! " )-> isValid (); // Returns true
$ is_invalid = $ my_schema -> parse ( 123 )-> isValid (); // Returns falseLide com exceções usando parse_or_throw para validação de dados críticos:
try {
$ response = $ my_schema -> parseOrThrow ( 123 ); // Throws ZecError
} catch ( ZecError $ error ) {
$ error_message = $ error -> message ; // Returns "Invalid type: expected string, received integer"
$ error -> log (); // Logs the error
}Você pode aprimorar a definição do esquema incorporando opções de validação adicionais. Isto permite um controle mais detalhado sobre a conformidade dos dados com base em requisitos específicos.
use function Zec z ;
$ user_schema = z ()-> options ([
' name ' => z ()-> string ()-> min ( 3 )-> max ( 50 ),
' email ' => z ()-> email (),
' age ' => z ()-> number ()-> min ( 18 ),
' isActive ' => z ()-> boolean (),
' registrationDate ' => z ()-> date ()
]);
// Parsing a valid user object
$ valid_user = $ user_schema -> parse ([
' name ' => ' John Doe ' ,
' email ' => ' [email protected] ' ,
' age ' => 30 ,
' isActive ' => true ,
' registrationDate ' => ' 2021-01-01 '
]);
// Parsing an invalid user object
$ invalid_user = $ user_schema -> parse ([
' name ' => ' JD ' , // Too short
' email ' => ' john.doe@ ' , // Invalid email format
' age ' => 17 , // Below minimum age requirement
' isActive ' => ' yes ' , // Incorrect type (should be boolean)
' registrationDate ' => ' 01-01-2021 ' // Wrong date format
]);
// Handling validation results
if ( $ valid_user -> isValid ()) {
echo ' User is valid. ' ;
} else {
echo ' User is invalid. Errors: ' ;
var_dump ( $ valid_user -> errors ());
}
if ( $ invalid_user -> isValid ()) {
echo ' User is valid. ' ;
} else {
echo ' User is invalid. Errors: ' ;
var_dump ( $ invalid_user -> errors ());
}A biblioteca oferece ampla configurabilidade para validação de dados, permitindo que os usuários definam regras de validação complexas com mensagens e condições personalizadas. Abaixo está um exemplo de como configurar um esquema detalhado para um campo de email com regras de validação específicas:
use function Zec z ;
// Define a configurable email schema
$ my_configurable_email_schema = z ()-> string ([
' message ' => ' Invalid string data '
])-> min ([
' min ' => 3 ,
' message ' => ' String data must be at least 3 characters long ' // Custom message
])-> max ([
' max ' => 10 ,
' message ' => ' String {{value}} must be at most ((max)) characters long ' // Custom message with value interpolation
]). email ([
' message ' => ' Invalid email ' ,
' domain ' => [ ' gmail.com ' , ' yahoo.com ' ] // Custom domain validation rules
]);
// Define a user schema using the configurable email schema
$ my_user = z ()-> options ([
' email ' => $ my_configurable_email_schema -> required ()
]);Este exemplo demonstra a validação de uma estrutura de dados do usuário que inclui matrizes aninhadas, campos opcionais e tipos de união, mostrando a capacidade da biblioteca de lidar com modelos de dados complexos e realistas.
use function Zec z ;
// Define a user schema with various data validation rules
$ user_parser = z ()-> options ([
' name ' => z ()-> required ()-> string ()-> min ( 3 )-> max ( 50 ),
' email ' => z ()-> url ([
' message ' => ' Invalid email address ' ,
' domain ' => [ ' gmail.com ' ]
]),
' age ' => z ()-> number (),
' friends ' => z ()-> each (
function ( $ user ) {
return $ user -> nullable ();
} // Each friend is a user object (nullable)
),
' password ' => z ()-> optional ()-> options ([
' password ' => z ()-> string (), // Path: 'password.password'
' confirm_password ' => z ()-> string (),
' created_at ' => z ()-> date (),
]),
' created_at ' => z ()-> date (),
' updated_at ' => z ()-> date (),
' document ' => z ()-> union ([
z ()-> options ([
' type ' => z ()-> enum ([ ' student ' ]),
' content ' => z ()-> options ([
' school ' => z ()-> string (),
' grade ' => z ()-> number (),
]),
]),
z ()-> options ([
' type ' => z ()-> enum ([ ' teacher ' ]),
' content ' => z ()-> options ([
' school ' => z ()-> string (),
' subject ' => z ()-> string (),
]),
]),
]) // Union type for document, can be student or teacher document
]);
// Parse a valid user object
$ user = $ user_parser -> parse ([
' name ' => ' John Doe ' ,
' email ' => ' [email protected] ' ,
' age ' => 25 ,
' friends ' => [
[
' name ' => ' Jane Doe ' ,
' email ' => ' [email protected] ' ,
' age ' => 30 ,
],
],
' password ' => [
' password ' => ' password ' ,
' confirm_password ' => ' password ' ,
' created_at ' => ' 2021-10-10 '
],
' created_at ' => ' 2021-10-10 ' ,
' updated_at ' => ' 2021-10-10 ' ,
' document ' => [
' type ' => ' student ' ,
' content ' => [
' school ' => ' School ' ,
' grade ' => 10 ,
]
]
]); // Returns a Zec object
// Validate the parsed data
if ( $ user -> isValid ()) {
echo ' User is valid. ' ;
var_dump ( $ user -> getValue ()); // Outputs the validated data
} else {
echo ' User is invalid. ' ;
var_dump ( $ user -> errors ()); // Outputs validation errors
} Para aumentar a flexibilidade e atender às necessidades específicas de validação, nossa biblioteca permite que os usuários definam métodos de análise personalizados. Esta seção demonstra como criar um método analisador size , que valida se o tamanho de uma matriz, o comprimento de uma string ou o valor de um número atende a um requisito específico.
O método size verifica se:
Aqui está como você pode implementar este analisador personalizado:
use function Zec z ;
use function Zec bundler ;
use Zec FIELD as FK ;
$ custom_size_parser = parser_build ()
-> name ( ' size ' )
-> prioritize ( ' string ' , ' number ' , ' array ' ) // Prioritize the parser for string, number, and array types
-> argument ( ' message ' , ' Invalid size ' , function ( Zec Zec $ z ) {
return $ z -> required ()-> string ();
}) // argument for custom message, default is 'Invalid size'
-> argument ( ' size ' , 0 , function ( Zec Zec $ z ) {
return $ z -> required ()-> number ();
}) // argument for size, default is 0
-> function ( function ( array $ args ): string | bool {
$ value = $ args [ ' value ' ];
$ expected_size = $ args [ ' size ' ];
$ message = $ args [ ' message ' ];
if ( is_array ( $ value )) {
$ actual_size = count ( $ value );
} elseif ( is_string ( $ value )) {
$ actual_size = strlen ( $ value );
} elseif ( is_numeric ( $ value )) {
$ actual_size = $ value ;
} else {
return $ message ?? ' Invalid data type ' ;
}
if ( $ actual_size === $ expected_size ) {
return true ;
}
return $ message ?? ' Invalid size ' ;
})-> priority ( 4 ); // priority of the parser, the default priority of parser is 10, parser with 5 as priority will override before parser with 10 as priority if they have the same parser name
-> build (); // Build the parser
bundler-> addParser ( $ custom_size_parser ); Agora você pode usar o método analisador size personalizado em suas definições de esquema:
$ my_schema = z ()-> options ([
' username ' => z ()-> string ()-> size ( 5 ), // Username must be a string of length 5
' favorite_numbers ' => z ()-> array ()-> size ( 5 ), // Favorite numbers must be an array of length 5
' lucky_number ' => z ()-> number ()-> size ( 5 ), // Lucky number must be 5
]);
$ user_data = [
' username ' => ' admin ' ,
' favorite_numbers ' => [ 1 , 2 , 3 , 4 , 5 ],
' lucky_number ' => 5
]; // Valid data
$ parsed_data = $ my_schema -> parse ( $ user_data ); // Returns a Zec object
// Validate the parsed data
if ( $ parsed_data -> isValid ()) { // Returns true if data is valid
echo ' All data is valid. ' ;
} else {
echo ' Data validation failed. Errors: ' ;
var_dump ( $ parsed_data -> errors ()); // Outputs validation errors
}Este projeto está licenciado sob a licença MIT - consulte o arquivo LICENSE.md para obter detalhes.
Copyright (c) 2024 Mohamed Amine SAYAGH
Todos os direitos reservados.
É concedida permissão, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para negociar o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar , publicar, distribuir, sublicenciar e/ou vender cópias do Software e permitir que as pessoas a quem o Software seja fornecido o façam, sujeito às seguintes condições:
O aviso de direitos autorais acima e este aviso de permissão serão incluídos em todas as cópias ou partes substanciais do Software.
O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM DETERMINADO FIM E NÃO VIOLAÇÃO. EM HIPÓTESE ALGUMA OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM UMA AÇÃO DE CONTRATO, ATO ILÍCITO OU DE OUTRA FORMA, DECORRENTE DE, OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.
