الکوئنت: سریال سازی

• معرفی
• سریال سازی مدل ها و مجموعه ها
  • سریال سازی به آرایه ها
  • پخش سریال به JSON
• پنهان کردن ویژگی ها از JSON
• افزودن مقادیر به JSON
• سریال سازی تاریخ

معرفی

هنگام ساخت API با استفاده از لاراول، اغلب نیاز دارید که مدل ها و روابط خود را به آرایه یا JSON تبدیل کنید. Eloquent شامل روش‌های راحت برای انجام این تبدیل‌ها، و همچنین کنترل ویژگی‌هایی است که در نمایش سریالی مدل‌های شما گنجانده شده‌اند.

برای یک روش قوی تر برای مدیریت مدل Eloquent و مجموعه JSON سریال سازی، مستندات منابع API Eloquent را بررسی کنید .

سریال سازی مدل ها و مجموعه ها

سریال سازی به آرایه ها

برای تبدیل یک مدل و روابط بارگذاری شده آن به یک آرایه، باید از toArray روش استفاده کنید. این روش بازگشتی است، بنابراین تمام ویژگی ها و همه روابط (از جمله روابط روابط) به آرایه تبدیل می شوند:

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

این attributesToArray روش ممکن است برای تبدیل ویژگی های یک مدل به یک آرایه استفاده شود، اما نه روابط آن:

$user = User::first();
 
return $user->attributesToArray();

همچنین می توانید کل مجموعه مدل ها را با فراخوانی toArray متد در نمونه مجموعه به آرایه تبدیل کنید:

$users = User::all();
 
return $users->toArray();

پخش سریال به JSON

برای تبدیل یک مدل به JSON، باید از toJson روش استفاده کنید. مانند toArray ، toJson روش بازگشتی است، بنابراین تمام ویژگی ها و روابط به JSON تبدیل می شوند. همچنین می‌توانید گزینه‌های کدگذاری JSON که توسط PHP پشتیبانی می‌شوند را مشخص کنید :

use App\Models\User;
 
$user = User::find(1);
 
return $user->toJson();
 
return $user->toJson(JSON_PRETTY_PRINT);

همچنین، می‌توانید یک مدل یا مجموعه را به یک رشته ارسال کنید، که به طور خودکار toJson متد را در مدل یا مجموعه فراخوانی می‌کند:

return (string) User::find(1);

از آنجایی که مدل‌ها و مجموعه‌ها هنگام فرستادن به رشته به JSON تبدیل می‌شوند، می‌توانید اشیاء Eloquent را مستقیماً از مسیرها یا کنترل‌کننده‌های برنامه خود برگردانید. لاراول به‌طور خودکار مدل‌ها و مجموعه‌های Eloquent شما را وقتی که از مسیرها یا کنترلرها برگردانده می‌شوند به JSON تبدیل می‌کند:

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

روابط

هنگامی که یک مدل Eloquent به JSON تبدیل می شود، روابط بارگذاری شده آن به طور خودکار به عنوان ویژگی در شی JSON گنجانده می شود. همچنین، اگرچه روش‌های ارتباط Eloquent با استفاده از نام‌های متد "camel case" تعریف می‌شوند، ویژگی JSON یک رابطه، "snake case" خواهد بود.

پنهان کردن ویژگی ها از JSON

گاهی اوقات ممکن است بخواهید ویژگی هایی مانند رمزهای عبور را که در آرایه مدل شما یا نمایش JSON گنجانده شده اند، محدود کنید. برای انجام این کار، یک $hidden ویژگی به مدل خود اضافه کنید. ویژگی‌هایی که در آرایه ویژگی فهرست شده‌اند $hidden در نمایش سریالی مدل شما لحاظ نمی‌شوند:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The attributes that should be hidden for arrays.
     *
     * @var array
     */
    protected $hidden = ['password'];
}

برای پنهان کردن روابط، نام متد رابطه را به $hidden ویژگی مدل Eloquent خود اضافه کنید.

