في بناء الأنظمة الويب الحديثة، لم تعد لغة PHP تُستخدم فقط لتوليد صفحات HTML بالطريقة التقليدية، بل أصبحت محركاً أساسياً لتطوير واجهات برمجة التطبيقات (APIs) التي تغذي تطبيقات الهواتف الذكية وتطبيقات الواجهات الأمامية المعتمدة على إطارات عمل متقدمة مثل React أو Vue أو Angular. تعتمد المعمارية الأكثر شيوعاً واستقراراً في هذا المجال على نمط REST أو (Representational State Transfer). في هذا الدليل التقني الشامل من مسار PHP المتقدم، سنتناول كيفية بناء RESTful API حقيقية وقوية باستخدام PHP الصرفة (Vanilla PHP) ودون الاعتماد على مكتبات أو إطارات عمل خارجية، لنفهم الآلية الداخلية التي تدير الطلبات، وتفسير رؤوس الطلبات (Headers)، وإرسال الاستجابات بصيغة JSON بشكل صحيح وآمن ومستدام.

فلسفة تصميم REST والتعامل مع بروتوكول HTTP

قبل كتابة أي سطر برمجي، من الضروري إدراك أن واجهة برمجة التطبيقات (API) تعتمد اعتماداً كاملاً على بروتوكول HTTP. على عكس صفحات الويب العادية التي تستخدم غالباً طريقتي GET و POST فقط، تستخدم معمارية REST مجموعة كاملة من أساليب HTTP (HTTP Methods) لتمثيل العمليات المختلفة على الموارد (Resources). كل عنوان URL يمثل مورداً محدداً بوضوح، بينما يحدد الأسلوب نوع العملية المطلوب تنفيذها على هذا المورد.

تتوزع العمليات الحيوية عبر أساليب HTTP الأساسية بالشكل التالي:

• GET: لاسترجاع بيانات مورد واحد أو قائمة من الموارد، ولا يجب أن تتسبب هذه العملية في أي تعديل على حالة الخادم أو قاعدة البيانات.
• POST: لإنشاء مورد جديد على الخادم، حيث يتم تمرير بيانات المورد الجديد ضمن جسم الطلب (Request Body).
• PUT: لتحديث مورد بالكامل، أو استبداله بالكامل إن كان موجوداً، أو إنشائه إن لم يكن موجوداً في بعض التصميمات.
• DELETE: لحذف المورد المحدد بناءً على معرفه أو معيار التحديد الخاص به.

بالإضافة إلى الأساليب، تعتمد RESTful APIs على رموز الحالة (HTTP Status Codes) لتواصل واضح ودقيق مع العميل حول نتيجة الطلب. استخدام الرمز 200 للنجاح العام، و201 لإنشاء المورد بنجاح، و400 للطلب الخاطئ أو غير المفهوم، و404 لعدم العثور على المورد المطلوب، و422 لبيانات غير قابلة للمعالجة، و500 لأخطاء الخادم الداخلي، هو جزء لا يتجزأ من التصميم الاحترافي الذي يسهل عملية تصحيح الأخطاء (Debugging) للفرق التي تستهلك الـ API.

إعداد هيكل التوجيه (Routing) الأساسي ومعالجة الطلبات

في بيئة PHP الصرفة، لا يوجد نظام توجيه مدمج للـ APIs كما هو الحال في إطارات العمل الضخمة مثل Laravel أو Symfony. لذلك، سنقوم بإنشاء موجه (Router) بسيط وفعال يستقبل جميع الطلبات عبر ملف موحد (مثل index.php) باستخدام إعدادات إعادة توجيه عناوين URL (URL Rewriting) عبر ملف .htaccess.

دعنا نفترض أن لدينا جدولاً للمستخدمين (Users) ونريد بناء API تدير بياناتهم بشكل كامل. الخطوة الأولى هي توجيه كافة الطلبات إلى نقطة دخول مركزية واحدة بغض النظر عن المسار الفرعي. إليك محتوى ملف التوجيه وضبط الـ .htaccess الأساسي لتوجيه المسارات:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>

الآن، سنقوم برمجة ملف index.php الأساسي ليكون النواة التي تلتقط المسار (Path) وطريقة الطلب (Method) وتمررها إلى المتحكم (Controller) المناسب بناءً على طلب العميل:

<?php
header("Access-Control-Allow-Origin: *");
header("Content-Type: application/json; charset=UTF-8");
header("Access-Control-Allow-Methods: GET, POST, PUT, DELETE");
header("Access-Control-Allow-Headers: Content-Type, Access-Control-Allow-Headers, Authorization, X-Requested-With");

