Laravel/eloquent serialization

مقدمة

عند بناء واجهات JSON APIs، تحتاج معظم الأوقات إلى تحويل نماذجك وعلاقاتها إلى مصفوفات أو كائنات JSON. يزود Eloquent بمجموعة من التوابع المساعدة لهذه التحويلات، إضافةً إلى التحكم بالحقول التي يجب تضمينها في التحويلات.

سلسلة النماذج والمجموعات

السلسلة لمصفوفات

لتحويل نموذج وعلاقاته المحمّلة لمصفوفة، يمكنك استخدام التابع toArray. إن هذا التابع تعاودي، لذلك ستُحوّل كل الحقول وكل العلاقات (وعلاقات العلاقات) إلى مصفوفات:

$user = App\User::with('roles')->first();

return $user->toArray();

يمكنك أيضًا تحويل مجموعة كاملة من النماذج إلى مصفوفة:

$users = App\User::all();

return $users->toArray();

السلسلة لكائنات JSON

لتحويل نموذج إلى كائن JSON، يمكنك استخدام التابع toJson. بالمثل، التابع toJson هو تابع تعاودي، مما يعني أن جميع الحقول والعلاقات ستُحوّل إلى كائنات JSON. يمكنك أيضًا تحديد نمط ترميز JSON المدعوم من PHP:

$user = App\User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);

بالمثل، يمكنك تحويل نموذج أو مجموعة إلى سلسلة نصية، مما يستدعي تلقائيًّا التابع toJson على النموذج أو المجموعة:

$user = App\User::find(1);

return (string) $user;

بما أن النماذج والمجموعات تحوّل إلى كائنات JSON عند تحويلها إلى سلاسل نصية، يمكنك إعادة كائنات Eloquent مباشرةً من مسارات تطبيقك أو وحدات التحكم:

Route::get('users', function () {
   return App\User::all();
});

إخفاء الخاصيات من كائنات JSON

قد تحتاج أحيانًا إلى الحد من الوصول لبعض الخاصيات المضمنة في كائنات JSON المسلسلة من نماذجك، ككلمات السر. لتحقيق ذلك، أضف الخاصية hidden إلى نموذجك:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الحقول التي يجب إخفاؤها عند السلسلة.
    *
    * @var array
    */
   protected $hidden = ['password'];
}

ملاحظة: عند إخفاء العلاقات، استخدم اسم تابع العلاقة. بالمثل، يمكنك استخدام الخاصية visible لتعريف قائمة بيضاء بالخاصيات التي يجب تضمينها في التمثيل المسلسل لنماذجك. جميع الخاصيات الأخرى من النموذج ستُخفى عند سلسلة النموذج:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الخاصيات التي يجب إظهارها عند السلسلة.
    *
    * @var array
    */
   protected $visible = ['first_name', 'last_name'];
}

إظهار أو إخفاء الخاصيات مؤقتًا

إذا أردت إظهار بعض الخاصيات المخفية مسبقًا على كائن نموذج، يمكنك استخدام التابع makeVisible. يعيد التابع makeVisible نفس كائن النموذج وذلك لسهولة سلسلة التوابع:

return $user->makeVisible('attribute')->toArray();

بالمثل، إذا أردت إخفاء بعض الخاصيات الظاهرة، يمكنك استخدام التابع makeHidden:

return $user->makeHidden('attribute')->toArray();

إلحاق القيم إلى كائنات JSON

عند سلسلة النماذج، قد تحتاج إحيانًا إلى إلحاق خاصيات إضافية لا تقابلها أعمدة في جدول قاعدة البيانات. لتحقيق ذلك، عرّف بدايةً موصّل للقيمة:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * قراءة إذا كان المستخدم مديرًااً.
    *
    * @return bool
    */
   public function getIsAdminAttribute()
   {
       return $this->attributes['admin'] == 'yes';
   }
}

بعد إنشاء الموصل، أضف اسم الحقل الجديد إلى الخاصية appends على نموذجك. لاحظ أن أسماء الخاصيات تُحوّل تلقائيًّا إلى النمط snake_case، بينما يُعرّف الموصل بالصيغة camel case:

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الموصل الذي يجب تضمينه في النمط المسلسل من النموذج..
    *
    * @var array
    */
   protected $appends = ['is_admin'];
}

بعد إضافة الخاصية إلى المصفوفة appends، ستُضمّن تلقائيًّا في النمط المسلسل من النموذج. إن الحقول المعرفة في المصفوفة appends تراعي الإعدادات المعرفة مسبقًا في الخاصيتين visible و hidden.

الإلحاق أثناء التنفيذ Appending at Run Time

يمكنك إلحاق خاصية على كائن نموذج جديد أثناء التنفيذ وذلك باستخدام التابع append. أو يمكنك استخدام التابع setAppends لتعيين المصفوفة appends بشكل كامل على كائن النموذج المعطى:

return $user->append('is_admin')->toArray();

return $user->setAppends(['is_admin'])->toArray();

سلسلة الحقول الزمنية

تخصيص النمط الزمني لكل حقل على حدى

يمكنك تخصيص النمط الزمني المستخدم أثناء السلسلة للحقول الزمنية عن طريق تعريف النمط الزمني في التحويل المعرف:

protected $casts = [
   'birthday' => 'date:Y-m-d',
   'joined_at' => 'datetime:Y-m-d H:00',
];

تخصيص النمط الزمني بشكل عام عن طريق Carbon

يستخدم Laravel المكتبة Carbon للتعامل مع القيم والمتحولات الزمنية، إذ تزود هذه المكتبة تخصيصًا سهلًا لسلسلة الحقول الزمنية. لتخصيص كيفية سلسلة جميع القيم الزمنية من Carbon في تطبيقك، استخدم التابع Carbon::serializeUsing. يقبل التابع serializeUsing نطاقًا مغلقًا يعيد النمط النصي للنمط الزمني من أجل السلسلة:

<?php

namespace App\Providers;

use Illuminate\Support\Carbon;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
   /**
    * القيام بتشغيل التطبيق قبل التسجيل.
    *
    * @return void
    */
   public function boot()
   {
       Carbon::serializeUsing(function ($carbon) {
           return $carbon->format('U');
       });
   }
}

مصادر

• صفحة Eloquent: Serialization في توثيق Laravel الرسمي.