پرش به مطلب اصلی

ماکرو های Response

این صفحه رفتار و ساختار ماکروهای پاسخ‌دهی (Response Macros) در Dorapi و نحوه استفاده آن‌ها را توضیح می‌دهد. این متدها یک الگوی ثابت، قابل پیش‌بینی و شفاف برای بازگرداندن پاسخ‌های API ایجاد می‌کنند تا Consumer ها بدون سردرگمی بتوانند پاسخ‌ها را پردازش کنند.

اهداف Response Macros​

  • ایجاد ساختار یکپارچه برای پاسخ‌های موفق و خطا
  • ساده‌سازی پاسخ‌های CRUD
  • پشتیبانی داخلی از Pagination به سبک Dorapi
  • جداسازی شفاف code, message, data, errors
نکته

این ماکروها روی Illuminate\Support\Facades\Response ثبت می‌شوند.

success ساختار پاسخ موفق​

امضای متد​

use Symfony\Component\HttpFoundation\Response as HttpFoundation;

Response::success(
    object $code = SystemMessage::SUCCESS,
    ?string $message = null,
    mixed $data = null,
    int $httpStatus = HttpFoundation::HTTP_OK,
    bool $flattenData = false,
    bool $hasPagination = false
);

توضیحات پارامترها​

پارامترتوضیح
codeمقدار enum از SystemMessage برای اعلام وضعیت منطقی عملیات
messageپیام خوانا برای کاربر
dataداده اصلی پاسخ
httpStatusوضعیت HTTP مانند 200 یا 201 یا 202
flattenDataاگر true باشد، داده‌ها در لایه اصلی پاسخ ادغام می‌شوند
hasPaginationدر صورت فعال بودن، ساختار خروجی با PaginationResource مربوط به Dorapi ایجاد می‌شود

نمونه خروجی معمولی​

{
  "code": "SUCCESS",
  "message": "Done.",
  "data": {
    "id": 1,
    "name": "Example"
  }
}

نمونه خروجی در حالت flatten​

{
  "code": "SUCCESS",
  "message": "Done.",
  "id": 1,
  "name": "Example"
}

صفحه‌بندی (Pagination) در Dorapi​

زمانی که مقدار hasPagination برابر با true باشد:

  1. داده‌ی ورودی به طور خودکار توسط PaginationResource مدیریت می‌شود.
  2. ساختار خروجی به صورت خودکار با فعال بودن flattenData برمی‌گردد (نیازی به مقداردهی دستی نیست).

نمونه استفاده​

return Response::success(
    data: $items,
    hasPagination: true
);

پاسخ‌های CRUD​

متد store​

برای ایجاد رکورد جدید.

Response::store(?string $message = null, ?array $data = null);
  • httpStatus = 201 Created
  • پیام پیش‌فرض: It was created successfully

متد update​

برای بروزرسانی رکورد.

Response::update(?string $message = null, ?array $data = null);
  • httpStatus = 202 Accepted
  • پیام پیش‌فرض: Successfully updated

متد destroy​

برای حذف رکورد.

Response::destroy(?string $message = null);
  • httpStatus = 202 Accepted
  • پیام پیش‌فرض: Removed successfully

پاسخ خطا (error)​

امضای متد​

Response::error(
    object $code,
    ?string $message = null,
    ?array $errors = null,
    int $httpStatus = 400
);

ساختار خروجی​

{
  "code": "SOME_ERROR",
  "message": "Something went wrong.",
  "errors": {
    "field": ["message"]
  }
}

خطای Data Not Found​

برای حالتی که داده موردنظر وجود ندارد.

Response::dataNotFound(array $errors = []);
  • code = SystemMessage::DATA_NOT_FOUND
  • message = Not found
  • httpStatus = 404 Not Found