راهنمای جامع API Resources در لاراول

لاراول ابزارهای قدرتمندی برای توسعه سریع و بهینه وب‌سایت‌ها ارائه می‌دهد. یکی از این قابلیت‌های کلیدی، API Resources است. این ویژگی به شما اجازه می‌دهد تا مدل‌های Eloquent خود را به سادگی به ساختار JSON تبدیل کنید. در واقع، این ابزار یک لایه تبدیلی بین مدل‌ها و پاسخ نهایی API ایجاد می‌کند. این کار کنترل شما بر خروجی API را به شکل چشمگیری افزایش می‌دهد.

در گذشته، توسعه‌دهندگان لاراول اغلب از پکیج‌هایی مانند Fractal استفاده می‌کردند. اما از نسخه ۵.۵ به بعد، لاراول این قابلیت را به صورت داخلی ارائه کرد. این ویژگی به قدری کارآمد است که نیاز به استفاده از ابزارهای جانبی را تقریباً از بین برده است. در این مقاله، به صورت کامل یاد می‌گیریم که API Resources چیست و چگونه می‌توانیم از آن برای ساخت APIهای تمیز و استاندارد استفاده کنیم. 🧐

چرا باید از API Resources لاراول استفاده کنیم؟ 🚀

استفاده از این قابلیت مزایای مهمی برای پروژه شما به همراه دارد. شاید در ابتدا تصور کنید که می‌توانید داده‌ها را مستقیماً از کنترلر به JSON تبدیل کنید. اما این کار در پروژه‌های بزرگ به سرعت باعث پیچیدگی و عدم خوانایی کد می‌شود. API Resources این فرآیند را ساختاریافته و مدیریت‌پذیر می‌کند.

در ادامه به مهم‌ترین مزیت‌های آن اشاره می‌کنیم:

✅ کنترل کامل بر خروجی JSON: شما دقیقاً مشخص می‌کنید کدام فیلدها از مدل نمایش داده شوند. همچنین می‌توانید نام فیلدها را تغییر دهید یا فیلدهای جدیدی بر اساس داده‌های موجود بسازید.
🔄 استانداردسازی پاسخ‌ها: با استفاده از یک ساختار ثابت برای تمام خروجی‌های API، ثبات و یکپارچگی پروژه حفظ می‌شود. این موضوع کار را برای توسعه‌دهندگان فرانت‌اند بسیار آسان‌تر می‌کند.
🧹 جداسازی منطق نمایش از مدل: مدل‌های شما فقط وظیفه تعامل با دیتابیس را بر عهده دارند. منطق مربوط به نحوه نمایش داده‌ها در API به کلاس‌های Resource منتقل می‌شود. این کار به تمیز ماندن کد (Clean Code) کمک شایانی می‌کند.
🔗 مدیریت آسان روابط (Relationships): شما می‌توانید به سادگی داده‌های مربوط به مدل‌های دیگر (مانند نمایش اطلاعات نویسنده یک پست) را در خروجی خود قرار دهید.
⚙️ افزودن داده‌های اضافی (Metadata): گاهی نیاز دارید اطلاعات بیشتری مانند لینک‌ها یا وضعیت درخواست را به پاسخ API اضافه کنید. این کار با API Resources به راحتی امکان‌پذیر است.

آموزش گام به گام ساخت و استفاده از API Resources

اکنون که با مزیت‌های این ابزار آشنا شدیم، بیایید یک مثال عملی را با هم بررسی کنیم. فرض کنید یک مدل User داریم و می‌خواهیم اطلاعات کاربران را از طریق یک API در دسترس قرار دهیم.

گام اول: ایجاد یک Resource جدید

ابتدا باید با استفاده از دستور Artisan یک کلاس Resource برای مدل User خود بسازیم. ترمینال را باز کرده و دستور زیر را اجرا کنید:

php

php artisan make:resource UserResource

پس از اجرای این دستور، یک فایل جدید به نام UserResource.php در مسیر app/Http/Resources ایجاد می‌شود. محتوای اولیه این فایل به شکل زیر است:

php

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class UserResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return parent::toArray($request);
    }
}

این کلاس در حال حاضر تمام فیلدهای مدل را به صورت پیش‌فرض برمی‌گرداند.

گام دوم: شخصی‌سازی خروجی در متد `toArray`

جادوی اصلی API Resources در متد toArray اتفاق می‌افتد. ما می‌توانیم این متد را ویرایش کنیم تا خروجی را دقیقاً مطابق با نیاز خود شکل دهیم. برای مثال، فرض کنید نمی‌خواهیم فیلدهای password و updated_at در خروجی نمایش داده شوند. همچنین می‌خواهیم نام فیلد telephone را به phone تغییر دهیم و یک URL کامل برای آواتار کاربر بسازیم.

کلاس UserResource را به شکل زیر ویرایش می‌کنیم:

