GuzzleHTTP/Promises في PHP: دليل شامل مع أمثلة عملية

مرحبًا بك في الدليل الشامل لمكتبة GuzzleHTTP/Promises للغة PHP. تُعد هذه المكتبة من الركائز الأساسية في نظام Guzzle البيئي، حيث تقدم تطبيقًا قويًا لنمط "Promise" (الوعد) للبرمجة غير المتزامنة. إذا كنت تعمل مع طلبات HTTP، أو المهام المتوازية، أو ترغب ببساطة في جعل كود PHP الخاص بك أكثر كفاءة وقابلية للقراءة، فهذه المقالة لك.

1. ما هي هذه المكتبة ولماذا تحتاجها؟

GuzzleHTTP/Promises هي مكتبة PHP تطبق مفهوم Promises (الوعود) والتنفيذ غير المتزامن للمهام. هي جزء من نظام Guzzle البيئي، ولكن يمكن استخدامها بشكل مستقل تمامًا عن عميل HTTP. الفكرة الأساسية للوعود هي إنشاء كائن يمثل نتيجة عملية غير متزامنة، يمكن الحصول عليها الآن أو لاحقًا أو أبدًا. يتيح لك ذلك كتابة كود لا يمنع تنفيذ البرنامج أثناء انتظار اكتمال العمليات الطويلة.

لماذا نحتاج هذا في PHP؟ تقليديًا، PHP هي لغة متزامنة (Synchronous)، حيث يتم تنفيذ كل عملية بشكل تسلسلي. ولكن مع تزايد شعبية الخدمات المصغرة (Microservices)، والتكامل مع واجهات API، والعمل مع الخدمات الخارجية، ظهرت الحاجة إلى إدارة فعالة للمهام المتوازية. تحل GuzzleHTTP/Promises هذه المشكلة، مما يسمح لك بتشغيل عدة عمليات في وقت واحد (مثل عدة طلبات HTTP لواجهات API مختلفة) ومعالجة نتائجها فور اكتمالها، دون انتظار تنفيذها واحدة تلو الأخرى.

توفر المكتبة مجموعة كاملة من الأدوات للعمل مع الكود غير المتزامن: إنشاء الوعود، دمجها، سلاسل الاستدعاءات، معالجة الأخطاء، وإدارة مهلات الانتظار. هي المعيار الفعلي (De facto) للعمل غير المتزامن في مجتمع PHP، وتُستخدم في مشاريع شهيرة مثل Laravel و Symfony و WordPress (عبر الإضافات) وبالطبع عميل Guzzle HTTP نفسه.

2. التثبيت

يتم تثبيت المكتبة عبر Composer، مدير الحزم القياسي لـ PHP. قم بتنفيذ الأمر التالي في terminal في جذر مشروعك:

composer require guzzlehttp/promises

إذا كنت تستخدم عميل Guzzle HTTP، فإن مكتبة الوعود مضمنة بالفعل في تبعياته، ولا تحتاج إلى تثبيت منفصل. بعد التثبيت، تأكد من تضمين ملف vendor/autoload.php في السكريبت الخاص بك:

require 'vendor/autoload.php';

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

لننشئ مثالًا بسيطًا للعمل مع الوعود. سننشئ وعدًا "يتم تنفيذه" بعد ثانية واحدة ويعيد النص "Hello, World!":

use GuzzleHttp\Promise\Promise;
use GuzzleHttp\Promise\Utils;

// إنشاء وعد جديد
$promise = new Promise(function () use (&$promise) {
    // محاكاة عملية غير متزامنة
    usleep(1000000); // 1 ثانية
    $promise->resolve('Hello, World!');
});

// إضافة معالج للتنفيذ الناجح
$promise->then(function ($value) {
    echo "تم الاستلام: " . $value . PHP_EOL;
});

// تشغيل تنفيذ الوعد
Utils::queue()->add(function () use ($promise) {
    $promise->wait();
});

// تشغيل قائمة الانتظار
Utils::queue()->run();

يوضح هذا المثال الآلية الأساسية: إنشاء وعد، حله (resolve)، ومعالجة النتيجة عبر دالة then.