تطوير واجهات REST API

التحقق من صحة الطلبات لواجهات برمجة التطبيقات

22 دقيقة الدرس 8 من 35

فهم التحقق من صحة طلبات API

يعد التحقق من صحة الطلبات أمراً بالغ الأهمية لأمان واجهة برمجة التطبيقات وسلامة البيانات. توفر Laravel أدوات تحقق قوية تجعل من السهل التحقق من صحة البيانات الواردة وإرجاع استجابات خطأ متسقة بتنسيق JSON.

لماذا نتحقق من صحة طلبات API؟

يحمي التحقق تطبيقك من خلال:

منع البيانات غير الصالحة من الدخول إلى قاعدة البيانات الخاصة بك
الحماية من المدخلات الضارة وهجمات الحقن
ضمان اتساق نوع البيانات وتنسيقها
توفير رسائل خطأ واضحة لمستهلكي واجهة برمجة التطبيقات
تقليل الأخطاء والسلوك غير المتوقع

ملاحظة: لا تثق أبداً في إدخال العميل. تحقق دائماً من البيانات وقم بتنظيفها على جانب الخادم، حتى لو كان لديك تحقق من جانب العميل.

التحقق الأساسي من المتحكم

أبسط طريقة للتحقق هي مباشرة في متحكمك:

use Illuminate\Http\Request;

public function store(Request $request)
{
    $validated = $request->validate([
        'title' => 'required|string|max:255',
        'content' => 'required|string',
        'email' => 'required|email|unique:users,email',
        'age' => 'required|integer|min:18|max:120',
        'website' => 'nullable|url',
    ]);

    // إذا فشل التحقق، يعيد Laravel تلقائياً استجابة JSON 422
    // إذا نجح، يحتوي $validated فقط على الحقول التي تم التحقق منها

    $post = Post::create($validated);

    return response()->json([
        'success' => true,
        'message' => 'تم إنشاء المنشور بنجاح',
        'data' => $post
    ], 201);
}

استجابات أخطاء JSON التلقائية

عندما يفشل التحقق في سياق API، يعيد Laravel تلقائياً استجابة JSON:

{
    "message": "البيانات المقدمة غير صالحة.",
    "errors": {
        "title": [
            "حقل العنوان مطلوب."
        ],
        "email": [
            "يجب أن يكون حقل البريد الإلكتروني عنوان بريد إلكتروني صالحاً.",
            "البريد الإلكتروني مستخدم بالفعل."
        ]
    }
}

نصيحة: يكتشف Laravel طلبات API (المسارات التي تبدأ بـ /api أو الطلبات مع رأس Accept: application/json) ويعيد تلقائياً أخطاء التحقق بتنسيق JSON.

قواعد التحقق الشائعة

يوفر Laravel العشرات من قواعد التحقق المدمجة:

القاعدة	الوصف	مثال
`required`	يجب أن يكون الحقل موجوداً	`'name' => 'required'`
`nullable`	يمكن أن يكون الحقل فارغاً	`'bio' => 'nullable\|string'`
`email`	تنسيق بريد إلكتروني صالح	`'email' => 'required\|email'`
`unique`	يجب أن تكون القيمة فريدة في الجدول	`'email' => 'unique:users'`
`exists`	يجب أن توجد القيمة في الجدول	`'user_id' => 'exists:users,id'`
`min/max`	الحد الأدنى/الأقصى للطول أو القيمة	`'age' => 'min:18\|max:120'`
`in`	يجب أن تكون القيمة في القائمة	`'role' => 'in:admin,user'`
`regex`	مطابقة نمط regex	`'phone' => 'regex:/^[0-9]{10}$/'`

إنشاء فئات طلب النموذج

لمنطق التحقق المعقد، أنشئ فئات طلب نموذج مخصصة:

php artisan make:request StorePostRequest

ينشئ هذا فئة في app/Http/Requests/StorePostRequest.php:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StorePostRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true; // أو تنفيذ منطق التفويض
    }

    public function rules(): array
    {
        return [
            'title' => 'required|string|max:255',
            'content' => 'required|string|min:100',
            'category_id' => 'required|exists:categories,id',
            'tags' => 'nullable|array',
            'tags.*' => 'exists:tags,id',
            'published_at' => 'nullable|date|after:now',
        ];
    }
}

استخدام طلبات النموذج في المتحكمات

حدد نوع طلب النموذج في طريقة متحكمك:

use App\Http\Requests\StorePostRequest;

public function store(StorePostRequest $request)
{
    // التحقق نجح بالفعل إذا وصلنا إلى هنا
    $validated = $request->validated();

    $post = Post::create($validated);

    return response()->json([
        'success' => true,
        'data' => $post
    ], 201);
}

