احسان رضایی

هنگام پیاده سازی API یکی از شیوه های بسیار کاربردی و مفیدی که میشه استفاده کرد API Resources هست. با استفاده از این روش به جای پاس دادن مدل یا آرایه ای از مدل ها به عنوان response، لایه ای بین Eloquent و خروجی JSON تعریف میشه. در این لایه که Resource/منبع نام داره دقیقا مشخص میکنیم چه دیتایی به عنوان JSON پاس بدیم. این کار باعث میشه response همون چیزی باشه که نیازش داریم، بدون اضافات. یا اینکه ممکن هست لازم بشه همیشه همراه با مدل، روابط خاصی رو هم داشته باشیم و یا در جاهای خاص، خروجی متفاوتی از یک مدل رو به نمایش بذاریم.

به عنوان مثال جدول کاربران شامل نام و نام خانوادگی، بیو، ایمیل، تاریخ ایجاد، بروزرسانی و حذف(deleted_at) رو در نظر بگیرید. برای سرویس لیست کاربران قرار نیست متن بیو رو نشون بدیم. deleted_at هم که برای soft delete هست و 99 درصد اوقات کلا نیازی به نمایش نداریم. پس همونطور که جلوتر پیاده سازیش رو توضیح میدم، دوتا Resource ایجاد میکنیم، یکی برای لیست کاربران که فیلدهای id, name, email  در اون تعریف میشه و یکی هم برای نمایش تکی کاربر که شامل تمام فیلدهاست.

شاید با خودتون فکر کنید بدون API Resources در لاراول هم میشه این کار رو انجام داد. بله اما تمیز نیست و قابلیت استفاده مجدد مثل Resources هم ندارید.

ایجاد Resources

با استفاده از artisan و دستور make:resource به راحتی میتونید resource جدید ایجاد کنید.

php artisan make:resource UserResource

در مسیر App\Http\Resources منبع جدید ایجاد میشه. اینجاست که باید مشخص کنیم دقیقا چه اطلاعاتی به عنوان response پاس داده بشه.

<?php
 
namespace App\Http\Resources;
 
use Illuminate\Http\Resources\Json\JsonResource;
 
class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
        ];
    }
}

در مثال بالا مشخص شد هنگام استفاده از این منبع، id, name, email از مدل User به عنوان خروجی JSON ارسال بشه.

استفاده از Resource 

برای استفاده از Resource دو حالت داریم. تکی و لیست. برای حالت تکی، یعنی زمانی که میخواییم فقط یک مدل(طبق مثال یک user یا یک سطر از جدول users) رو پاس بدیم کافی هست که با استفاده از دستور new یک شی از منبع مورد نظرمون ایجاد، مدل رو به عنوان پارامتر فرستاده و خروجی رو return کنیم.

class UserController extends Controller
{
    public function view(User $user)
    {
        return new UserResource($user);
    }
// ...

 برای حالت دوم، یعنی لیستی از کاربران، از متد collection استفاده میکنیم.

class UserController extends Controller
{
    public function index()
    {
        $users = User::query()->latest()->get();
        return UserResource::collection($users);
    }
// ...

مطالعه بیشتر...