عرض مصدر Laravel/eloquent mutators

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

إضافةً إلى المعدلات والموصلات الافتراضية، يمكّنك [[Laravel/eloquent|Eloquent]] من التحويل التلقائي للخاصيات الزمنية إلى كائنات من الصنف [https://github.com/briannesbitt/Carbon Carbon] أو حتى تحويل الخاصيات النصية إلى كائنات JSON.

== المعدلات والموصلات ==

=== تعريف الموصل ===
لتعريف موصل ما، عرف التابع <code>getFooAttribute</code> على صنف نموذجك حيث <code>Foo</code> هو اسم الحقل المراد الوصول إليه (بعد تحويل صيغة الاسم إلى PascalCase). في هذا المثال، سنعرف موصل للحقل <code>first_name</code>. سيُستدعى الموصل تلقائيًّا من قبل Eloquent عند استرداد قيمة الحقل <code>first_name</code>:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * قراءة الاسم الأول للمستخدم..
    *
    * @param  string $value
    * @return string
    */
   public function getFirstNameAttribute($value)
   {
       return ucfirst($value);
   }
}
</syntaxhighlight>كما نرى، تُمرّر القيمة الافتراضية للحقل إلى تابع الموصل، مما يتيح لك تعديل هذه القيمة. للوصول إلى القيمة المعدلة من قبل الموصل، قم بالوصول إلى الخاصية <code>first_name</code> على نموذجك:<syntaxhighlight lang="php">
$user = App\User::find(1);

$firstName = $user->first_name;
</syntaxhighlight>وبالطبع، يمكنك استخدام الموصلات لإنشاء قيم جديدة ومحسوبة تلقائيًّا من القيم الموجودة مسبقًا:<syntaxhighlight lang="php">
/**
* قراءة الاسم الكامل للمستخدم..
*
* @return string
*/
public function getFullNameAttribute()
{
   return "{$this->first_name} {$this->last_name}";
}
</syntaxhighlight>

=== تعريف المعدل ===
لتعريف معدل ما، عرف التابع <code>setFooAttribute</code> على صنف نموذجك حيث <code>Foo</code> هو اسم الحقل المراد التعديل عليه (بعد تحويل صيغة الاسم إلى PascalCase). لذلك مجددًا، سنعرف معدل للحقل <code>first_name</code>. سيُستدعى المعدل تلقائيًّا من قبل [[Laravel/eloquent|Eloquent]] عند تعيين قيمة الحقل <code>first_name</code>:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * تعيين الاسم الأول للمستخدم.
    *
    * @param  string $value
    * @return void
    */
   public function setFirstNameAttribute($value)
   {
       $this->attributes['first_name'] = strtolower($value);
   }
}
</syntaxhighlight>يتلقى المعدل القيمة المراد تعيينها على الخاصية، مما يتيح لك تعديل هذه القيمة وتعيينها على الخاصية <code>attributes</code> الداخلية لنماذج Eloquent. مثلاً، إذا أردنا تعيين الاسم الأول ليصبح <code>Sally</code>:<syntaxhighlight lang="php">
$user = App\User::find(1);

$user->first_name = 'Sally';
</syntaxhighlight>في هذا المثال، سيُستدعى التابع <code>setFirstNameAttribute</code> وتُمرّر القيمة <code>Sally</code> له. سيطبّق المعدل بعد ذلك التابع <code>strtolower</code> للاسم ويعيّنه للحقل.

== المعدلات الزمنية ==
يحوّل Eloquent افتراضيًّا الحقلين <code>created_at</code> و <code>updated_at</code> لكائنات من النوع [https://github.com/briannesbitt/Carbon Carbon]، الذي يرث من الصنف الداخلي <code>DateTime</code> الخاص بـ [[PHP]] لتزويد مجموعة من التوابع المساعدة. يمكنك تخصيص الحقول الزمنية التي تُعدّل، أو إلغاء التعديل بأكمله، عن طريق إعادة تعيين الخاصية <code>dates</code> على نموذجك:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الخاصيات التي يجب تحويلها إلى كائنات زمنية.
    *
    * @var array
    */
   protected $dates = [
       'created_at',
       'updated_at',
       'deleted_at'
   ];
}
</syntaxhighlight>عند اعتبار حقل ما زمنيًّا، يمكنك تعيين قيمته إلى طابع زمني UNIX، أو نص تاريخ (<code>Y-m-d</code>)، أو كائن من النوع <code>DateTime</code> أو <code>Carbon</code>؛ وستُخزّن القيمة الزمنية تلقائيًّا وبشكل صحيح في قاعدة البيانات:<syntaxhighlight lang="php">
$user = App\User::find(1);

