Zec Data Parsing
v1.0.0
تم تصميم مكتبة Zec Data Parsing وإعلان المخطط لتوفير تعريف المخطط وإمكانات التحقق من الصحة لتطبيقات PHP.
composer require mohamed-amine-sayagh/zecفيما يلي مثال لكيفية استخدام مكتبة Zec لتحديد مخطط ملف تعريف المستخدم والتحقق من صحته:
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"
]
}
]
الإصدار الحالي: v1.0.0، تاريخ الإصدار: 2024-10-01، المؤلف: محمد أمين الصايغ، ملاحظات الإصدار: الإصدار الأولي لمكتبة تحليل بيانات Zec PHP.، رابط الإصدار: [Zec 1.0.0](
ملحوظة: هذه المكتبة قيد التطوير حاليًا. الوثائق الرسمية والموارد الإضافية ستكون متاحة قريبا.
معلومات المؤلف:
نحن منفتحون بالكامل على التعاون! إذا كنت مهتمًا بالمساهمة في مكتبة تحليل بيانات PHP، فنحن نحب أن نسمع منك. سواء كان ذلك من خلال مساهمات التعليمات البرمجية، أو تحسينات الوثائق، أو اقتراحات الميزات، فإن مدخلاتك موضع ترحيب كبير.
لمزيد من التفاصيل، راجع إرشادات المساهمة الخاصة بنا (رابط إلى إرشادات المساهمة التفصيلية إذا كانت متوفرة).
نحن نتطلع إلى بناء أداة قوية لتحليل البيانات مع مجتمع حيوي من المساهمين!
تحديد أنواع البيانات والتحقق من صحتها باستخدام تعريفات المخطط البسيطة:
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 classالتحقق من صحة البيانات بسرعة بعد التحليل:
$ is_valid = $ my_schema -> parse ( " Hello, World! " )-> isValid (); // Returns true
$ is_invalid = $ my_schema -> parse ( 123 )-> isValid (); // Returns falseتعامل مع الاستثناءات باستخدام parse_or_throw للتحقق من صحة البيانات الهامة:
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
}يمكنك تحسين تعريف المخطط من خلال دمج خيارات التحقق الإضافية. وهذا يسمح بتحكم أكثر تفصيلاً في مطابقة البيانات بناءً على متطلبات محددة.
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 ());
}توفر المكتبة إمكانية تكوين واسعة النطاق للتحقق من صحة البيانات، مما يسمح للمستخدمين بتحديد قواعد التحقق المعقدة مع الرسائل والشروط المخصصة. فيما يلي مثال لكيفية تكوين مخطط تفصيلي لحقل بريد إلكتروني بقواعد تحقق محددة:
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 ()
]);يوضح هذا المثال التحقق من صحة بنية بيانات المستخدم التي تتضمن المصفوفات المتداخلة والحقول الاختيارية وأنواع الاتحاد، مما يعرض قدرة المكتبة على التعامل مع نماذج البيانات المعقدة والواقعية.
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
} لتعزيز المرونة وتلبية احتياجات التحقق المحددة، تتيح مكتبتنا للمستخدمين تحديد طرق المحلل اللغوي المخصصة. يوضح هذا القسم كيفية إنشاء طريقة محلل size ، والتي تتحقق من أن حجم المصفوفة أو طول السلسلة أو قيمة الرقم يلبي متطلبات محددة.
تتحقق طريقة size مما إذا:
إليك كيفية تنفيذ هذا المحلل اللغوي المخصص:
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 ); يمكنك الآن استخدام طريقة محلل size المخصص في تعريفات المخطط الخاص بك:
$ 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
}تم ترخيص هذا المشروع بموجب ترخيص MIT - راجع ملف LICENSE.md للحصول على التفاصيل.
حقوق الطبع والنشر (ج) 2024 محمد أمين الصايغ
جميع الحقوق محفوظة.
يُمنح الإذن مجانًا لأي شخص يحصل على نسخة من هذا البرنامج وملفات الوثائق المرتبطة به ("البرنامج")، للتعامل في البرنامج دون قيود، بما في ذلك، على سبيل المثال لا الحصر، حقوق الاستخدام والنسخ والتعديل والدمج. ونشر و/أو توزيع وترخيص من الباطن و/أو بيع نسخ من البرنامج، والسماح للأشخاص الذين تم توفير البرنامج لهم بالقيام بذلك، وفقًا للشروط التالية:
يجب تضمين إشعار حقوق الطبع والنشر أعلاه وإشعار الإذن هذا في جميع النسخ أو الأجزاء الكبيرة من البرنامج.
يتم توفير البرنامج "كما هو"، دون أي ضمان من أي نوع، صريحًا أو ضمنيًا، بما في ذلك، على سبيل المثال لا الحصر، ضمانات القابلية للتسويق والملاءمة لغرض معين وعدم الانتهاك. لا يتحمل المؤلفون أو أصحاب حقوق الطبع والنشر بأي حال من الأحوال المسؤولية عن أي مطالبة أو أضرار أو مسؤولية أخرى، سواء في إجراء العقد أو الضرر أو غير ذلك، الناشئة عن أو خارج أو فيما يتعلق بالبرنامج أو الاستخدام أو المعاملات الأخرى في برمجة.
