Laravel Sanctum في PHP: دليل شامل لـ API Tokens ومصادقة SPA

1. ما هو ولماذا تحتاجه

Laravel Sanctum هي مكتبة مصادقة خفيفة الوزن لإطار العمل PHP Laravel، مصممة لإدارة توكنات API وتطبيقات الصفحة الواحدة (SPA). طورها Taylor Otwell وفريق Laravel، توفر Sanctum طريقة بسيطة لكنها قوية لحماية مسارات API، مما يسمح للمطورين بتنفيذ المصادقة بسرعة دون التعقيدات الموجودة في الحلول الأثقل مثل Passport (OAuth2).

المهمة الأساسية لـ Sanctum هي حل مشكلتين رئيسيتين في تطوير الويب الحديث: مصادقة تطبيقات SPA التي تعمل على نفس نطاق الخادم الخلفي، وإصدار توكنات API للتطبيقات المحمولة أو الخدمات الخارجية. على عكس Passport، لا تستخدم Sanctum بروتوكول OAuth2 الكامل، مما يجعلها الخيار الأمثل للمشاريع التي لا تحتاج إلى نظام تفويض معقد. تستخدم جلسات Laravel لمصادقة SPA وتوكنات بسيطة تعتمد على HMAC لـ API.

المكتبة مضمنة بشكل افتراضي في Laravel 8 والإصدارات الأحدث، مما يجعلها متاحة "جاهزة للاستخدام". Sanctum مفيدة بشكل خاص للشركات الناشئة والفرق الصغيرة والمشاريع التي تهمها سرعة التطوير وتقليل التبعيات. تدير تلقائياً صلاحية التوكنات، وتدعم "الصلاحيات" (abilities) للتحكم الدقيق في الوصول، وتتكامل بسهولة مع Laravel Fortify أو Breeze أو Jetstream.

2. التثبيت

يتم تثبيت Laravel Sanctum عبر Composer، مدير الحزم القياسي لـ PHP. تأكد من أن لديك PHP 8.0 أو أعلى و Laravel 8.x/9.x/10.x/11.x.

الأمر الدقيق للتثبيت:

composer require laravel/sanctum

بعد التثبيت، يجب نشر ملف الإعدادات وملفات الترحيل (migrations) لقاعدة البيانات:

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

ثم قم بتشغيل الترحيلات لإنشاء جدول personal_access_tokens:

php artisan migrate

لمصادقة SPA، تحتاج أيضاً إلى إضافة middleware EnsureFrontendRequestsAreStateful إلى نواة HTTP (ملف app/Http/Kernel.php):

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

أيضاً، في ملف .env، حدد نطاق تطبيق SPA الخاص بك:

SANCTUM_STATEFUL_DOMAINS=localhost:8080

3. بداية سريعة — مثال عملي بسيط

لنلقِ نظرة على مثال بسيط لإصدار توكن API وحماية مسار.

الخطوة 1: نموذج User

في النموذج App\Models\User، استخدم trait HasApiTokens:

validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

    if (auth()->attempt($credentials)) {
        $user = auth()->user();
        $token = $user->createToken('api-token')->plainTextToken;
        
        return response()->json([
            'token' => $token,
            'user' => $user
        ]);
    }