// تحديد المسار المطلوب وطريقة الطلب
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$uri = explode( '/', $uri );

// استخراج طريقة الطلب HTTP Method
$requestMethod = $_SERVER["REQUEST_METHOD"];

// التحقق من صحة نقطة النهاية (Endpoint) الأساسية
if ($uri[1] !== 'api' || $uri[2] !== 'users') {
    header("HTTP/1.1 404 Not Found");
    echo json_encode(array("message" => "Endpoint not found."));
    exit();
}

// استخراج معرف المستخدم إن وجد في المسار
$userId = null;
if (isset($uri[3])) {
    $userId = (int) $uri[3];
}

require_once "./Controllers/UserApiController.php";
$controller = new UserApiController($requestMethod, $userId);
$controller->processRequest();
?>

شرح هيكل التوجيه وتدفق العمل

يقوم الكود أعلاه بضبط الرؤوس (Headers) الخاصة بمشاركة الموارد عبر النطاقات المختلفة (CORS)، مما يسمح للبرامج والتطبيقات الخارجية بالاتصال بالـ API بسلاسة. بعد ذلك، يقوم بتحليل المسار (URI) لمعرفة ما إذا كان الطلب موجهاً نحو نقطة النهاية الصحيحة /api/users، مع استخراج معرف المستخدم إن وُجد في الجزء الرابع من المسار (مثل /api/users/5). أخيرًا، يتم استدعاء المتحكم المسؤول عن معالجة البيانات وإرسال الرد.

بناء المتحكم (Controller) ومعالجة البيانات

المتحكم هو الطبقة البرمجية المسؤولة عن اتخاذ القرار الهندسي: قراءة المدخلات، تنفيذ العمليات عبر قاعدة البيانات، وإرجاع الاستجابة المناسبة بصيغة JSON. سنكتب الآن كود متحكم UserApiController.php الذي يتعامل مع العمليات الأربع الشهيرة (CRUD).

<?php
class UserApiController {
    private $requestMethod;
    private $userId;

    public function __construct($requestMethod, $userId) {
        $this->requestMethod = $requestMethod;
        $this->userId = $userId;
    }

    public function processRequest() {
        switch ($this->requestMethod) {
            case 'GET':
                if ($this->userId) {
                    $response = $this->getUser($this->userId);
                } else {
                    $response = $this->getAllUsers();
                }
                break;
            case 'POST':
                $response = $this->createUser();
                break;
            case 'PUT':
                $response = $this->updateUser($this->userId);
                break;
            case 'DELETE':
                $response = $this->deleteUser($this->userId);
                break;
            default:
                $response = $this->notFoundResponse();
                break;
        }

        header($response['status_code_header']);
        if ($response['body']) {
            echo $response['body'];
        }
    }

    private function getAllUsers() {
        // محاكاة لجلب البيانات من قاعدة البيانات الفعلية
        $data = [
            ["id" => 1, "name" => "أحمد محمد", "email" => "ahmed@example.com"],
            ["id" => 2, "name" => "سارة علي", "email" => "sara@example.com"]
        ];
        $response['status_code_header'] = 'HTTP/1.1 200 OK';
        $response['body'] = json_encode($data);
        return $response;
    }

    private function getUser($id) {
        // مثال افتراضي للبحث عن مستخدم برقم المعرف
        if ($id !== 1) {
            return $this->notFoundResponse();
        }
        $data = ["id" => 1, "name" => "أحمد محمد", "email" => "ahmed@example.com"];
        $response['status_code_header'] = 'HTTP/1.1 200 OK';
        $response['body'] = json_encode($data);
        return $response;
    }

    private function createUser() {
        $input = (array) json_decode(file_get_contents('php://input'), TRUE);
        if (!isset($input['name']) || !isset($input['email'])) {
            return $this->unprocessableEntityResponse();
        }

        // منطق الحفظ الفعلي في قاعدة البيانات يتم هنا باستخدام PDO الاستعدادي

        $response['status_code_header'] = 'HTTP/1.1 201 Created';
        $response['body'] = json_encode([
            "message" => "User created successfully",
            "data" => $input
        ]);
        return $response;
    }

    private function updateUser($id) {
        if (!$id) {
            return $this->notFoundResponse();
        }
        $input = (array) json_decode(file_get_contents('php://input'), TRUE);
        if (!isset($input['name']) || !isset($input['email'])) {
            return $this->unprocessableEntityResponse();
        }

        // منطق التحديث الفعلي في قاعدة البيانات يتم هنا

        $response['status_code_header'] = 'HTTP/1.1 200 OK';
        $response['body'] = json_encode([
            "message" => "User updated successfully",
            "data" => $input
        ]);
        return $response;
    }