php

public function toArray(Request $request): array
{
    return [
        'user_id' => $this->id,
        'full_name' => $this->name,
        'email_address' => $this->email,
        'phone' => (int) $this->telephone,
        'avatar_url' => url($this->photo),
        'registration_date' => $this->created_at->toDateTimeString(),
    ];
}

تغییرات اعمال شده:

فیلدهای غیرضروری حذف شده‌اند.
نام کلیدها برای خوانایی بیشتر تغییر کرده است (مانند id به user_id).
مقدار telephone به عدد صحیح (integer) تبدیل شده است.
یک URL معتبر برای تصویر آواتار با استفاده از تابع url() ساخته شده است.
تاریخ ثبت‌نام با فرمت استاندارد نمایش داده می‌شود.

گام سوم: استفاده از Resource در کنترلر

حالا فقط کافی است در کنترلر خود، به جای برگرداندن مستقیم مدل، آن را از طریق کلاس Resource برگردانیم. کنترلر UserController را باز کرده و متد show را به این صورت بنویسید:

php

<?php

namespace App\Http\Controllers;

use App\Models\User;
use App\Http\Resources\UserResource;

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

همانطور که می‌بینید، ما نمونه‌ای از مدل User را به سازنده UserResource پاس می‌دهیم. لاراول به صورت خودکار متد toArray را فراخوانی کرده و خروجی را به فرمت JSON استاندارد تبدیل می‌کند. 🔥

نتیجه نهایی درخواست به این آدرس api/users/1 چیزی شبیه به این خواهد بود:

json

{
    "data": {
        "user_id": 1,
        "full_name": "Reza Ahmadi",
        "email_address": "reza@example.com",
        "phone": 9123456789,
        "avatar_url": "http://yourdomain.com/images/avatar.jpg",
        "registration_date": "2026-08-14 10:00:00"
    }
}

توجه کنید که لاراول به صورت خودکار خروجی را داخل یک کلید data قرار می‌دهد. این یک استاندارد رایج در طراحی API است.

کاربردهای پیشرفته‌تر API Resources

قابلیت‌های این ابزار به موارد بالا محدود نمی‌شود. در ادامه به چند کاربرد پیشرفته‌تر اشاره می‌کنیم.

مدیریت کالکشن‌ها (Collections)

اگر بخواهید لیستی از کاربران را برگردانید، نیازی به ایجاد یک Resource جداگانه نیست. می‌توانید از متد استاتیک collection استفاده کنید:

php

use App\Http\Resources\UserResource;
use App\Models\User;

// در کنترلر
public function index()
{
    return UserResource::collection(User::all());
}

این دستور همان UserResource را برای هر آیتم در کالکشن User اعمال می‌کند.

افزودن داده‌های شرطی

گاهی اوقات می‌خواهید یک فیلد فقط تحت شرایط خاصی به خروجی اضافه شود. برای مثال، نمایش اطلاعات مدیریتی فقط برای کاربران ادمین.

php

'is_admin' => $this->when($this->isAdmin(), true),

در این مثال، کلید is_admin فقط زمانی به خروجی اضافه می‌شود که نتیجه متد isAdmin() در مدل User برابر با true باشد.

مدیریت API‌های شما با پلتفرم p.api.ir

وقتی API شما آماده شد، مدیریت، مستندسازی و ارائه آن به کاربران اهمیت پیدا می‌کند. پلتفرم api.ir یک راهکار جامع برای مدیریت وب‌سرویس‌های شما ارائه می‌دهد. شما می‌توانید به راحتی سرویس‌های خود را ثبت کرده و از امکانات آن بهره‌مند شوید.

برای شروع کار با این پلتفرم:

به لینک p.api.ir مراجعه کنید.
با چند کلیک ساده، حساب کاربری خود را ایجاد نمایید.
سرویس API خود را ثبت و پیکربندی کنید.

این پلتفرم به شما در مدیریت ترافیک، سطوح دسترسی و ارائه مستندات شفاف کمک می‌کند.

جمع‌بندی 🎯

API Resources یکی از قدرتمندترین و کاربردی‌ترین ویژگی‌های فریم‌ورک لاراول است. این ابزار به شما کمک می‌کند تا پاسخ‌های API خود را به شکلی تمیز، ساختاریافته و استاندارد طراحی کنید. با جداسازی لایه نمایش داده از منطق اصلی برنامه، نگهداری و توسعه پروژه در بلندمدت بسیار ساده‌تر خواهد شد. بنابراین، در پروژه‌های بعدی خود حتماً از این قابلیت شگفت‌انگیز استفاده کنید.

شما از چه روشی برای مدیریت خروجی API در پروژه‌های لاراول خود استفاده می‌کنید؟ تجربیات خود را در بخش نظرات با ما به اشتراک بگذارید!