jsonmapper

JsonMapper - قم بتعيين هياكل JSON المتداخلة على فئات PHP

يأخذ البيانات المستردة من خدمة ويب JSON ويحولها إلى كائنات ومصفوفات متداخلة - باستخدام فئات النماذج الخاصة بك.

بدءًا من كائن أساسي، يقوم بتعيين بيانات JSON على خصائص الفئة، وتحويلها إلى الأنواع أو الكائنات البسيطة الصحيحة.

إنه يشبه إلى حد ما تعيين معلمات SOAP الأصلي الذي يوفره لك SoapClient PHP، ولكن لـ JSON. أنها لا تعتمد على أي مخطط، فقط تعريفات فئة PHP الخاصة بك.

يعمل اكتشاف النوع عن طريق تحليل إعلانات النوع والتعليقات التوضيحية @var docblock لخصائص الفئة، بالإضافة إلى تلميحات الكتابة في أساليب الضبط.

ليس عليك تعديل فئات النموذج الخاصة بك عن طريق إضافة كود JSON محدد؛ إنه يعمل تلقائيًا عن طريق تحليل كتل المستندات الموجودة بالفعل.

هذه المكتبة ليس لديها تبعيات.

الكلمات المفتاحية: إلغاء التسلسل، الترطيب

محتويات

• برو وكونترا
  • فوائد
  • العيوب
• الاستخدام
  • الاستخدام الأساسي
  • مثال
  • رسم خرائط نوع العقار
    • أسماء الأنواع المدعومة
    • رسم خرائط نوع بسيط
    • خريطة الصف
    • القيم الفارغة
  • التسجيل
  • التعامل مع البيانات غير الصالحة أو المفقودة
    • خصائص غير معروفة
    • خصائص مفقودة
  • الخصائص والوظائف الخاصة
  • أنواع بسيطة بدلا من الكائنات
  • تمرير المصفوفات إلى map()
  • رد الاتصال بعد التعيين
• تثبيت
• البرامج ذات الصلة
• حول جسونمابر
  • رخصة
  • أسلوب الترميز
  • مؤلف

برو وكونترا

فوائد

• الإكمال التلقائي في IDEs
• من السهل إضافة أساليب الراحة إلى فئات نماذج البيانات
• قد تتغير واجهة برمجة تطبيقات JSON الخاصة بك، ولكن يمكن أن تظل نماذجك كما هي - دون تعطيل التطبيقات التي تستخدم فئات النماذج.

العيوب

• يجب كتابة الفصول النموذجية يدويًا

  نظرًا لأن JsonMapper لا يعتمد على أي معلومات مخطط (على سبيل المثال من مخطط json)، فلا يمكن إنشاء فئات النماذج تلقائيًا.

الاستخدام

الاستخدام الأساسي

1. قم بتثبيت netresearch/jsonmapper باستخدام الملحن
2. قم بإنشاء مثيل كائن JsonMapper
3. اتصل map أو طريقة mapArray ، وفقًا لبياناتك

تعيين كائن عادي:

 <?php
require ' autoload.php ' ;
$ mapper = new JsonMapper ();
$ contactObject = $ mapper -> map ( $ jsonContact , new Contact ());
// or as classname
$ contactObject = $ mapper -> map ( $ jsonContact , Contact::class);

تعيين مجموعة من الكائنات:

 <?php
require ' autoload.php ' ;
$ mapper = new JsonMapper ();
$ contactsArray = $ mapper -> mapArray (
    $ jsonContacts , array (), ' Contact '
);

بدلًا من array() يمكنك أيضًا استخدام ArrayObject والفئات المشتقة، بالإضافة إلى الفئات التي تنفذ ArrayAccess .

مثال

JSON من خدمة ويب دفتر العناوين:

 {
    "name" : "Sheldon Cooper" ,
    "address" : {
        "street" : "2311 N. Los Robles Avenue" ,
        "city" : "Pasadena"
    }
}

فئة Contact المحلية الخاصة بك:

 <?php
class Contact
{
    /**
     * Full name
     */
    public string $ name ;

    public ? Address $ address ;
}

فئة Address المحلي الخاصة بك:

 <?php
class Address
{
    public $ street ;
    public $ city ;

    public function getGeoCoords ()
    {
        //do something with $street and $city
    }
}

رمز التطبيق الخاص بك:

 <?php
$ json = json_decode ( file_get_contents ( ' http://example.org/sheldon.json ' ));
$ mapper = new JsonMapper ();
$ contact = $ mapper -> map ( $ json , new Contact ());

echo " Geo coordinates for " . $ contact -> name . " : "
    . var_export ( $ contact -> address -> getGeoCoords (), true );

رسم خرائط نوع العقار

