نسخهٔ ۳ پکیج Laravel Rest Api منتشر شد
خلاصهٔ کاملتر
Gautier Deleglise نسخهٔ 3.0 پکیج Laravel Rest Api رو منتشر کرده. این پکیج از یه کلاس resource (یعنی یه کلاس که میگه مدل چه فیلدها و دسترسیهایی داره) یه REST API کامل برای مدلهای Eloquent میسازه. به گفتهٔ Laravel News، ایده همون قبلیه ولی بیشتر چیزهایی که زیرش کار میکنه عوض شده.
بزرگترین تغییر فیلدهای تایپداره. تو نسخهٔ 2 فقط اسم ستونها رو لیست میکردی، ولی حالا هر فیلد با کلاسهایی مثل Text، Integer، Date و Enum تعریف میشه:
return [
ID::make('id'),
Text::make('title')->rules('max:80')->creationRules('required'),
Integer::make('seats')->rules('min:0'),
Enum::make('status', ShowStatus::class)->offered([ShowStatus::Planned, ShowStatus::OnSale]),
];همین یه تعریف کل API رو جلو میبره. فیلترها فقط عملگرهایی رو قبول میکنن که به نوع فیلد میخوره و بقیه خطای 422 میدن. خطای ولیدیشن دقیقاً کلید مشکلدار رو نشون میده، مثلاً mutate.0.attributes.seats. عددها تو خروجی عدد برمیگردن و Enum::offered() تعیین میکنه کلاینت کدوم مقدارها رو میتونه بنویسه؛ یعنی یه وضعیت قدیمی رو هنوز میشه خوند و فیلتر کرد، ولی دیگه کسی نمیتونه ستش کنه.
مولد مستندات داخلی حذف شده و جاش پکیج با Scramble یکپارچه شده. با نصب Scramble، آدرس /docs/api همهٔ endpointها رو با بدنهٔ تایپدار، قوانین هر فیلد، نمونه درخواست و خطاها مستند میکنه. تستهای خود پکیج هم همین نمونهها رو به API میفرستن و جواب رو با سند مقایسه میکنن؛ یعنی اگه مستندات و API با هم نخونن، تست میشکنه.
متریکها هم جدیدن: یه متریک روی resource تعریف میکنی و بدون کنترلر، route خودش رو میگیره. نوعهای Value، Trend، Partition، Progress و Table شمارش، جمع، میانگین، میانه و صدک رو پوشش میدن، با بازهٔ تاریخ، منطقهٔ زمانی، مقایسه با دورهٔ قبل و کش. هر متریک فقط ردیفهایی رو میشمره که کاربر فعلی اجازهٔ دیدنشون رو داره.
قابلیت تأیید هم اضافه شده: actionها، mutate، destroy، restore و force destroy میتونن قبل از اجرا تأیید بخوان. endpoint یه پاسخ 428 با پیام و یه توکن امضاشده برمیگردونه و اگه کلاینت همون درخواست رو با توکن دوباره بفرسته، اجرا میشه؛ بدون session و بدون endpoint اضافه.
از بقیهٔ تغییرات: policyها روی همهٔ ردیفها قبل از اولین نوشتن چک میشن، perimeterQuery() داده رو به tenant یا تیم محدود میکنه، resourceهای versioned() اگه ردیف بعد از خوندن عوض شده باشه 409 میدن، و دستورهای rest:quick-start و rest:check برای ساخت سریع و چک تو CI اومدن. این نسخه به PHP 8.3+ و Laravel 13.30+ نیاز داره و پروژههای Laravel 12 باید روی 2.x بمونن.
نکات کلیدی:
- Laravel Rest Api 3.0 به PHP 8.3+ و Laravel 13.30+ نیاز داره و breaking change داره
- فیلدهای تایپدار مثل Text، Integer و Enum فیلتر، ولیدیشن و خروجی رو تعیین میکنن
- مستندات OpenAPI از طریق Scramble روی /docs/api ساخته میشه
- پنج نوع متریک Value، Trend، Partition، Progress و Table بدون کنترلر route میگیرن
- عملیات حساس با پاسخ 428 و توکن امضاشده تأیید میخوان
- پیامها به انگلیسی و فرانسوی هستن و از locale درخواست پیروی میکنن