$user->deleted_at = now();

$user->save();
</syntaxhighlight>كما ذُكر آنفًا، عند استرداد القيم الموجودة في مصفوفة <code>dates</code>، ستُحوّل تلقائيًّا إلى كائن من نوع [https://github.com/briannesbitt/Carbon Carbon]، مما يتيح لك استخدام أي من توابع Carbon على هذه الحقول:<syntaxhighlight lang="php">
$user = App\User::find(1);

return $user->deleted_at->getTimestamp();
</syntaxhighlight>

==== تنسيق الحقول الزمنية ====
تُنسّق الحقول الزمنية افتراضيًّا بالنمط '<code>Y-m-d H:i:s</code>'. إذا أردت تخصيص هذا النمط، عيّن الخاصية <code>dateFormat</code> على نموذجك. تحدد هذه الخاصية كيفية تخزين القيم الزمنية في قاعدة بياناتك، وكيفية تنسيق هذه القيم عند سلسلتها إلى مصفوفة أو كائن JSON:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
   /**
    * نمط تخزين الحقول الزمنية.
    *
    * @var string
    */
   protected $dateFormat = 'U';
}
</syntaxhighlight>

== تحويل الحقول ==
تزوّد الخاصية <code>casts</code> في نموذجك بتابع مساعد لتحويل الحقول إلى أنواع بيانات معروفة. يجب أن تكون الخاصية <code>casts</code> مصفوفة، تكون المفاتيح فيها أسماء الحقول التي ستُحوّل، والقيم أنواع البيانات التي تُحوّل إليها. إن التحويلات المتاحة هي: <code>integer</code>, <code>real</code>, <code>float</code>, <code>double</code>, <code>string</code>, <code>boolean</code>, <code>object</code>, <code>array</code>, <code>collection</code>, <code>date</code>, <code>datetime</code>, و <code>timestamp</code>.

لنحوّل على سبيل المثال الحقل <code>is_admin</code>، الذي يُخزن في قاعدة البيانات كقيمة صحيحة (0 أو 1)، إلى قيمة منطقية <code>boolean</code>:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الحقول التي يجب تحويلها.
    *
    * @var array
    */
   protected $casts = [
       'is_admin' => 'boolean',
   ];
}
</syntaxhighlight>الآن، سيُحوّل الحقل <code>is_admin</code> تلقائيًّا إلى قيمة منطقية عند الوصول إليها، حتى ولو كان نمط تخزينها في قاعدة البيانات قيمة صحيحة:<syntaxhighlight lang="php">
$user = App\User::find(1);

if ($user->is_admin) {

  //

}
</syntaxhighlight>

=== تحويلات المصفوفات وكائنات JSON ===
يساعد نمط التحويل <code>array</code> بشكل خاص عند العمل مع الحقول التي تُخزّن القيم المسلسلة كـ JSON فيها. مثلاً، إذا احتوت قاعدة بياناتك على حقل من النوع <code>JSON</code> أو <code>TEXT</code> يحتوي على كائن JSON مسلسل، عند إضافة التحويل <code>array</code> إلى ذلك الحقل، ستُفكّ السلسلة تلقائيًّا إلى مصفوفة PHP عند الوصول إلى هذا الحقل على نموذج [[Laravel/eloquent|Eloquent]]:<syntaxhighlight lang="php">
<?php

namespace App;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
   /**
    * الحقول التي يجب تحويلها.
    *
    * @var array
    */
   protected $casts = [
       'options' => 'array',
   ];
}
</syntaxhighlight>بعد تعريف التحويل، يمكنك الوصول إلى الحقل <code>options</code> وستُفكّ السلسلة تلقائيًّا من [[JSON]] إلى مصفوفة [[PHP]]. عند تعيين قيم الحقل <code>options</code>، ستُحوّل المصفوفة المعطاة تلقائيًّا إلى كائن [[JSON]] مسلسل وذلك للتخزين:<syntaxhighlight lang="php">
$user = App\User::find(1);

$options = $user->options;

$options['key'] = 'value';

$user->options = $options;

$user->save();
</syntaxhighlight>

=== تحويلات الأزمان ===
عند استخدام نمط التحويل <code>date</code> أو <code>datetime</code>، يمكنك تعيين النمط الزمني. سيُستخدم هذا النمط عند [[Laravel/eloquent serialization|سلسلة السجل إلى مصفوفة أو كائن JSON]]:<syntaxhighlight lang="php">
/**
* الحقول التي يجب تحويلها.
*
* @var array
*/
protected $casts = [
   'created_at' => 'datetime:Y-m-d',
];
</syntaxhighlight>

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