يستخدم JsonMapper عدة مصادر لاكتشاف النوع الصحيح للخاصية بالترتيب التالي:

1. طريقة الضبط ( set + ucwords($propertyname) )

   الشرطات السفلية " _ " والواصلات " - " تجعل الحرف التالي كبيرًا. الخاصية foo_bar-baz تؤدي إلى طريقة الضبط setFooBarBaz .

   1. إذا كان يحتوي على تلميح نوع في توقيع الطريقة، فسيتم استخدام نوعه:

       الوظيفة العامة setPerson(جهة الاتصال $person) {...}
      

   2. يتم فحص docblock الخاص بالطريقة بحثًا عن التعليقات التوضيحية @param $type :

       /**
       *param Contact $person جهة الاتصال الرئيسية لهذا التطبيق
       */
      الوظيفة العامة setPerson($person) {...}
      

   3. إذا لم يتم اكتشاف أي نوع، فسيتم تمرير قيمة JSON البسيطة إلى طريقة الضبط.

2. أنواع خصائص الفئة (منذ PHP 7.4):

    جهة الاتصال العامة $person;
   

3. أنواع الترويج لملكية المُنشئ (منذ PHP 8.0):

    الوظيفة العامة __construct(جهة الاتصال المحمية $person) {}
   

4. شرح @var $type docblock لخصائص الفئة:

    /**
    * @var myapplicationmodelContact
    */
   شخص عام $؛
   

   يجب أن يكون العقار عامًا ليتم استخدامه بشكل مباشر. يمكنك أيضًا استخدام $bIgnoreVisibility للاستفادة من الخصائص المحمية والخاصة.

   إذا لم يتم اكتشاف أي نوع، فستحصل الخاصية على مجموعة قيم JSON البسيطة.

   إذا تعذر العثور على خاصية، يحاول JsonMapper العثور على الخاصية بطريقة غير حساسة لحالة الأحرف. سيتم بعد ذلك تعيين خاصية JSON isempty إلى خاصية PHP isEmpty .

   ملحوظة

   يجب عليك توفير مساحة الاسم المؤهلة بالكامل حتى يعمل النوع. يتم تقييم أسماء الفئات النسبية في سياق مساحة اسم الفئات الحالية، دون احترام أي عمليات استيراد قد تكون موجودة.

   لا توفر PHP عمليات الاستيراد عبر Reflection؛ يحتوي نص التعليق فقط على النص الحرفي للنوع. لأسباب تتعلق بالأداء، لا يقوم JsonMapper بتحليل الكود المصدري من تلقاء نفسه لاكتشاف أي عمليات استيراد وتوسيعها.

أسماء الأنواع المدعومة

• أنواع بسيطة

  • string
  • bool boolean
  • int ، integer
  • double ، float
  • array
  • object
  • mixed

• أسماء الفئات، مع وبدون مساحات الأسماء

  • Contact - سيتم طرح الاستثناء إذا كانت قيمة JSON null

• مصفوفات من الأنواع البسيطة وأسماء الفئات:

  • int[]
  • Contact[]

• المصفوفات المتعددة الأبعاد:

  • int[][]
  • TreeDeePixel[][][]

• ArrayObjects من الأنواع البسيطة وأسماء الفئات:

  • ContactList[Contact]
  • NumberList[int]

• التعدادات المدعومة، مع وبدون مساحات الأسماء

  • Suit:string|Suit:int - سيتم طرح الاستثناء إذا لم تكن قيمة JSON موجودة في التعداد

• أنواع لاغية:

  • int|null أو ?int - ستكون null إذا كانت القيمة في JSON null ، وإلا فستكون عددًا صحيحًا
  • Contact|null أو ?Contact - ستكون null إذا كانت القيمة في JSON null ، وإلا فستكون كائنًا من النوع Contact

يتم التعامل مع ArrayObjects والفئات الموسعة كمصفوفات.

ستحصل المتغيرات التي لا تحتوي على نوع أو ذات نوع mixed على قيمة JSON المحددة مباشرة دون أي تحويل.

راجع وثائق نوع phpdoc لمزيد من المعلومات.

رسم خرائط نوع بسيط

ملحوظة

تم تعطيل هذه الميزة بشكل افتراضي لأسباب أمنية منذ الإصدار 5. راجع $bStrictObjectTypeChecking للحصول على التفاصيل.

عندما يتم إنشاء كائن ولكن JSON يحتوي على نوع بسيط فقط (على سبيل المثال، سلسلة، تعويم، منطقي)، يتم تمرير هذه القيمة إلى مُنشئ الفئات. مثال:

كود PHP:

 public DateTime $ date ;

جسون:

 { "date" : "2014-05-15" }

سيؤدي هذا إلى استدعاء new DateTime('2014-05-15') .

خريطة الصف

