في هذا الدرس 6تصفّح المواضيع
عندما يتصل تطبيق واجهة أمامية يعمل على النطاق https://app.example.com بواجهة JSON API مستضافة على https://api.example.com، يفرض المتصفح سياسة النطاق الواحد (Same-Origin Policy). وما لم يرسل خادم PHP رؤوس مشاركة الموارد عبر النطاقات (CORS) التي تصرح لهذا النطاق، سيمنع المتصفح كود JavaScript من قراءة الاستجابة.
- لا ترسل أبداً الرأس المفتوح
Access-Control-Allow-Origin: *في الواجهات المحمية؛ بل افحص$_SERVER['HTTP_ORIGIN']مقابل قائمة بيضاء صريحة باستخدامin_array($origin, $allowed, true). - أرسل دائماً الرأس
Vary: Originعند اختيار النطاق ديناميكياً لمنع خوادم التخزين المؤقت (CDN) من خلط رؤوس النطاقات. - حدد طرق HTTP والرؤوس المسموحة صراحةً عبر
Access-Control-Allow-MethodsوAccess-Control-Allow-Headers.
تفحص هذه الدالة النطاق الطالب مقابل قائمة بيضاء صارمة وتضبط رؤوس CORS المناسبة:
<?php
$origin = $_SERVER['HTTP_ORIGIN'] ?? 'https://app.closetag.com';
$allowed = ['https://app.closetag.com', 'https://admin.closetag.com'];
$headers = ['Vary: Origin'];
if (in_array($origin, $allowed, true)) {
$headers[] = "Access-Control-Allow-Origin: {$origin}";
$headers[] = 'Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS';
$headers[] = 'Access-Control-Allow-Headers: Content-Type, Authorization';
}
echo implode("\n", $headers) . "\n";
قبل أن يرسل المتصفح طلباً عابراً للنطاقات يحتوي على جسم Content-Type: application/json أو رأس المصادقة Authorization: Bearer، فإنه يرسل تلقائياً طلب فحص استباقي (CORS Preflight) بطريقة OPTIONS للتأكد من موافقة الخادم.
- لا يرسل المتصفح رأس
Authorizationأثناء طلبOPTIONSالاستباقي؛ لذلك إذا شغل سكربت PHP فحص المصادقة قبل فحص طريقةOPTIONSفستفشل جميع الطلبات الاستباقية بخطأ401! - اعترض الشرط
$_SERVER['REQUEST_METHOD'] === 'OPTIONS'في بداية نقطة دخول الـ API، وأرسل رؤوس CORS مع كود الحالة204 No Contentوأنهِ التنفيذ فوراً. - أضف الرأس
Access-Control-Max-Age: 86400ليحفظ المتصفح نتيجة الفحص الاستباقي لمدة 24 ساعة بدلاً من تكرار طلبOPTIONSقبل كل استدعاء.
يوضح هذا المثال كيفية معالجة طلب OPTIONS الاستباقي فوراً قبل تشغيل أي استعلامات قاعدة بيانات:
<?php
function handleCorsPreflight(string $method, string $origin): array {
$allowed = ['https://app.closetag.com'];
if (!in_array($origin, $allowed, true)) return ['status' => 403, 'headers' => []];
$headers = ["Access-Control-Allow-Origin: {$origin}", 'Access-Control-Max-Age: 86400'];
if ($method === 'OPTIONS') return ['status' => 204, 'headers' => $headers];
return ['status' => 200, 'headers' => $headers];
}
$res = handleCorsPreflight('OPTIONS', 'https://app.closetag.com');
echo "Status: {$res['status']} (" . count($res['headers']) . " CORS headers)\n";
تعتمد واجهات JSON API عديمة الحالة (Stateless) على رموز Bearer العشوائية لمصادقة العملاء بدلاً من كوكيز الجلسات. ولّد هذه الرموز باستخدام المولد التشفيري الآمن bin2hex(random_bytes(32)) وخزّن بصمتها المشفرة بـ SHA-256 فقط في قاعدة البيانات.
- أضف بادئة واضحة للرمز الخام (مثل
ct_live_) لمساعدة المطورين وأدوات فحص الأسرار على تمييز المفاتيح فوراً. - اعرض الرمز النصي الخام للمستخدم مرة واحدة فقط لحظة إنشائه، وخزّن ناتج
hash('sha256', $plainToken)في عمودtoken_hash. - نظراً لأن الرمز المولد من 32 بايت عشوائي يمتلك كثافة احتمالات تبلغ 256 بت، فإن تجزئة
SHA-256آمنة تماماً ضد القواميس وتسمح بالبحث المفهرس السريع في SQL.
يولّد هذا الكود رمز API عشوائياً ببادئة قياسية ويحسب بصمة SHA-256 المكونة من 64 محرفاً لتخزينها في قاعدة البيانات:
<?php
$plainToken = 'ct_live_' . bin2hex(random_bytes(32));
$tokenHash = hash('sha256', $plainToken);
echo 'Token Prefix: ' . substr($plainToken, 0, 16) . "...\n";
echo 'SHA-256 Length: ' . strlen($tokenHash) . " hex chars\n";
بمجرد استخراج رمز Bearer من الطلب، احسب بصمته عبر hash('sha256', $rawToken) وابحث عنها في جدول api_tokens مربوطاً بجدول users. تحقق دائماً من أن صلاحية الرمز لم تنتهِ (expires_at > :now) وأنه غير ملغى.
- ضع فهرساً فريداً
UNIQUEعلى العمودapi_tokens(token_hash)ليتم التحقق من كل طلب API في أجزاء من المللي ثانية. - اربط جدول
usersعبرINNER JOINفي نفس الاستعلام المحضر لجلب معرف المستخدم ودوره في رحلة استعلام واحدة. - يمكنك تحديث حقل
last_used_atلتمكين المستخدم من مراقبة آخر استخدام لكل مفتاح API من إعدادات حسابه.
يتحقق هذا المثال عبر PDO من بصمة الرمز وتاريخ انتهاء صلاحيته ويجلب بيانات المستخدم المالك له:
<?php
$pdo = new PDO('sqlite::memory:');
$pdo->exec('CREATE TABLE users (id INT, name TEXT, role TEXT)');
$pdo->exec('CREATE TABLE api_tokens (user_id INT, token_hash TEXT UNIQUE, expires_at INT)');
$raw = 'ct_live_secret_token_99';
$pdo->exec("INSERT INTO users VALUES (5, 'Omar Khaled', 'editor')");
$pdo->prepare('INSERT INTO api_tokens VALUES (5, :h, :e)')->execute(['h' => hash('sha256', $raw), 'e' => time() + 3600]);
$stmt = $pdo->prepare('SELECT u.id, u.name, u.role FROM api_tokens t JOIN users u ON u.id = t.user_id WHERE t.token_hash = :h AND t.expires_at > :now');
$stmt->execute(['h' => hash('sha256', $raw), 'now' => time()]);
echo json_encode($stmt->fetch(PDO::FETCH_ASSOC)) . "\n";
عندما يفشل طلب الـ API في المصادقة أو يتجاوز حصة الطلبات المسموحة، لا تقم أبداً بإعادة توجيه العميل إلى صفحة تسجيل دخول HTML؛ بل أعد استجابة خطأ بصيغة JSON موحدة مع رمز حالة HTTP القياسي والرؤوس المرافقة.
- أعد الحالة
401 Unauthorizedمع الرأسWWW-Authenticate: Bearerعند غياب الرمز أو عدم صحته أو انتهاء صلاحيته. - أعد الحالة
403 Forbiddenعندما يكون الرمز صحيحاً ولكن المستخدم لا يمتلك الصلاحية الكافية لتنفيذ الإجراء المطلوب. - أعد الحالة
429 Too Many Requestsمع الرأسRetry-Afterعند تجاوز الحد المسموح من الطلبات في الدقيقة.
يلخص الجدول التالي رموز الحالة القياسية والرؤوس المرافقة لها في واجهات PHP JSON API المحمية:
| رمز حالة HTTP | الحالة التي يمثلها | الرأس المرافق المطلوب |
|---|---|---|
204 No Content | نجاح طلب الفحص الاستباقي OPTIONS | Access-Control-Allow-Origin وAccess-Control-Max-Age |
401 Unauthorized | غياب رمز Bearer أو عدم صحته أو انتهاء صلاحيته | WWW-Authenticate: Bearer |
403 Forbidden | الرمز موثق لكن المستخدم لا يملك صلاحية الوصول | Content-Type: application/json |
429 Too Many Requests | تجاوز حصة الطلبات المسموحة في النافذة الزمنية | Retry-After: 60 |
<?php
function jsonApiError(int $status, string $code, string $message): string {
return json_encode([
'ok' => false,
'status' => $status,
'error' => ['code' => $code, 'message' => $message],
], JSON_UNESCAPED_UNICODE);
}
echo jsonApiError(401, 'TOKEN_EXPIRED', 'Your Bearer token has expired.') . "\n";
echo jsonApiError(429, 'QUOTA_EXCEEDED', 'Rate limit exceeded. Retry in 60s.') . "\n";
ملخص الدرس
حصاد الدرسمراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي
ماذا تعلّمت في هذا الدرس؟
أتقنت في هذا الدرس ضبط رؤوس CORS بقائمة بيضاء، ومعالجة طلبات OPTIONS الاستباقية بكود 204، وتوليد وتشفير رموز Bearer بـ SHA-256، والتحقق منها عبر PDO، وإرجاع أخطاء 401 و429 القياسية. في الوحدة التالية سننتقل إلى بناء تطبيق الويب المتكامل بدءاً من الموجه ومعمارية MVC.
سجّل الدخول لحفظ تقدمك
تابع إنجاز المواضيع والمصطلحات والمهام، وكمّل من آخر خطوة على أي جهاز.
المصطلحات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 Cross-Origin Resource Sharing (CORS) مشاركة الموارد عبر النطاقات (CORS)
- آلية تعتمد على رؤوس HTTP تسمح للخادم بتحديد النطاقات الخارجية المسموح لها بقراءة استجاباته داخل المتصفح.
- للمراجعة
- 02 Preflight Request (OPTIONS) طلب الفحص الاستباقي (OPTIONS Preflight)
- طلب OPTIONS تلقائي يرسله المتصفح قبل الطلبات العابرة للنطاقات التي تضم رؤوساً مخصصة مثل Authorization أو جسم JSON.
- للمراجعة
- 03 Bearer Token Authentication مصادقة رمز الحامل (Bearer Token)
- نظام مصادقة عديم الحالة يرسل فيه العميل رمزاً سرياً داخل الرأس Authorization: Bearer مع كل طلب.
- للمراجعة
- 04 SHA-256 Token Digest بصمة الرمز المشفرة (SHA-256 Digest)
- بصمة سداسية عشرية بطول 64 محرفاً غير قابلة للعكس تُخزن في قاعدة البيانات بدلاً من رمز API النصي الخام.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
الاختصارات4
راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.
- 01 CORS مشاركة الموارد عبر النطاقات
- Cross-Origin Resource Sharing
- بروتوكول أمان في المتصفح ينظم الطلبات العابرة للنطاقات عبر رؤوس Access-Control-*.
- للمراجعة
- 02 API واجهة برمجة التطبيقات
- Application Programming Interface
- نقاط نهاية برمجية تتبادل بيانات JSON المهيكلة بين التطبيقات والخادم.
- للمراجعة
- 03 CSPRNG مولد أرقام عشوائية آمن تشفيرياً
- Cryptographically Secure Pseudo-Random Number Generator
- مصدر عشوائية تشفيري في نظام التشغيل يُستدعى عبر random_bytes() لتوليد رموز غير قابلة للتخمين.
- للمراجعة
- 04 SPA تطبيق الصفحة الواحدة
- Single-Page Application
- تطبيق واجهة أمامية يتخاطب مع خادم PHP عبر واجهات JSON API المدعومة برؤوس CORS.
- للمراجعة
لا توجد بطاقات تطابق البحث والتصفية.
اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.
مهامك قبل الاختبار
خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.
-
اكتب فحصاً في PHP يتحقق من وجود النطاق ضمن القائمة البيضاء ويرد على طلبات OPTIONS بكود 204 مع رأس Access-Control-Allow-Headers.
-
استخرج رمز Bearer من رأس Authorization عبر preg_match() واحسب بصمته بـ hash("sha256", $token) للبحث عنه في جدول api_tokens.
تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.
اختبر فهمك.
ووصلها للإتقان.
كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.
أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.
الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.
لمحة عن التحدي8 أسئلة تنتظرك +
لماذا يجب إرسال الرأس "Vary: Origin" عند تحديد قيمة Access-Control-Allow-Origin ديناميكياً من قائمة بيضاء؟
يخبر الرأس Vary: Origin خوادم التخزين المؤقت بعدم تقديم استجابة CORS المخزنة لنطاق معين إلى زائر قادم من نطاق آخر.
ماذا يحدث إذا قام سكربت الـ API بفحص رمز Bearer قبل التحقق مما إذا كانت طريقة الطلب هي OPTIONS؟
لا يرسل المتصفح رأس Authorization في طلبات OPTIONS الاستباقية، مما يؤدي لفشل الفحص الاستباقي بخطأ 401 وحظر الطلب الفعلي.
يجب تشفير رموز API المولدة عبر random_bytes(32) بدالة التجزئة hash("sha256", $token) قبل حفظها في قاعدة البيانات.
صواب؛ حفظ بصمة SHA-256 فقط يحمي حسابات المستخدمين حتى لو تسربت بيانات جدول الرموز.
لماذا يجب إرسال رموز API داخل الرأس "Authorization: Bearer" بدلاً من رابط الاستعلام (?api_key=...)؟
معاملات الرابط تُسجّل كنص واضح في سجلات الخادم وسجل تصفح المتصفح ورأس Referer، مما يعرض المفتاح للتسريب.
أي شرط في استعلام SQL يضمن رفض رموز API منتهية الصلاحية مباشرةً أثناء التحقق عبر PDO؟
إضافة الشرط AND expires_at > :now يستبعد الرموز منتهية الصلاحية مباشرة أثناء الاستعلام.
ما رمز حالة HTTP القياسي الذي يجب أن تعيده واجهة JSON API عند غياب رمز Bearer أو عدم صحته؟
الرمز 401 Unauthorized هو الرمز القياسي لفشل المصادقة بسبب غياب الرمز أو عدم صلاحيته.
اختر جميع الممارسات الأمنية الصحيحة عند بناء واجهة API تدعم CORS ورموز Bearer في PHP:
فحص النطاق في قائمة بيضاء، والرد المبكر على OPTIONS بكود 204، وتشفير الرموز بـ SHA-256 هي الممارسات الأساسية.
عند تجاوز العميل لحد الطلبات في واجهة API، فإن إرجاع الكود 429 Too Many Requests مع الرأس Retry-After يحدد للعميل عدد الثواني اللازمة للانتظار قبل إعادة المحاولة.
صواب؛ الكود 429 مع الرأس Retry-After هو المعيار القياسي لتحديد معدل الطلبات في واجهات API.