در لاراول، API Resources ابزاری بسیار مفید برای تبدیل داده‌ها به فرمت‌های مناسب برای ارسال به کلاینت‌ها (مانند JSON) است. این ویژگی به شما این امکان را می‌دهد که مدل‌ها و مجموعه‌های داده را به راحتی به JSON تبدیل کنید و در آن‌ها مقادیر مورد نظر را به‌طور دلخواه فیلتر، فرمت یا تغییر دهید.

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

فصل 1: ایجاد یک API Resource

برای ایجاد یک API Resource جدید در لاراول، از دستور php artisan make:resource استفاده می‌کنید. این دستور یک کلاس resource جدید ایجاد می‌کند که می‌توانید آن را برای تبدیل مدل‌ها به فرمت JSON شخصی‌سازی کنید.

1. ایجاد یک API Resource جدید:

   به‌عنوان مثال، فرض کنید یک مدل به نام Post دارید و می‌خواهید داده‌های آن را به فرمت مناسب برای API بازگردانید:

   bash
   CopyEdit
   php artisan make:resource PostResource
   

   این دستور یک کلاس جدید در مسیر app/Http/Resources/PostResource.php ایجاد می‌کند.

فصل 2: شخصی‌سازی API Resource

بعد از ایجاد PostResource، شما می‌توانید روش toArray را در این کلاس برای تبدیل مدل به آرایه‌ای از داده‌ها تغییر دهید. این داده‌ها بعداً به فرمت JSON تبدیل خواهند شد.

1. ساختار PostResource:

   در داخل کلاس PostResource، متد toArray به طور پیش‌فرض مدل را به آرایه‌ای از ویژگی‌ها تبدیل می‌کند. می‌توانید این متد را برای کنترل دقیق‌تر داده‌ها و فرمت JSON پیاده‌سازی کنید:

   php
   CopyEdit
   // app/Http/Resources/PostResource.php
   namespace App\Http\Resources;
   
   use Illuminate\Http\Resources\Json\JsonResource;
   
   class PostResource extends JsonResource
   {
       /**
        * تبدیل داده‌ها به آرایه.
        *
        * @param  \Illuminate\Http\Request  $request
        * @return array
        */
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'title' => $this->title,
               'content' => $this->content,
               'created_at' => $this->created_at->toDateTimeString(),
               'updated_at' => $this->updated_at->toDateTimeString(),
           ];
       }
   }
   

   در این مثال، ما فقط ویژگی‌های id, title, content, created_at, و updated_at مدل را به عنوان داده‌های خروجی باز می‌گردانیم. این باعث می‌شود که اطلاعات اضافی حذف شده و فقط داده‌های ضروری به کلاینت ارسال شوند.

2. استفاده از API Resource در کنترلر:

   برای استفاده از PostResource در کنترلر، به راحتی می‌توانید از آن برای بازگشت داده‌ها به کلاینت استفاده کنید. به‌عنوان مثال، در کنترلر PostController:

   php
   CopyEdit
   // app/Http/Controllers/PostController.php
   namespace App\Http\Controllers;
   
   use App\Models\Post;
   use App\Http\Resources\PostResource;
   
   class PostController extends Controller
   {
       /**
        * نمایش لیست تمامی پست‌ها.
        *
        * @return \Illuminate\Http\Response
        */
       public function index()
       {
           $posts = Post::all();
   
           // استفاده از PostResource برای بازگشت داده‌ها
           return PostResource::collection($posts);
       }
   }
   

   در اینجا، PostResource::collection($posts) برای بازگرداندن مجموعه‌ای از پست‌ها به‌صورت JSON استفاده می‌شود. این به طور خودکار هر پست را با استفاده از PostResource تبدیل می‌کند.

فصل 3: استفاده از Additional و Meta در API Resources

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

1. اضافه کردن داده‌های اضافی:

   برای اضافه کردن داده‌های اضافی مانند meta یا links می‌توانید از متد with در کلاس Resource استفاده کنید:

   php
   CopyEdit
   // app/Http/Resources/PostResource.php
   public function with($request)
   {
       return [
           'meta' => [
               'version' => '1.0',
               'author' => 'John Doe',
           ],
       ];
   }
   

   این داده‌ها به خروجی JSON اضافه خواهند شد.

2. استفاده از additional:

   اگر می‌خواهید داده‌های اضافی را به صورت دینامیک به نتیجه بازگشتی اضافه کنید، می‌توانید از متد additional استفاده کنید:

   php
   CopyEdit
   return (new PostResource($post))->additional([
       'message' => 'Post retrieved successfully',
       'status' => 'success',
   ]);
   

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

فصل 4: API Resource برای یک مدل و مجموعه

1. API Resource برای یک مدل واحد:

   همان‌طور که در قسمت‌های قبلی نشان دادیم، برای بازگرداندن یک مدل واحد می‌توانید به سادگی از PostResource استفاده کنید:

   php
   CopyEdit
   $post = Post::find($id);
   return new PostResource($post);
   

   این کد پست مشخصی را با استفاده از PostResource باز می‌گرداند.

2. API Resource برای مجموعه‌ای از مدل‌ها:

   برای بازگرداندن مجموعه‌ای از مدل‌ها (مثل یک لیست از پست‌ها) نیز می‌توانید از متد collection استفاده کنید که به‌طور خودکار تمام مدل‌ها را از طریق resource مناسب تبدیل می‌کند:

   php
   CopyEdit
   $posts = Post::all();
   return PostResource::collection($posts);
   

   این کد یک مجموعه از پست‌ها را باز می‌گرداند و هر پست با استفاده از PostResource به فرمت JSON تبدیل می‌شود.

فصل 5: استفاده از JsonResource برای مدل‌های پیچیده‌تر

گاهی ممکن است بخواهید یک ساختار پیچیده‌تری برای منابع خود ایجاد کنید. برای این کار می‌توانید از JsonResource استفاده کنید تا از ویژگی‌های اضافی مانند شمول روابط (Relationships) بهره‌مند شوید.

1. شمول روابط:

   اگر مدل شما دارای روابط است (مانند hasMany, belongsTo و غیره)، می‌توانید این روابط را نیز در API Resource خود بگنجانید.

   به‌عنوان مثال، اگر هر پست دارای یک نویسنده باشد (مدل User)، می‌توانید نویسنده هر پست را به صورت زیر اضافه کنید:

   php
   CopyEdit
   public function toArray($request)
   {
       return [
           'id' => $this->id,
           'title' => $this->title,
           'content' => $this->content,
           'author' => new UserResource($this->whenLoaded('user')),  // شامل رابطه user
       ];
   }
   

   در اینجا، whenLoaded('user') تنها زمانی داده‌های نویسنده را بارگذاری می‌کند که رابطه user به طور فعال بارگذاری شده باشد.

نتیجه‌گیری

API Resources در لاراول ابزاری قدرتمند برای تبدیل داده‌ها به فرمت JSON است که به شما امکان می‌دهد کنترل دقیقی بر نحوه ارسال داده‌ها به کلاینت‌ها داشته باشید. با استفاده از JsonResource و ویژگی‌هایی مانند with، additional و whenLoaded، می‌توانید داده‌های API خود را به‌طور مؤثر و سازمان‌یافته مدیریت کنید. این ابزار نه تنها به کاهش اطلاعات اضافی کمک می‌کند، بلکه ساختار قابل انعطاف و تمیزی برای توسعه API‌های RESTful در لاراول فراهم می‌آورد.