كيف تصمم معالج أخطاء مركزي وموحد لاستجابات الـ API في Laravel؟

الإجابة المختصرة

بتخصيص معالجة الاستثناءات في bootstrap/app.php أو Handler عبر دالة renderable لتحويل أخطاء مثل ModelNotFoundException إلى ردود JSON منسقة.

الشرح

افتراضياً، قد يرجع Laravel صفحات HTML أو تفاصيل كود حساسة عند وقوع أخطاء. يجب ضبط معالج الاستثناءات ليتعرف تلقائياً على طلبات الـ API عبر $request->expectsJson() ويرجع بنية موحدة ثابتة تحتوي على error code و message واضحة، مع إخفاء الـ Stack Trace في بيئات الإنتاج.

مثال بالكود

// bootstrap/app.php (Laravel 11)
->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (NotFoundHttpException $e, Request $request) {
        if ($request->is('api/*')) {
            return response()->json(['message' => 'Resource not found'], 404);
        }
    });
})

أخطاء شائعة

• تسريب تفاصيل الـ SQL Exceptions وأسماء الجداول والحقول للمستخدم في بيئة الإنتاج.

أسئلة متابعة

• ما هي API Resources في Laravel ولماذا تعد أفضل من إرجاع نماذج Eloquent كـ JSON مباشرة؟
• كيف تعزل منطق التحقق والصلاحيات في فئات Form Requests بـ Laravel؟

المصادر

• Laravel docs — Error Handling