عندما يتم تعريف المتغيرات ككائنات من فئات أو واجهات مجردة، سيحاول JsonMapper عادةً إنشاء مثيل لها مباشرة ويتعطل.

باستخدام الخاصية $classMap الخاصة بـ JsonMapper، يمكنك تحديد الفئات التي سيتم إنشاء مثيل لها بدلاً من ذلك:

 $ jm = new JsonMapper ();
$ jm -> classMap [ ' Foo ' ] = ' Bar ' ;
$ jm -> map (...);

سيؤدي هذا إلى إنشاء كائنات من النوع Bar عندما يتم تعريف متغير ليكون من النوع Foo .

من الممكن أيضًا استخدام قابل للاستدعاء في حالة الحاجة إلى تحديد فئة التنفيذ الفعلية ديناميكيًا (على سبيل المثال في حالة الاتحاد). يتم تمرير الفئة المعينة ("Foo" في المثال أدناه) وبيانات Json كمعلمات في الاستدعاء.

 $ mapper = function ( $ class , $ jvalue ) {
    // examine $class and $jvalue to figure out what class to use...
    return ' DateTime ' ;
};

$ jm = new JsonMapper ();
$ jm -> classMap [ ' Foo ' ] = $ mapper ;
$ jm -> map (...);

القيم الفارغة

يطرح JsonMapper استثناءً عندما تكون خاصية JSON null ، ما لم تكن خاصية فئة PHP تحتوي على نوع فارغ - على سبيل المثال Contact|null أو ?Contact .

إذا كانت واجهة برمجة التطبيقات الخاصة بك تحتوي على العديد من الحقول التي قد تكون null ولا ترغب في جعل جميع تعريفات الأنواع الخاصة بك فارغة، فقم بتعيين:

 $ jm -> bStrictNullTypes = false ;

منذ الإصدار 5.0.0، تؤدي القيم null في المصفوفات إلى JsonMapper_Exception ما لم يكن النوع خاليًا - على سبيل المثال array[?string] أو array[string|null] .

لاستعادة السلوك السابق (السماح بالقيم الخالية حتى عندما لا يتم الإعلان عن ذلك) قم بتعيين:

 $ jm -> bStrictNullTypesInArrays = false ;

التسجيل

تدعم طريقة setLogger() الخاصة بـ JsonMapper جميع مثيلات المسجل المتوافقة مع PSR-3.

الأحداث التي يتم تسجيلها:

• تحتوي بيانات JSON على مفتاح، لكن الفئة لا تحتوي على خاصية أو طريقة ضبط لها.
• لا يمكن تعيين أي واضع أو ملكية من الخارج لأنها محمية أو خاصة

التعامل مع البيانات غير الصالحة أو المفقودة

أثناء التطوير، غالبًا ما تتغير واجهات برمجة التطبيقات. للحصول على إشعارات بشأن هذه التغييرات، يمكن تكوين JsonMapper لطرح استثناءات في حالة فقدان البيانات أو عدم معرفتها بعد.

خصائص غير معروفة

عندما يرى JsonMapper خصائص في بيانات JSON غير محددة في فئة PHP، يمكنك السماح له بطرح استثناء عن طريق تعيين $bExceptionOnUndefinedProperty :

 $ jm = new JsonMapper ();
$ jm -> bExceptionOnUndefinedProperty = true ;
$ jm -> map (...);

يمكنك أيضًا اختيار التعامل مع هذه الخصائص بنفسك عن طريق تعيين عنصر قابل للاستدعاء إلى $undefinedPropertyHandler :

 /**
 * Handle undefined properties during JsonMapper::map()
 *
 * @param object $object    Object that is being filled
 * @param string $propName  Name of the unknown JSON property
 * @param mixed  $jsonValue JSON value of the property
 *
 * @return void
 */
function setUndefinedProperty ( $ object , $ propName , $ jsonValue )
{
    $ object ->{ ' UNDEF ' . $ propName } = $ jsonValue ;
}

$ jm = new JsonMapper ();
$ jm -> undefinedPropertyHandler = ' setUndefinedProperty ' ;
$ jm -> map (...);

أو إذا كنت ستسمح لـ JsonMapper بالتعامل مع أداة الضبط نيابةً عنك، فيمكنك إرجاع سلسلة من $undefinedPropertyHandler والتي سيتم استخدامها كاسم خاصية.

 /**
 * Handle undefined properties during JsonMapper::map()
 *
 * @param object $object    Object that is being filled
 * @param string $propName  Name of the unknown JSON property
 * @param mixed  $jsonValue JSON value of the property
 *
 * @return void
 */
function fixPropName ( $ object , $ propName , $ jsonValue )
{
    return ucfirst ( $ propName );
}

