عرض مصدر Laravel/eloquent serialization

<noinclude>{{DISPLAYTITLE:السلسلة في رابط الكائنات بالعلاقات Eloquent}}</noinclude>
== مقدمة ==
عند بناء واجهات JSON APIs، تحتاج معظم الأوقات إلى تحويل نماذجك وعلاقاتها إلى مصفوفات أو كائنات [[JSON]]. يزود [[Laravel/eloquent|Eloquent]] بمجموعة من التوابع المساعدة لهذه التحويلات، إضافةً إلى التحكم بالحقول التي يجب تضمينها في التحويلات.

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

=== السلسلة لمصفوفات ===
لتحويل نموذج [[Laravel/eloquent-relationships|وعلاقاته]] المحمّلة لمصفوفة، يمكنك استخدام التابع <code>toArray</code>. إن هذا التابع تعاودي، لذلك ستُحوّل كل الحقول وكل العلاقات (وعلاقات العلاقات) إلى مصفوفات:<syntaxhighlight lang="php">
$user = App\User::with('roles')->first();

return $user->toArray();
</syntaxhighlight>يمكنك أيضًا تحويل [[Laravel/eloquent collections|مجموعة]] كاملة من النماذج إلى مصفوفة:<syntaxhighlight lang="php">
$users = App\User::all();

return $users->toArray();
</syntaxhighlight>

=== السلسلة لكائنات JSON ===
لتحويل نموذج إلى كائن JSON، يمكنك استخدام التابع <code>toJson</code>. بالمثل، التابع <code>toJson</code> هو تابع تعاودي، مما يعني أن جميع الحقول والعلاقات ستُحوّل إلى كائنات JSON. يمكنك أيضًا تحديد نمط ترميز JSON المدعوم من PHP:<syntaxhighlight lang="php">
$user = App\User::find(1);

return $user->toJson();

return $user->toJson(JSON_PRETTY_PRINT);
</syntaxhighlight>بالمثل، يمكنك تحويل نموذج أو مجموعة إلى سلسلة نصية، مما يستدعي تلقائيًّا التابع <code>toJson</code> على النموذج أو المجموعة:<syntaxhighlight lang="php">
$user = App\User::find(1);

return (string) $user;
</syntaxhighlight>بما أن النماذج والمجموعات تحوّل إلى كائنات [[JSON]] عند تحويلها إلى سلاسل نصية، يمكنك إعادة كائنات [[Laravel/eloquent|Eloquent]] مباشرةً من مسارات تطبيقك أو وحدات التحكم:<syntaxhighlight lang="php">
Route::get('users', function () {
   return App\User::all();
});
</syntaxhighlight>

== إخفاء الخاصيات من كائنات JSON ==
قد تحتاج أحيانًا إلى الحد من الوصول لبعض الخاصيات المضمنة في كائنات [[JSON]] المسلسلة من نماذجك، ككلمات السر. لتحقيق ذلك، أضف الخاصية <code>hidden</code> إلى نموذجك:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

بالمثل، يمكنك استخدام الخاصية <code>visible</code> لتعريف قائمة بيضاء بالخاصيات التي يجب تضمينها في التمثيل المسلسل لنماذجك. جميع الخاصيات الأخرى من النموذج ستُخفى عند سلسلة النموذج:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

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

==== إظهار أو إخفاء الخاصيات مؤقتًا ====
إذا أردت إظهار بعض الخاصيات المخفية مسبقًا على كائن نموذج، يمكنك استخدام التابع <code>makeVisible</code>. يعيد التابع <code>makeVisible</code> نفس كائن النموذج وذلك لسهولة سلسلة التوابع:<syntaxhighlight lang="php">
return $user->makeVisible('attribute')->toArray();
</syntaxhighlight>بالمثل، إذا أردت إخفاء بعض الخاصيات الظاهرة، يمكنك استخدام التابع <code>makeHidden</code>:<syntaxhighlight lang="php">
return $user->makeHidden('attribute')->toArray();
</syntaxhighlight>

== إلحاق القيم إلى كائنات JSON ==
عند سلسلة النماذج، قد تحتاج إحيانًا إلى إلحاق خاصيات إضافية لا تقابلها أعمدة في جدول قاعدة البيانات. لتحقيق ذلك، عرّف بدايةً [[Laravel/eloquent-mutators|موصّل]] للقيمة:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * قراءة إذا كان المستخدم مديرًااً.
    *
    * @return bool
    */
   public function getIsAdminAttribute()
   {
       return $this->attributes['admin'] == 'yes';
   }
}
</syntaxhighlight>بعد إنشاء الموصل، أضف اسم الحقل الجديد إلى الخاصية <code>appends</code> على نموذجك. لاحظ أن أسماء الخاصيات تُحوّل تلقائيًّا إلى النمط snake_case، بينما يُعرّف الموصل بالصيغة camel case:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الموصل الذي يجب تضمينه في النمط المسلسل من النموذج..
    *
    * @var array
    */
   protected $appends = ['is_admin'];
}
</syntaxhighlight>بعد إضافة الخاصية إلى المصفوفة <code>appends</code>، ستُضمّن تلقائيًّا في النمط المسلسل من النموذج. إن الحقول المعرفة في المصفوفة <code>appends</code> تراعي الإعدادات المعرفة مسبقًا في الخاصيتين <code>visible</code> و <code>hidden</code>.

==== الإلحاق أثناء التنفيذ Appending at Run Time ====
يمكنك إلحاق خاصية على كائن نموذج جديد أثناء التنفيذ وذلك باستخدام التابع <code>append</code>. أو يمكنك استخدام التابع <code>setAppends</code> لتعيين المصفوفة <code>appends</code> بشكل كامل على كائن النموذج المعطى:<syntaxhighlight lang="php">
return $user->append('is_admin')->toArray();

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

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

==== تخصيص النمط الزمني لكل حقل على حدى ====
يمكنك تخصيص النمط الزمني المستخدم أثناء السلسلة للحقول الزمنية عن طريق تعريف النمط الزمني في [[Laravel/eloquent mutators|التحويل المعرف]]:<syntaxhighlight lang="php">
protected $casts = [
   'birthday' => 'date:Y-m-d',
   'joined_at' => 'datetime:Y-m-d H:00',
];
</syntaxhighlight>

==== تخصيص النمط الزمني بشكل عام عن طريق Carbon ====
يستخدم Laravel المكتبة [https://github.com/briannesbitt/Carbon Carbon] للتعامل مع القيم والمتحولات الزمنية، إذ تزود هذه المكتبة تخصيصًا سهلًا لسلسلة الحقول الزمنية. لتخصيص كيفية سلسلة جميع القيم الزمنية من Carbon في تطبيقك، استخدم التابع <code>Carbon::serializeUsing</code>. يقبل التابع <code>serializeUsing</code> نطاقًا مغلقًا يعيد النمط النصي للنمط الزمني من أجل السلسلة:<syntaxhighlight lang="php">
<?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');
       });
   }
}
</syntaxhighlight>

== مصادر ==
* [https://laravel.com/docs/5.6/eloquent-serialization صفحة Eloquent: Serialization في توثيق Laravel الرسمي.]
[[تصنيف:Laravel|{{SUBPAGENAME}}]]
[[تصنيف:Laravel Eloquent ORM|{{SUBPAGENAME}}]]