ملاحظة: يتم التحقق من طلبات النموذج قبل تنفيذ طريقة المتحكم. إذا فشل التحقق، يتم إرجاع الاستجابة تلقائياً.

رسائل خطأ مخصصة

قم بتخصيص رسائل خطأ التحقق في طلب النموذج الخاص بك:

public function messages(): array
{
    return [
        'title.required' => 'يرجى تقديم عنوان المنشور',
        'title.max' => 'لا يمكن أن يتجاوز عنوان المنشور 255 حرفاً',
        'content.required' => 'محتوى المنشور مطلوب',
        'content.min' => 'يجب أن يكون محتوى المنشور 100 حرف على الأقل',
        'category_id.required' => 'يرجى اختيار فئة',
        'category_id.exists' => 'الفئة المحددة غير موجودة',
    ];
}

أسماء سمات مخصصة

اجعل رسائل الخطأ أكثر سهولة من خلال تخصيص أسماء السمات:

public function attributes(): array
{
    return [
        'category_id' => 'الفئة',
        'published_at' => 'تاريخ النشر',
    ];
}

التحقق الشرطي

تطبيق القواعد بشكل شرطي بناءً على حقول أخرى:

public function rules(): array
{
    return [
        'title' => 'required|string|max:255',
        'is_published' => 'required|boolean',

        // اطلب published_at فقط إذا كان is_published صحيحاً
        'published_at' => 'required_if:is_published,true|date',

        // الفئة مطلوبة ما لم يكن النوع 'مسودة'
        'category_id' => 'required_unless:type,draft|exists:categories,id',
    ];
}

التحقق من المصفوفة والتداخل

تحقق من المصفوفات وهياكل البيانات المتداخلة:

public function rules(): array
{
    return [
        // التحقق من عناصر المصفوفة
        'tags' => 'required|array|min:1|max:10',
        'tags.*' => 'string|max:50',

        // التحقق من الكائنات المتداخلة
        'author' => 'required|array',
        'author.name' => 'required|string|max:255',
        'author.email' => 'required|email',

        // التحقق من مصفوفة الكائنات
        'comments' => 'nullable|array',
        'comments.*.user_id' => 'required|exists:users,id',
        'comments.*.content' => 'required|string|max:1000',
    ];
}

تحذير: كن حذراً مع التحقق المتداخل بعمق. حدد حدوداً معقولة لمنع مشاكل الأداء وهجمات DoS المحتملة.

قواعد التحقق المخصصة

أنشئ قواعد تحقق مخصصة للمنطق المعقد:

php artisan make:rule Uppercase

<?php

namespace App\Rules;

use Closure;
use Illuminate\Contracts\Validation\ValidationRule;

class Uppercase implements ValidationRule
{
    public function validate(string $attribute, mixed $value, Closure $fail): void
    {
        if (strtoupper($value) !== $value) {
            $fail('يجب أن يكون :attribute بأحرف كبيرة.');
        }
    }
}

استخدم القاعدة المخصصة في التحقق:

use App\Rules\Uppercase;

public function rules(): array
{
    return [
        'code' => ['required', 'string', new Uppercase],
    ];
}

تمرين:

أنشئ طلب نموذج لتسجيل مستخدمين جدد مع التحقق من الاسم والبريد الإلكتروني وكلمة المرور والعمر
أضف رسائل خطأ مخصصة لجميع قواعد التحقق
أنشئ قاعدة تحقق مخصصة تتحقق مما إذا كان اسم المستخدم يحتوي على ألفاظ بذيئة
نفذ التحقق الشرطي حيث يكون رقم الهاتف مطلوباً إذا لم يتم توفير البريد الإلكتروني
أضف خطاف تحقق after يتحقق مما إذا كان رمز القسيمة صالحاً

أفضل الممارسات

استخدم طلبات النموذج: حافظ على المتحكمات نحيفة من خلال نقل التحقق إلى فئات طلب النموذج
فشل مبكراً: تحقق من المدخلات قبل إجراء عمليات مكلفة
كن محدداً: استخدم قواعد تحقق دقيقة بدلاً من الاعتماد على القواعد العامة
نظف المدخلات: نظف البيانات وقم بتنسيقها في prepareForValidation()
حدد المصفوفات: حدد حدود max على مدخلات المصفوفة لمنع إساءة الاستخدام
رسائل واضحة: قدم رسائل خطأ سهلة الاستخدام وقابلة للتنفيذ

الخلاصة

التحقق من صحة الطلبات ضروري لبناء واجهات برمجة تطبيقات آمنة وموثوقة. يوفر نظام التحقق في Laravel أدوات قوية لضمان سلامة البيانات مع الحفاظ على كود نظيف وقابل للصيانة. في الدرس التالي، سنستكشف مصادقة API باستخدام Laravel Sanctum.