$ jm = new JsonMapper ();
$ jm -> undefinedPropertyHandler = ' fixPropName ' ;
$ jm -> map (...);

خصائص مفقودة

ملحوظة

يعمل هذا فقط عندما يظل $bStrictObjectTypeChecking ممكنًا.

يمكن وضع علامة على الخصائص الموجودة في فئات PHP الخاصة بك على أنها "مطلوبة" عن طريق وضع @required في docblock الخاص بها:

 /**
 * @var string
 * @required
 */
public $ someDatum ;

عندما لا تحتوي بيانات JSON على هذه الخاصية، فسيقوم JsonMapper بطرح JsonMapper_Exception عند تنشيط $bExceptionOnMissingData :

 $ jm = new JsonMapper ();
$ jm -> bExceptionOnMissingData = true ;
$ jm -> map (...);

يؤدي الخيار $bRemoveUndefinedAttributes إلى قيام JsonMapper بإزالة الخصائص من الكائن النهائي إذا لم تكن موجودة في بيانات JSON:

 $ jm = new JsonMapper ();
$ jm -> bRemoveUndefinedAttributes = true ;
$ jm -> map (...);

الخصائص والوظائف الخاصة

يمكنك السماح بالتخطيط للخصائص الخاصة والمحمية وطرق الضبط عن طريق ضبط $bIgnoreVisibility على true:

 $ jm = new JsonMapper ();
$ jm -> bIgnoreVisibility = true ;
$ jm -> map (...);

أنواع بسيطة بدلا من الكائنات

عندما يكون نوع المتغير فئة وبيانات JSON عبارة عن نوع بسيط مثل string ، يمكن لـ JsonMapper تمرير هذه القيمة إلى مُنشئ الفئة عند تكوينه للقيام بذلك:

 $ jm = new JsonMapper ();
$ jm -> bStrictObjectTypeChecking = false ;
$ jm -> map (...);

يمكن استخدام هذا لتهيئة كائنات DateTime تلقائيًا من سلاسل التاريخ.

قد يؤدي تعطيل عمليات التحقق الصارمة من نوع الكائن إلى حدوث مشكلات، على الرغم من ذلك:

• عندما لا تحتوي الفئة على مُنشئ أو لا توجد معلمة مُنشئة، ستفقد القيمة
• عندما يكون لدى المُنشئ أكثر من معلمة واحدة مطلوبة، فسوف يتعطل.
• عندما لا يتطابق نوع معلمة المنشئ مع البيانات الموجودة في JSON، فسوف يتعطل
• لن يتم ملء الخصائص @required

ملحوظة

تم تغيير القيمة الافتراضية من false إلى true في الإصدار 5 لزيادة الأمان.

الآن عليك الاشتراك إذا كنت تريد تمرير أنواع بسيطة إلى مُنشئ الفصل.

تمرير المصفوفات إلى map()

قد ترغب في تمرير بيانات المصفوفة إلى map() التي حصلت عليها عن طريق الاتصال

 json_decode ( $ jsonString , true )

افتراضيًا، سيقوم JsonMapper بطرح استثناء لأن map() تتطلب كائنًا كمعلمة أولى. يمكنك التحايل على ذلك عن طريق تعيين $bEnforceMapType على false :

 $ jm = new JsonMapper ();
$ jm -> bEnforceMapType = false ;
$ jm -> map (...);

رد الاتصال بعد التعيين

JsonMapper قادر على استدعاء طريقة مخصصة مباشرة على كل كائن بعد الانتهاء من تعيينه:

 $ jm = new JsonMapper ();
$ jm -> postMappingMethod = ' afterMapping ' ;
$ jm -> map (...);

الآن يتم استدعاء afterMapping() على كل كائن معين (إذا كان الفصل لديه هذه الطريقة).

يمكنك تمرير وسائط إضافية إلى رد الاتصال بعد التعيين:

 $ jm = new JsonMapper ();
$ jm -> postMappingMethod = ' afterMapping ' ;
$ jm -> postMappingMethodArguments = [ 23 , ' foo ' ];
$ jm -> map (...);

تثبيت

عبر الملحن من Packagist:

 $ الملحن يتطلب netresearch/jsonmapper

البرامج ذات الصلة

البدائل

• ربط بيانات جاكسون لجافا
• يوهانس شميت مُسلسِل PHP
• ميتاسيون ل PHP
• رسام الخرائط ل PHP
• كائن نقل البيانات ل PHP
• فالينور ل PHP
• مكتبة JsonMapper تحمل نفس الاسم ولها تبعيات.

حول جسونمابر

رخصة

JsonMapper مرخص بموجب OSL 3.0.

أسلوب الترميز

يتبع JsonMapper معايير ترميز PEAR.

مؤلف

كريستيان ويسكي، cweiske.de