dataclass

مكتبة dataclass PHP

تسمح لك dataclass بتغيير array العادي الخاص بك بسرعة إلى فئة PHP ذات التلميح بالنوع مع إلغاء التسوية التلقائي للكائنات والمجموعات المضمنة والتي تتطلب عادةً الكثير من العمل إذا كنت تستخدم أدوات التسوية وأدوات إزالة التسوية. المكتبة مستوحاة من وحدة Python pydantic. يستخدم قوة تلميح النوع المتوفرة منذ PHP 7.4.

الهدف الرئيسي من هذه الحزمة هو توفير طريقة سريعة للحصول على فئات محددة النوع بشكل صارم لمزيد من الاستخدام، على سبيل المثال، لتعيين حمولة الطلب للفئة المكتوبة بدقة حتى تتمكن من استخدامها بدلاً من المصفوفة التي قد تتطابق أو لا تتطابق مع متطلباتك. لن يحل محل التحقق من صحة البيانات الخاصة بك ولكنه سيتأكد من أن fx المستلم لحمولة JSON تتطابق مع الأنواع التي تتوقع عمليات الواجهة الخلفية الخاصة بك استلامها. إنه شيء كما هو مذكور أعلاه pydantic BaseModel أو واجهة TypeScript.

كل ما تحتاجه هو إنشاء فصل أو فصلين:

 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 )
  }
}

لا داعي للقلق بشأن تمرير null من json_decode ، فسوف يؤدي ذلك إلى طرح TransformException لحقل root إذا تم اكتشافه.

لا داعي للقلق بشأن الحقول المفقودة والأنواع غير الصالحة حيث تكتشف المكتبة جميع المتطلبات التي تم التلميح إليها وتطرح TransformException مع وجود أخطاء (جاهزة للعرض كاستجابة) تشير إلى الحقول المحددة برسالة سبب بسيطة، على سبيل المثال:

 echo json_encode ( $ transformException , JSON_PRETTY_PRINT )

{
    "errors" : [
        {
            "field" : " optionalText " ,
            "reason" : " Field must have value "
        },
        {
            "field" : " embeded " ,
            "reason" : " Field must have value "
        }
    ]
}

يمكنك أيضًا استخدام طريقة Transform::to والتي يتم استدعاؤها في الواقع بواسطة وظيفة transform المساعدة. ستستخدم الوظيفة المساعدة دائمًا الإعدادات المثالية 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 . يجب أن يكون للمعلمات نفس نوع الخصائص. النظام لا يهم. إذا لزم الأمر، يمكن أن توجد فقط بعض المجموعات الفرعية من الخصائص في المُنشئ.

المزيد من الأمثلة

يرجى مراجعة المستندات/ الدليل لمزيد من الأمثلة.

تثبيت

بهذه البساطة

dataclass">

 composer install rutek/ dataclass

تلميحات النوع المدعومة

تنبيه: يرجى الانتباه إلى استخدام تلميحات نوع array . لا يمكن استخدامها (سيتم طرح UnsupportedException إذا تم اكتشافها) لأن PHP لا توفر طريقة لعناصر تلميح النوع في المصفوفة. يرجى مراجعة قسم المجموعات أدناه للحصول على مزيد من المعلومات.

العددية

جميع وحدات PHP الأربعة مدعومة.

الحقول الفارغة

يتم دعم إبطال تلميح النوع. يمكنك استخدام ?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 لذا من المحتمل ألا يتغير هذا السلوك قريبًا.

ستتحقق المكتبة مما إذا كانت القيم المقدمة تتطابق مع نوع التلميح للمنشئ.

لا توجد إمكانية للتحقق من الحد الأدنى والحد الأقصى للعناصر ولكن قد تكون هناك مثل هذه الميزة في الإصدارات القادمة.

يرجى ملاحظة أنه يمكنك أيضًا استخدام المجموعة كفئة أساسية تريد تحويلها، على سبيل المثال:

 $ tags = transform (Tags::class, [ ' tag1 ' , ' tag2 ' ]);

الاستثناءات

TransformException - البيانات لا تتطابق مع المخطط الخاص بك

هذا استثناء أساسي يمكنك توقعه. في كل مرة يتم فيها تمرير بياناتك (الحمولة) إلى وظيفة transform(string $class, $data) أو Transform::to لن تتطابق مع فئاتك التي تم التلميح إليها، سوف تتلقى TransformException باستخدام طريقة getErrors(): FieldError[] التي تصف ما هو حقيقي حدث.

يحتوي كل FieldError على field الذي يصف الحقل الذي فشل في التحقق من النوع reason يصف بكلمات بسيطة سبب رفضه. إذا كانت هناك كائنات متداخلة، فيمكنك توقع تلقي قيم field مثل parentProperty.childrenProperty (مستويات مفصولة بنقطة).

يدعم Class تسلسل 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 الأصلية غير مدعومة في الوقت الحالي.

الممتلكات الخاصة والمحمية

يجب أن تكون جميع الحقول المُلمحة إلى النوع عامة في الوقت الحالي. يعد تنفيذ مثل هذه الميزة أمرًا مشكوكًا فيه حيث سيتعين عليك إنشاء حروف لمثل هذه الخصائص التي تعتبر حملًا غير مرغوب فيه. تهدف المكتبة إلى إنشاء إمكانية تحديد المخططات الداخلية للبيانات الواردة من الأنظمة البعيدة (واجهات برمجة التطبيقات وقوائم الانتظار/رسائل الناقل والمتصفحات).

مخبأ الانعكاس

يتم إجراء جميع عمليات التحقق من الانعكاس في كل مرة يتم فيها استدعاء الدالة transform أو Transform::to . يمكنك توقع وظيفة التخزين المؤقت للحصول على أداء أفضل قريبًا.

ملاحظات

يرجى تذكر أن الهدف من هذه الحزمة ليس التحقق من صحة البيانات التي تتلقاها بشكل كامل ولكن إنشاء فئات بسيطة تجعل الحمولات الخاصة بك محددة بشكل كامل أيضًا عندما تحتوي على بنية معقدة. لن تضطر إلى تشفير فئاتك في JSON باستخدام حقول class لأن تلميحات النوع الخاصة بك ستخبر التعليمات البرمجية الخاصة بك بالكائن أو المصفوفة التي يجب إنشاؤها بدلاً من بعض القيم المضمنة.

إذا كنت تقوم بإنشاء واجهة برمجة التطبيقات (API) وتحتاج إلى التحقق من صحة مخطط OpenAPI على مستوى المؤسسة، فيجب عليك التحقق من hkarlstrom/openapi-validation-middleware وبعد ذلك يمكنك تعيين الحمولة المستلمة إلى الفئات التي تم التلميح إليها باستخدام هذه المكتبة! :)