کنترلر نسخه ۳ (V3)

کنترلرهای نسخه ۳ در این پروژه برای ارائه یک API استاندارد و RESTful طراحی شده‌اند. این کنترلرها از یک ساختار مبتنی بر ارث‌بری استفاده می‌کنند که بسیاری از عملکردهای رایج را در کلاس‌های پایه کپسوله می‌کند و به شما اجازه می‌دهد تا فقط منطق خاص ماژول خود را پیاده‌سازی کنید.

۱. ساختار اصلی

یک کنترلر نسخه ۳ به طور خودکار با استفاده از دستور make:v3 {model} ساخته می‌شود و ساختار زیر را دارد:

• ارث‌بری: هر کنترلر از BaseClientAPIController یا BaseAdminAPIController ارث‌بری می‌کند. هر دوی این کلاس‌ها نیز از BaseAPIController ارث‌بری می‌کنند که منطق اصلی در آن قرار دارد.
• تزریق وابستگی (Dependency Injection): در __construct، ریپازیتوری و ترنسفورمر مربوط به مدل به صورت خودکار تزریق می‌شوند. این کار باعث جداسازی کامل لایه‌های داده، منطق و نمایش می‌شود.

<?php

namespace Modules\YourModule\Http\Controllers\API\V3\Admin;

use App\Http\Controllers\BaseAdminAPIController;
use Modules\YourModule\Repositories\YourModelRepository;
use Modules\YourModule\Http\Transformers\V3\Admin\YourModelTransformer;
use Modules\YourModule\Http\Requests\V3\Admin\YourModelStoreRequest;
use Modules\YourModule\Http\Requests\V3\Admin\YourModelUpdateRequest;
use Illuminate\Http\JsonResponse;

class YourModelController extends BaseAdminAPIController
{
    public function __construct()
    {
        // تزریق خودکار ریپازیتوری و ترنسفورمر
        parent::__construct(
            resolve(YourModelRepository::class),
            resolve(YourModelTransformer::class)
        );
    }

    // ... متدهای پیاده‌سازی شده ...
}

۲. متدهای پیاده‌سازی شده در کنترلر شما

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

• store(YourModelStoreRequest $request): JsonResponse

  • وظیفه: ایجاد یک رکورد جدید.
  • فرآیند: داده‌های اعتبارسنجی شده از YourModelStoreRequest را دریافت کرده، از طریق ریپازیتوری یک مدل جدید ایجاد می‌کند و نتیجه را با استفاده از ترنسفورمر به صورت JSON باز می‌گرداند.

• update(int $id, YourModelUpdateRequest $request): JsonResponse

  • وظیفه: بروزرسانی یک رکورد موجود.
  • فرآیند: داده‌های اعتبارسنجی شده از YourModelUpdateRequest را دریافت کرده، رکورد با id مشخص شده را آپدیت می‌کند و نتیجه را باز می‌گرداند.

• delete(int $id): JsonResponse

  • وظیفه: حذف یک رکورد.
  • فرآیند: رکورد با id مشخص شده را از طریق ریپازیتوری حذف کرده و یک پاسخ موفقیت‌آمیز باز می‌گرداند.

۳. متدهای ارث‌بری شده از BaseAPIController

این متدها در تمام کنترلرهای نسخه ۳ در دسترس هستند و نیازی به پیاده‌سازی مجدد آن‌ها نیست، مگر اینکه بخواهید رفتار پیش‌فرض را تغییر دهید.

• index(Request $request): JsonResponse

  • وظیفه: دریافت لیست رکوردها به صورت صفحه‌بندی شده (Pagination).
  • قابلیت‌ها: به طور خودکار از RequestCriteria برای فیلتر کردن، مرتب‌سازی و بارگذاری روابط (includes) بر اساس پارامترهای Query String پشتیبانی می‌کند.

• simpleIndex(Request $request): JsonResponse

  • وظیفه: مشابه index است اما از simplePaginate برای صفحه‌بندی ساده‌تر (فقط لینک‌های next/previous) استفاده می‌کند.

• show(int|string $identifier, Request $request, ?string $field = 'id'): JsonResponse

  • وظیفه: دریافت اطلاعات یک رکورد خاص.
  • قابلیت‌ها: می‌تواند رکورد را بر اساس id یا هر فیلد یکتای دیگری پیدا کند. همچنین از بارگذاری روابط (includes) پشتیبانی می‌کند.

• keyValList(string $field, Request $request, string $key = 'id'): JsonResponse

  • وظیفه: دریافت یک لیست از رکوردها به صورت زوج‌های کلید-مقدار (key-value). مناسب برای پر کردن لیست‌های dropdown در فرانت‌اند.
  • مثال: api/v3/admin/users/key-val-list/name لیستی از کاربران را به صورت [{ "id": 1, "name": "User A" }] باز می‌گرداند.

• signal(int|BaseModel $model, BaseSignalRequest $request): JsonResponse

  • وظیفه: برای عملیات‌های سیگنال‌مانند مانند toggle کردن یک وضعیت (مثلاً لایک/آنلایک).
  • فرآیند: یک type و value از BaseSignalRequest دریافت کرده و عملیات مربوطه را روی مدل انجام می‌دهد.

• countsBy(string $column, Request $request): JsonResponse

  • وظیفه: شمارش و گروه‌بندی رکوردها بر اساس یک ستون خاص.
  • مثال: api/v3/admin/posts/counts-by/status تعداد پست‌ها را به تفکیک وضعیت (مثلاً منتشر شده، پیش‌نویس) باز می‌گرداند.

۴. متدهای خاص BaseAdminAPIController

• prepareForm(): JsonResponse
  • وظیفه: یک ساختار خالی از مدل به همراه مقادیر پیش‌فرض را برای استفاده در فرم‌های "ایجاد" در پنل ادمین باز می‌گرداند.