    private function deleteUser($id) {
        if (!$id) {
            return $this->notFoundResponse();
        }

        // منطق الحذف الفعلي من قاعدة البيانات يتم هنا

        $response['status_code_header'] = 'HTTP/1.1 200 OK';
        $response['body'] = json_encode([
            "message" => "User deleted successfully",
            "id" => $id
        ]);
        return $response;
    }

    private function unprocessableEntityResponse() {
        $response['status_code_header'] = 'HTTP/1.1 422 Unprocessable Entity';
        $response['body'] = json_encode([
            "error" => "Invalid input data. Name and email are required fields."
        ]);
        return $response;
    }

    private function notFoundResponse() {
        $response['status_code_header'] = 'HTTP/1.1 404 Not Found';
        $response['body'] = json_encode([
            "error" => "Resource not found."
        ]);
        return $response;
    }
}
?>

تحليل آليات العمل والتعامل مع المدخلات الجسدية

يعتمد المتحكم بشكل أساسي على دالة file_get_contents('php://input') لقراءة البيانات المرسلة من العميل بصيغة JSON ضمن طلبات POST أو PUT، وذلك لأن PHP لا تقوم بملء مصفوفة $_POST تلقائياً عند التعامل مع طلبات REST التي ترسل البيانات في جسم الطلب (Raw Request Bodies) وليس كنموذج HTML تقليدي (Form Data). بعد قراءة وتحويل هذه البيانات إلى مصفوفة باستخدام json_decode، يتم التحقق بدقة من وجود الحقول المطلوبة مثل الاسم والبريد الإلكتروني، وفي حال حدوث نقص أو خطأ يتم إرجاع رمز الحالة 422 مع رسالة خطأ واضحة تتيح لمطور الواجهة الأمامية فهم سبب الرفض دون تخمين.

الأخطاء الشائعة واعتبارات الأمان في واجهات APIs

عند بناء واجهات برمجة التطبيقات باستخدام PHP الصرفة، تظهر تحديات أمنية وهندسية يجب التعامل بحذر شديد معها لضمان استقرار النظام ومنع الثغرات:

• إهمال التحقق وتطهير المدخلات (Input Validation & Sanitization): الاعتماد على إرسال البيانات مباشرة إلى قاعدة البيانات دون تنظيف أو تحقق يعرض النظام لثغرات حقن SQL أو هجمات تجاوز البيانات. يجب دائماً استخدام الاستعدادات البرمجية (Prepared Statements) في كائنات PDO والتحقق من نوع البيانات وطولها.
• عدم التعامل السليم مع رموز الحالة (Status Codes): إرجاع رمز 200 دائماً بغض النظر عن حالة الطلب (حتى عند حدوث خطأ داخلي وإرسال رسالة نصية داخل جسم الاستجابة) يربك العميل ويمنع مكتبات جلب البيانات الشهيرة مثل Axios أو Fetch من التعامل مع الأخطاء بصورة سليمة وعبر كتل الاستثناءات.
• غياب حماية وتكوين CORS المناسب: ضبط الرؤوس بصورة عشوائية مثل السماح لجميع النطاقات (*) قد يشكل خطراً فادحاً إذا كانت الـ API تحتوي على بيانات حساسة للمستخدمين وتتطلب مصادقة تعتمد على ملفات الارتباط (Cookies) أو الرموز المميزة (Tokens).
• معالجة الاستثناءات والأخطاء الداخلية (Exception Handling): السماح بعرض أخطاء PHP الافتراضية للمستخدم النهائي يكشف بنية النظام ومسارات ملفات الخادم الداخلية. يجب دائماً التقاط الاستثناءات عبر كتل (Try-Catch) وإرجاع رسالة خطأ موحدة بصيغة JSON تحمل رمز الحالة 500 عند تعطل الخادم.

خلاصة الدرس

إنشاء واجهات برمجة تطبيقات RESTful قوية ومستقرة باستخدام لغة PHP الصرفة يتطلب فهماً عميقاً لبروتوكول HTTP وكيفية التعامل مع المدخلات بصيغة JSON وتوجيه الطلبات بالطريقة الصحيحة عبر خادم الويب. من خلال تنظيم الكود الهندسي لفصل آليات التوجيه عن منطق المعالجة داخل المتحكمات، يمكنك بناء نواة نظام قابلة للتوسع والصيانة بسهولة، مما يمهد الطريق لربط تطبيقات الويب والهواتف بمختلف المنصات والعملاء بكفاءة عالية وموثوقية تامة، ودون الحاجة لاعتماد مفرط على إطارات العمل الضخمة في المشاريع البرمجية البسيطة والمتوسطة.