في هذا الدرس 6تصفّح المواضيع
توفر مكتبة Laravel Sanctum نظام مصادقة خفيفاً لتطبيقات الصفحة الواحدة وتطبيقات الهواتف والواجهات البرمجية المعتمدة على الرموز دون تعقيدات OAuth. يقوم الأمر php artisan install:api بتثبيت Sanctum وإنشاء تهجير جدول personal_access_tokens وتجهيز نموذج المستخدم لإضافة السمة HasApiTokens.
- سمة HasApiTokens (HasApiTokens Trait): أضف Laravel\Sanctum\HasApiTokens إلى نموذج المستخدم لتفعيل دوال إنشاء وفحص الرموز.
- تخزين الرموز المشفرة (Hashed Token Storage): يخزن Sanctum الرموز بعد تجزئتها بخوارزمية SHA-256 داخل جدول personal_access_tokens.
- بساطة بدون تعقيد (Zero OAuth Overhead): حل مثالي لتطبيقات الهواتف وأدوات سطر الأوامر والتكامل البرمجي المباشر.
namespace App\Models;
use Illuminate\Foundation\Auth\User as AuthUser;
use Laravel\Sanctum\HasApiTokens;
class User extends AuthUser {
use HasApiTokens;
}بعد التحقق من صحة بيانات دخول المستخدم، استدع الدالة $user->createToken لتوليد كائن رمز وصول جديد. يجب إرجاع الخاصية النصية plainTextToken للعميل فوراً لأن القيمة الخام غير المشفرة لا تُحفظ أبداً في قاعدة البيانات.
- التحقق من بيانات الدخول (Credential Verification): تحقق من البريد وكلمة المرور عبر دالة Hash::check قبل إصدار رمز الواجهة البرمجية.
- النص الصريح لمرة واحدة (One-Time Plain Text): اقرأ الخاصية plainTextToken من الكائن الناتج لتسليم العميل نص الرمز الخاص به.
- صيغة رأس التفويض (Authorization Header Format): يرسل العميل الرمز في الطلبات اللاحقة داخل رأس الرسالة Authorization: Bearer.
$user = User::where('email', $req->email)->first();
if (! $user || ! Hash::check($req->pw, $user->pw)) {
return response()->json(['err' => 'Auth'], 401);
}
$tok = $user->createToken('app')->plainTextToken;
return response()->json(['token' => $tok], 201);لقصر الوصول إلى نقاط النهاية البرمجية على العملاء المصادق عليهم، أرفق البرمجية الوسيطة auth:sanctum بالمسارات الفردية أو مجموعات المسارات داخل routes/api.php. عند إرسال رمز Bearer صالح، تعيد دالة $request->user كائن المستخدم المصادق عليه تلقائياً.
- الحماية بالبرمجية الوسيطة (Middleware Protection): غلف نقاط النهاية الخاصة داخل مجموعة Route::middleware('auth:sanctum') في ملف routes/api.php.
- جلب المستخدم الحالي (Resolving Current User): استرجع مالك الرمز عبر دالة $request->user داخل أي متحكم أو مسار محمي.
- الرمز 401 لغير المصادق (HTTP 401 Unauthenticated): الطلبات التي تفتقر لرمز Bearer صالح مع رأس JSON تستقبل استجابة 401 فورية.
use App\Http\Controllers\Api\PostController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::middleware('auth:sanctum')->group(function () {
Route::get('/me', fn (Request $r) => $r->user());
Route::apiResource('posts', PostController::class);
});تتيح مكتبة Sanctum تخصيص صلاحيات دقيقة للرمز تُعرف بالقدرات عبر الوسيط الثاني في دالة createToken على غرار نطاقات OAuth. داخل المتحكمات، يمكنك استدعاء دالة tokenCan على كائن المستخدم للتحقق مما إذا كان الرمز الحالي يمتلك صلاحية تنفيذ العملية المطلوبة.
- تحديد قدرات الرمز (Defining Token Abilities): مرر مصفوفة قدرات نصية مثل ['posts:read', 'posts:write'] عند استدعاء دالة createToken.
- الفحص بدالة tokenCan (Checking with tokenCan): استدع دالة tokenCan على المستخدم للتحقق من صلاحية الرمز الحالي داخل إجراءات المتحكم.
- وسيط القدرات (Abilities Middleware): سجل الاسمين المستعارين abilities و ability في ملف bootstrap/app.php لحماية المسارات تصريحياً.
// Issue scoped token:
$token = $user->createToken('cli', ['posts:write']);
// Verify ability inside controller:
if (! $request->user()->tokenCan('posts:write')) {
abort(403, 'Token lacks write ability.');
}نظراً لأن Sanctum يخزن رموز الوصول في قاعدة البيانات، يمكنك إبطالها فوراً عند تسجيل خروج المستخدم أو فقدان جهازه. يحذف استدعاء currentAccessToken->delete الرمز المستخدم في الطلب الحالي فقط، بينما تلغي دالة tokens->delete جميع الرموز النشطة للمستخدم على كافة الأجهزة.
- تسجيل الخروج من الجهاز الحالي (Single-Device Logout): احذف الرمز الحالي عبر currentAccessToken لكي تبقى الأجهزة الأخرى متصلة.
- إبطال جميع الرموز (Global Token Revocation): استدع tokens->delete بعد تغيير كلمة المرور لتسجيل الخروج من كافة الأجهزة.
- انتهاء الصلاحية التلقائي (Automatic Expiration): اضبط عدد دقائق الصلاحية في ملف config/sanctum.php لإبطال الرموز القديمة آلياً.
public function logout(Request $request)
{
$request->user()->currentAccessToken()->delete();
return response()->json([
'message' => 'Token revoked successfully.',
]);
}يتطلب تأمين واجهات RESTful البرمجية في بيئة الإنتاج الجمع بين مصادقة رموز Sanctum وتقييد قدرات الرموز وتطبيق محددات المعدل على مسارات الدخول. راجع ملخص دوال دورة حياة الرموز أدناه لترسيخ معمارية مصادقة الواجهات البرمجية.
| وجه المقارنة الهندسي | الأسلوب المتزامن أو التقليدي | معيار Laravel 12 الحديث |
|---|---|---|
| تخزين رموز الوصول | تخزين مفتاح API كنص صريح مباشرة داخل جدول المستخدمين | تخزين الرموز مجزأة بـ SHA-256 في جدول personal_access_tokens |
| دعم تعدد الأجهزة | عمود رمز واحد يتم استبداله عند الدخول من جهاز جديد | رموز متعددة ومسماة لكل مستخدم عبر علاقة HasApiTokens |
| تحديد نطاق الصلاحيات | منح صلاحيات كاملة ومطلقة لأي مفتاح واجهة برمجية | تخصيص قدرات دقيقة للرمز وفحصها عبر دالة tokenCan |
| إبطال الجلسة والرموز | استحالة إبطال رمز جهاز واحد دون تعطيل بقية الأجهزة | إلغاء فوري لرمز الجهاز الحالي عبر currentAccessToken->delete |
// Prune expired tokens via Artisan:
// php artisan sanctum:prune-expired --hours=24
$request->user()->tokens()
->where('id', $tokenId)->delete();ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
أتقنت في هذا الدرس حول «مصادقة الرموز وحماية واجهات API عبر Laravel Sanctum» مفاهيم إعداد مكتبة Sanctum وسمة الرموز، وإصدار رموز الدخول عبر createToken، وحماية مسارات API بحارس Sanctum وفق معايير Laravel 12 الحديثة.
الخطوة التالية والدرس القادم
انتقل الآن إلى الدرس التالي «إرسال البريد الإلكتروني عبر Mailable ونظام الإشعارات في Laravel» للبناء التراكمي على ما تعلمته.
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 Laravel Sanctum مصادقة Sanctum
- إصدار رموز الوصول Bearer Tokens عبر مكتبة Laravel Sanctum وحماية مسارات API بالبرمجية الوسيطة auth:sanctum وإدارة صلاحيات الرموز.
- للمراجعة
- 02 Configuring Laravel Sanctum Tokens إعداد مكتبة Sanctum وسمة الرموز
- المفهوم الهندسي والتطبيق العملي المباشر لقسم إعداد مكتبة Sanctum وسمة الرموز في إطار العمل Laravel 12.
- للمراجعة
- 03 Issuing API Bearer Tokens إصدار رموز الدخول عبر createToken
- المفهوم الهندسي والتطبيق العملي المباشر لقسم إصدار رموز الدخول عبر createToken في إطار العمل Laravel 12.
- للمراجعة
- 04 Protecting Routes with Sanctum Guard حماية مسارات API بحارس Sanctum
- المفهوم الهندسي والتطبيق العملي المباشر لقسم حماية مسارات API بحارس Sanctum في إطار العمل Laravel 12.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
الاختصارات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 MVC MVC
- Model View Controller
- النمط المعماري الذي يفصل بين نماذج البيانات Models، وطبقات العرض Views، والمتحكمات Controllers في Laravel.
- للمراجعة
- 02 CLI CLI
- Command Line Interface
- واجهة سطر الأوامر التي تعمل عبر أداة php artisan لتوليد الملفات وإدارة التطبيق.
- للمراجعة
- 03 HTTP HTTP
- Hypertext Transfer Protocol
- بروتوكول نقل النص الفائق الذي ينظم طلبات المتصفح واستجابات خادم Laravel.
- للمراجعة
- 04 PSR PSR
- PHP Standards Recommendations
- المعايير القياسية للغة PHP مثل التحميل التلقائي PSR-4 التي يلتزم بها إطار العمل Laravel.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
مهامك قبل الاختبار
خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.
-
اكتب ونفّذ المثال البرمجي المشروح في قسم «إعداد مكتبة Sanctum وسمة الرموز» داخل مشروع Laravel 12 المحلي وتحقق من النتيجة.
-
بدّل بين الحالات الثلاث في المحاكي التفاعلي ضمن قسم «إصدار رموز الدخول عبر createToken» وقارن مخرجات التنفيذ.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.
لمحة عن التحدي8 أسئلة تنتظرك ＋
ما الهدف الهندسي الأساسي من إعداد مكتبة Sanctum وسمة الرموز في إطار العمل Laravel 12؟
يسهم إعداد مكتبة Sanctum وسمة الرموز في تنظيم منطق التطبيق بأسلوب معياري آمن وقابل للصيانة في Laravel 12.
يساعد الالتزام باصطلاحات Laravel 12 الرسمية في قسم «إصدار رموز الدخول عبر createToken» على رفع جودة الكود وسهولة اختباره آلياً.
صواب؛ الالتزام بالمعايير القياسية في Laravel 12 يجعل الكود واضحاً وسهل الفحص والصيانة.
أي آلية في Laravel 12 تتولى إدارة حماية مسارات API بحارس Sanctum بشكل مباشر ومنظم؟
توفر طبقة إطار العمل وحاوية الخدمات في Laravel 12 الأدوات القياسية لإدارة حماية مسارات API بحارس Sanctum.
لماذا يُعد تطبيق تحديد صلاحيات الرموز وفحصها برمجياً مهماً عند بناء تطبيقات Laravel 12 جاهزة للإنتاج؟
لأنه يمنع الأخطاء البرمجية الخفية ويوحد سلوك التطبيق بين بيئتي التطوير والإنتاج.
في Laravel 12، يُنصح بكتابة مفاتيح الإنتاج السرية مباشرة داخل ملفات الكود المصدري المرفوعة إلى Git بدلاً من ملفات البيئة.
خطأ؛ يجب حفظ المفاتيح والبيانات السرية في متغيرات البيئة وعدم رفعها أبداً إلى مستودع Git.
ما المزايا الهندسية التي يحققها تطبيق إلغاء رموز الوصول وتسجيل الخروج في Laravel 12؟ (اختر كل ما ينطبق)
يوفر فصلاً واضحاً للمسؤوليات، وأماناً أعلى أثناء التنفيذ، وتعاوناً أسهل بين أفراد الفريق.
يوظف إطار العمل Laravel 12 ميزات PHP 8 الحديثة مثل تحديد أنواع القيم المرجعة لجعل الكود أكثر وضوحاً وأماناً.
صواب؛ يعتمد Laravel 12 بشكل كامل على الصياغة الحديثة للغة PHP 8.2+ وسلامة الأنواع.
ما الفرق الجوهري بين معيار Laravel 12 الحديث والملفات اليدوية التقليدية في مرجع دوال وأمان Laravel Sanctum؟
يوفر Laravel 12 واجهات قياسية موحدة وحماية مدمجة تغني عن الكود اليدوي المعرض للأخطاء.