از طرف دیگر، می‌توانید از این visible ویژگی برای تعریف «لیست مجاز» از ویژگی‌هایی که باید در آرایه مدل شما و نمایش JSON استفاده شود، استفاده کنید. $visible هنگامی که مدل به آرایه یا JSON تبدیل می شود، تمام ویژگی هایی که در آرایه وجود ندارند پنهان می شوند:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The attributes that should be visible in arrays.
     *
     * @var array
     */
    protected $visible = ['first_name', 'last_name'];
}

تغییر موقت نمایان بودن ویژگی

اگر می‌خواهید برخی از ویژگی‌های پنهان را در یک نمونه مدل مشخص نمایان کنید، می‌توانید از این makeVisible روش استفاده کنید. متد makeVisible نمونه مدل را برمی گرداند:

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

به همین ترتیب، اگر می‌خواهید برخی از ویژگی‌هایی را که معمولاً قابل مشاهده هستند پنهان کنید، می‌توانید از makeHidden روش استفاده کنید.

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

اگر می خواهید به طور موقت همه ویژگی های قابل مشاهده یا پنهان را لغو کنید، می توانید به ترتیب از روش های setVisible و استفاده کنید setHidden :

return $user->setVisible(['id', 'name'])->toArray();
 
return $user->setHidden(['email', 'password', 'remember_token'])->toArray();

افزودن مقادیر به JSON

گاهی اوقات، هنگام تبدیل مدل ها به آرایه یا JSON، ممکن است بخواهید ویژگی هایی را اضافه کنید که ستون مربوطه در پایگاه داده شما ندارند. برای انجام این کار، ابتدا یک Accessor برای مقدار تعریف کنید:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * Determine if the user is an administrator.
     */
    protected function isAdmin(): Attribute
    {
        return new Attribute(
            get: fn () => 'yes',
        );
    }
}

اگر می‌خواهید که دسترسی همیشه به آرایه مدل شما و نمایش‌های JSON اضافه شود، می‌توانید نام ویژگی را به ویژگی appends مدل خود اضافه کنید. توجه داشته باشید که نام‌های ویژگی معمولاً با استفاده از نمایش سریالی «مورد مار» ارجاع می‌شوند، حتی اگر متد PHP دسترسی با استفاده از «مورد شتر» تعریف شده باشد:

<?php
 
namespace App\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class User extends Model
{
    /**
     * The accessors to append to the model's array form.
     *
     * @var array
     */
    protected $appends = ['is_admin'];
}

هنگامی که ویژگی به لیست اضافه شد appends ، هم در آرایه مدل و هم در نمایش JSON گنجانده می شود. ویژگی های موجود در appends آرایه نیز به تنظیمات visible و hidden تنظیمات پیکربندی شده روی مدل احترام می گذارند.

در زمان اجرا اضافه می شود

در زمان اجرا، ممکن است به یک نمونه مدل دستور دهید تا با استفاده از append روش، ویژگی‌های اضافی را اضافه کند. یا، می‌توانید از این setAppends روش برای نادیده گرفتن کل آرایه ویژگی‌های ضمیمه شده برای یک نمونه مدل استفاده کنید:

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

سریال سازی تاریخ

سفارشی کردن قالب پیش فرض تاریخ

می‌توانید با نادیده گرفتن روش، قالب سریال‌سازی پیش‌فرض را سفارشی کنید serializeDate . این روش بر نحوه قالب بندی تاریخ های شما برای ذخیره سازی در پایگاه داده تأثیر نمی گذارد:

/**
 * Prepare a date for array / JSON serialization.
 */
protected function serializeDate(DateTimeInterface $date): string
{
    return $date->format('Y-m-d');
}

سفارشی کردن قالب تاریخ در هر ویژگی

می‌توانید با تعیین قالب تاریخ در اعلان‌های بازیگران مدل، قالب سریال‌سازی ویژگی‌های تاریخ Eloquent را سفارشی کنید :

protected function casts(): array
{
    return [
        'birthday' => 'date:Y-m-d',
        'joined_at' => 'datetime:Y-m-d H:00',
    ];
}