ویژگی API Resource در لاراول نسخه ۵٫۵

  • 170 بازدید
  • ویژگی API Resource در لاراول نسخه ۵٫۵

    در نسخه ۵٫۵ فریم ورک لاراول امکانی تحت عنوان API Resource افزوده شده است که برای تبدیل ساختار مدل ها به json سودمند می باشد. در ادامه این ویژگی را بررسی خواهیم کرد.

    مقدمه:

    استفاده از این ویژگی در زمان ایجاد API ، برای مدیریت بهتر JSON Response ها می‌تواند بسیار مفید واقع شود.

    این ویژگی در حقیقت لایه‌ای است که بین مدل و JSON response قرار می‌گیرد  و به شما اجازه می‌دهد تا به راحتی مدل‌ها و model collection ها را به  JSON تبدیل کنید.

    پیاده سازی:

    برای استفاده از این  ویژگی ابتدا در ترمینال دستور

    Php artisan make:resource User

    را برای model  و برای model collection  دستور

    Php artisan make:resource User --collection

    یا

    Php artisan make:resource UserCollection

     را وارد می‌کنیم.

    پس از اجرای این دستور در مسیر app/http  یک پوشه‌ی جدید به نام Resources ایجاد می‌شود و درون این پوشه کلاس به نام User  یا UserCollection  ایجاد می‌شود.

    استفاده:

    حال می‎‌توان به جای دستور

    return response()->json(['data'=>$user])

    از

    Return new UserResource($user)

    استفاده کرد.

    سفارشی سازی:

    فکر کنم متوجه شدید که خروجی بصورت ساختار {data:value} ساخته میشود.برای تغییر نام  فیلد 'data' می توان از روش‌های زیر استفاده کرد:

    ۱- استفاده از تابع wrap قبل از return  کردن مقدار resource :

    \illuminate\Http\Resources\Json\Resource::wrap('item');

    ۲- در مسیر app\Http\Resources  و در User.php  از متغیر از پیش تعریف شده‌ی $wrap استفاده کنیم.

    Public static $wrap='item';

    برای محدود کردن مقادیر بازگشتی در Json response ، به عنوان مثال فقط نام و ایمیل کاربر، در app/Http/Resources/User.php در متد toArray :

    Return [

    'name'=>$this->name,

    'email'=>$this->email

    ];

    می‌توانیم در متد toArray  یک سری شرایط را چک کنیم و در صورت درست بودن شرایط یک فیلد را به Json Response  اضافه کنیم. برای این کار از متد when  به صورت زیر استفاده می‌کنیم:

    Return [

    'name'=>$this->name,

    'email'=>$this->email,

    'admin'=>$this->when($this->isAdmin(),'admin')

    ];

    اگر پارامتر اول تابع when، true برگرداند، یک فیلد "admin":"admin" به اطلاعات کاربر در Json Response  اضافه می‌شود و اگر مقدار پارامتر اول false باشد فیلد "admin":"admin" به طور کامل نمایش داده نخواهد شد. می‌توانیم پارامتر دوم تابع when را function  هم قرار دهیم.

    برای اینکه در کنار اطلاعات کاربر(همان 'data' یا 'item') یک فیلد دیگر هم اضافه کنیم، می‌توانیم از متد with درون app/Http/Resources/User.php استفاده کنیم.

    Public function with($request)

    {

    Return ['status'=>'success']

    }

    این کد باعث می‌شود تا در کنار فیلد data یک فیلد status هم اضافه شود.

    برای برگرداندن لیستی از مدل (کاربران) می‌توانیم از روش‌های زیر استفاده کنیم:

    ۱- استفاده از متد استاتیک collection  برای UserResource (که برای برگداندن فقط یک instance از مدل استفاده می‌شد)

    $users=/app/User::all();

    Return UserResource::collection($users);

    عیب استفاده از این روش این است که متد  with() از کار می‌افتد.

    ۲-ایجاد و استفاده از Resource collection

    برای ایجاد Resource collection

    Php artisan make:resource User --collection

    یا

    Php artisan make:resource UserCollection

    برای استفاده:

    $users=/app/User::all();

    Return  new UserCollection($users);

    نکته قابل توجه در این مورد این است که اگر در مسیر app/Http/Resources هم User.php و هم UserCollection.php  داشته باشیم و در User.php با استفاده از متد toArray فیلدها را customize  کرده باشیم تغییرات ایجاد شده روی UserCollection هم اعمال خواهند شد ولی بای متد with() را برای UserCollection  هم بازنویسی کنیم.

    یکی از ویژگی‌هایی که استفاده از Resource collection  را ضروری می‌کند، paginate راحت آن است.

    برای اضافه کردن paginate به UserCollection :

    $users=/app/User::paginate(5);

    Return new UserCollection($users);

     با استفاده از این روش فیلدهای links  و meta که حاوی اطلاعات مربوط به  pagination می‌باشند، در کنار فیلد data اضافه می‌شوند.

    می‌توان به همراه response یک سری اطلاعات هم ارسال کرد (مثلا اطلاعات مربوط به header) برای این کار روش های زیر را می‌توان اجرا کرد:

    ۱-

    Return (new UserCollection)->response()->header('X-Value','true');

              ۲- استفاده از متد withResponse()  درUser و UserCollection

    Public function withResponse($request,$response)

    {

    $response->header('X-Value','true');

    }

     

    از Api Resource می‌توانیم هم برای درخواست‌های api و هم درخواست‌های ajax استفاده کنیم.

    1. علیرضا

      سلام آقای منصور بهزادی عزیز
      یه سوال خیلی حیاتی از شما داشتم و ممنون میشم اگه براتون مقدور بود و زیاد وقتتون رو نمیگیره بهش پاسخ بدین.
      api resource در واقع باعث میشه که ما بتونیم یه ساختار پیچیده از دیتا رو به فرمت jason برگردونیم.(یا بفرستیم)
      ما همین کار رو مگه نمیتونیم تو خوده controller و با ایجاد یک آرایه دلخواه انجام بدیم؟
      اصلا مزیت استفاه از api resource در چیه؟
      راستش سوال نهایی م اینه که اگه من بجای اینکه آرایه دلخواهم رو در Controller بسازم و بیام از resource استفاده کنم، ایا performance وب سرویس من پایین نمیاد؟ (چون من دارم یه آبجکت برای این کار میسازم، در حالی که میتونم داخل controller این کار رو انجام بدم)

      بی نهایت از شما ممنونم

      1. علی حقیقت جو

        پاسخ مهندس بهزادی عزیز:

        سلام
        بله میتونیم خودمون این کار رو انجام بدیم. بصورت دستی عناصر مدل رو بصورت دلخواه به یک ارائه تبدیل کنیم و برگردانیم. حتی میشه مستقیم خود مدل رو در تابع جی سون قرار داد و همه فیلد هارو برگرداند.
        دلیل استفاده از ای پی آی ریسورس این هست که حجم کد های کنترلر کم بشه و کد نویسی ما مرتب بشه.
        شاید در نگاه اول کم اهمیت باشه اما توی پروژه های بزرگ تر مفید هست و باعث تسهیل ویرایش و نگهداری پروژه میشه

    ارسال دیدگاه

    نشانی ایمیل شما منتشر نخواهد شد.

    This site uses Akismet to reduce spam. Learn how your comment data is processed.

    سئوال دارید؟ کارشناسان ما همواره پاسخگوی شما هستند.

       ارتباط از طریق نرم افزار پیام رسان واتس آپ