إنشاء وتشغيل مشروع Webman في ServBay

ما هو Webman؟

Webman هو إطار عمل ويب PHP عالي الأداء يعتمد على Workerman، ومصمم لبناء تطبيقات ويب عالية التحمل وقادرة على التعامل مع عدد هائل من المستخدمين المتزامنين. على عكس الإطارات التقليدية التي تعتمد على حظر العمليات، يستخدم Webman نموذج الأحداث والإدخال/الإخراج غير المتزامن، مما يجعله ممتازًا في معالجة الطلبات الكثيفة بشكل فعال. يوفر Webman واجهات برمجية سهلة ودعمًا للتوسعة عبر إضافات متنوعة، وهو حل مثالي لبناء التطبيقات الفورية، خدمات الـ API والخدمات المصغرة.

المزايا الرئيسية لـ Webman

• أداء عالي: مبني على Workerman ويستخدم نموذج الأحداث والإدخال/الإخراج غير المتزامن، مما يمكّنه من معالجة عدد هائل من الاتصالات بكفاءة أعلى بكثير من الإطارات التقليدية.
• سهولة الاستخدام: يوفر Webman واجهات برمجية سهلة الفهم وميزات قوية لتمكين المطورين من بناء التطبيقات بسرعة.
• دعم بروتوكولات متعددة: يدعم بروتوكولات مثل HTTP وWebSocket وغيرهما، مما يسهل بناء أنواع مختلفة من الخدمات بسهولة.
• توسعة مرنة: إمكانية إضافة الحزم والمكونات الإضافية والوسيطات عبر Composer بسهولة لتعزيز وظائف الإطار.
• استهلاك موارد منخفض: كمشروع يعمل في الذاكرة باستمرار، يستهلك Webman موارد أقل مقارنةً بخوادم الويب التقليدية التي تعتمد على PHP-FPM.
• مجتمع قوي ودعم واسع: يملك مجتمع مطورين نشط وموارد دعم غنية.

يساعد Webman المطورين على بناء تطبيقات ويب وخدمات API عالية الأداء وعالية التوفر، خاصة لمن يحتاج لمعالجة طلبات كثيفة بزمن استجابة منخفض.

خطوات إنشاء وتشغيل مشروع Webman بسيط باستخدام ServBay

يهدف هذا الدليل لتوضيح كيفية استخدام Webman داخل بيئة ServBay المحلية لبناء مشروع ويب بسيط. ستتعلم كيفية تثبيت Webman، كتابة واستعراض الأكواد الأساسية، ودمج قواعد البيانات (MySQL, PostgreSQL) وأنظمة التخزين المؤقت (Redis, Memcached).

TIP

ينصح ServBay المطورين بحفظ جميع مشاريع المواقع المحلية داخل المسار /Applications/ServBay/www كي يسهل على ServBay إدارتها، كضبط إعدادات المواقع المحلية (التي كانت تُسمى "استضافة" سابقاً).

المتطلبات الأساسية

قبل البدء، تأكد من توفر ما يلي:

1. تثبيت ServBay: يجب أن يكون ServBay مثبتًا بنجاح على جهاز macOS الخاص بك. ServBay يوفر بيئة تطوير متكاملة تشمل PHP، Composer، MySQL، PostgreSQL، Redis، Memcached وكل ما يحتاجه هذا الدليل.
2. تفعيل الحزم المطلوبة: عبر لوحة تحكم ServBay، تأكد من أن الحزم التالية مثبتة وتعمل:
   • إصدار PHP الذي تختاره (يفضل استخدام الإصدارات الأحدث مثل PHP 8.x)
   • Composer (موجود تلقائياً في ServBay)
   • MySQL
   • PostgreSQL
   • Redis
   • Memcached
   • تأكد من تفعيل امتدادات PHP المهمة مثل memcached، redis، pdo_mysql، pdo_pgsql. ServBay يفعل هذه الامتدادات تلقائياً عادةً، ويمكنك التحقق من ذلك في إعدادات PHP ضمن ServBay.
3. التعامل مع الطرفية (Terminal): يجب أن تكون لديك معرفة باستخدام تطبيق الطرفية في macOS.

تثبيت Webman

1. التأكد من توفر Composer

   يأتي ServBay مع Composer مثبت مسبقا، ومجهز للاستخدام من الطرفية مباشرة. للتحقق من توفره:

   composer --version

   إذا ظهرت معلومات الإصدار بشكل صحيح، فهذا يعني أن Composer جاهز للاستخدام.

2. الدخول إلى مسار المواقع في ServBay

   افتح الطرفية وادخل إلى مجلد المواقع الموصى به في ServBay:

   cd /Applications/ServBay/www

3. إنشاء مشروع Webman باستخدام Composer

   استخدم أمر create-project لتثبيت Webman في مجلد مخصص. سنسمي المشروع servbay-webman-app:

   composer create-project workerman/webman servbay-webman-app

   سيقوم Composer بتحميل Webman وجميع الاعتمادات الأساسية إلى المسار المحدد.

4. الدخول إلى مجلد المشروع

   بعد الانتهاء من التثبيت، أدخل إلى مجلد المشروع الجديد:

   cd servbay-webman-app

5. تثبيت المكونات الإضافية اللازمة

   لتجربة قواعد البيانات والتخزين المؤقت، نحتاج لبعض الحزم الإضافية من Composer مثل illuminate/database (مكون قواعد بيانات من Laravel)، وilluminate/redis. استخدم معامل -W لحل مشكلات التوافق أثناء التثبيت.

   composer require -W illuminate/database illuminate/redis illuminate/pagination illuminate/events symfony/var-dumper

   سيقوم هذا الأمر بتثبيت ORM قواعد البيانات، عميل Redis، نظام التصفح، مدير الأحداث، وأداة التصحيح VarDumper.

إنشاء قاعدة البيانات والجداول

حتى يعمل الكود بشكل صحيح، عليك إنشاء قاعدة بيانات وجداول مستخدمين (users) في MySQL وPostgreSQL داخل ServBay. كلمة المرور الافتراضية لمستخدم root في ServBay هي password.

يمكنك استخدام أدوات إدارة قواعد البيانات التي يوفرها ServBay (مثل phpMyAdmin أو pgAdmin من خلال لوحة التحكم)، أو تنفيذ الأوامر يدويًا.

1. إنشاء قاعدة البيانات webman_app

   • MySQL:

     CREATE DATABASE IF NOT EXISTS webman_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

   • PostgreSQL:

     CREATE DATABASE webman_app;

2. إنشاء جدول users داخل قاعدة البيانات webman_app

   • MySQL:

     USE webman_app;
     CREATE TABLE users (
         id INT AUTO_INCREMENT PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

   • PostgreSQL:

     \c webman_app; -- الاتصال بقاعدة البيانات الجديدة
     CREATE TABLE users (
         id SERIAL PRIMARY KEY,
         name VARCHAR(255) NOT NULL,
         email VARCHAR(255) NOT NULL UNIQUE,
         created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
     );

كتابة كود المشروع

سنضيف الكود لتعريف المسارات، إنشاء وحدات التحكم (Controllers)، وتنفيذ العمليات مع قواعد البيانات وأنظمة التخزين المؤقت.

1. إعداد المسارات (Routes)

   حرر ملف config/route.php في جذر المشروع وأضف الأكواد التالية لتعريف المسارات المطلوبة:

   <?php
   
   use Webman\Route;
   use app\controller\IndexController;
   use app\controller\CacheController;
   use app\controller\DatabaseController;
   
   // تعريف مسار الجذر، ويمرّر الطلب إلى الدالة index في IndexController
   Route::any('/', [IndexController::class, 'index']);
   
   // مسارات متعلقة بالتخزين المؤقت
   Route::any('/memcached', [CacheController::class, 'memcached']);
   Route::any('/redis', [CacheController::class, 'redis']);
   
   // مسارات متعلقة بقواعد البيانات
   Route::any('/mysql-add', [DatabaseController::class, 'mysqlAdd']);
   Route::any('/mysql', [DatabaseController::class, 'mysqlGet']);
   Route::any('/pgsql-add', [DatabaseController::class, 'pgsqlAdd']);
   Route::any('/pgsql', [DatabaseController::class, 'pgsqlGet']);
   
   // يمكنك إضافة المزيد من المسارات هنا...

2. إنشاء ملفات وحدات التحكم (Controllers)

   أنشئ في مجلد app/controller الملفات التالية: IndexController.php, CacheController.php, DatabaseController.php، وضع فيها الأكواد التالية:

   • app/controller/IndexController.php: لمعالجة طلبات الجذر.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response; // استيراد فئة Response
     
     class IndexController
     {
         /**
          * مثال لدالة معالجة طلب الجذر
          * @param Request $request كائن الطلب الحالي
          * @return Response إرجاع كائن Response
          */
         public function index(Request $request): Response // تحديد نوع الرجوع
         {
             // إرجاع رد نصي بسيط
             return response('Hello ServBay & Webman!'); // تحديث رسالة الترحيب
         }
     }

   • app/controller/CacheController.php: لعرض التعامل مع Memcached وRedis.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use Memcached; // استيراد فئة Memcached
     use support\Redis; // استيراد واجهة Redis من Webman
     
     class CacheController
     {
         /**
          * مثال على استخدام Memcached
          * @param Request $request
          * @return Response
          */
         public function memcached(Request $request): Response
         {
             // الاتصال بخادم Memcached، ServBay يعمل افتراضيًا على 127.0.0.1:11211
             $memcached = new Memcached();
             $memcached->addServer('127.0.0.1', 11211);
     
             // تعيين قيمة مؤقتة لمدة 60 ثانية
             $success = $memcached->set('servbay_key', 'Hello Memcached from ServBay!', 60); // تحديث المفتاح والقيمة
             if (!$success) {
                  return response('Failed to set Memcached key', 500);
             }
     
             // جلب القيمة المخزنة
             $value = $memcached->get('servbay_key'); // تحديث المفتاح
     
             // إرجاع القيمة أو رسالة في حال عدم العثور عليها
             return response($value ?: 'Memcached key not found or expired'); // إضافة رسالة في حال عدم العثور
         }
     
         /**
          * مثال على استخدام Redis
          * @param Request $request
          * @return Response
          */
         public function redis(Request $request): Response
         {
             // استخدام واجهة Redis في Webman للتخزين المؤقت
             Redis::set('servbay_redis_key', 'Hello Redis from ServBay!'); // تحديث المفتاح والقيمة
     
             // جلب القيمة المخزنة باستخدام واجهة Redis
             $value = Redis::get('servbay_redis_key'); // تحديث المفتاح
     
             // إرجاع القيمة أو رسالة في حال عدم العثور
             return response($value ?: 'Redis key not found'); // إضافة رسالة في حال عدم العثور
         }
     }

   • app/controller/DatabaseController.php: لعرض العمليات مع قواعد البيانات MySQL وPostgreSQL.

     <?php
     
     namespace app\controller;
     
     use support\Request;
     use support\Response;
     use support\Db; // استيراد واجهة Db من Webman
     
     class DatabaseController
     {
         /**
          * إضافة مستخدم إلى قاعدة بيانات MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlAdd(Request $request): Response
         {
             try {
                 // استخدام Db للاتصال بـ 'mysql' وإضافة بيانات المستخدم
                 Db::connection('mysql')->table('users')->insert([
                     'name' => 'ServBay Webman MySQL User', // تحديث البيانات التوضيحية
                     'email' => 'mysql_demo@servbay.test',  // تحديث البريد التوضيحي
                     'created_at' => date('Y-m-d H:i:s')    // إضافة تاريخ الإنشاء
                 ]);
                 return response('User added to MySQL'); // تحديث رسالة الاستجابة
             } catch (\Exception $e) {
                 return response('Error adding user to MySQL: ' . $e->getMessage(), 500); // معالجة الأخطاء
             }
         }
     
         /**
          * جلب قائمة المستخدمين من قاعدة بيانات MySQL
          * @param Request $request
          * @return Response
          */
         public function mysqlGet(Request $request): Response
         {
             try {
                 // جلب كافة المستخدمين من جدول users في MySQL
                 $users = Db::connection('mysql')->table('users')->get();
                 // إرجاع القائمة بصيغة JSON
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // تحديد نوع المحتوى
             } catch (\Exception $e) {
                  return response('Error getting users from MySQL: ' . $e->getMessage(), 500); // معالجة الأخطاء
             }
         }
     
         /**
          * إضافة مستخدم إلى قاعدة بيانات PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlAdd(Request $request): Response
         {
              try {
                 // استخدام Db للاتصال بـ 'pgsql' وإضافة بيانات المستخدم
                 Db::connection('pgsql')->table('users')->insert([
                     'name' => 'ServBay Webman PgSQL User',   // تحديث البيانات التوضيحية
                     'email' => 'pgsql_demo@servbay.test',    // تحديث البريد التوضيحي
                     'created_at' => date('Y-m-d H:i:s')      // إضافة تاريخ الإنشاء
                 ]);
                 return response('User added to PostgreSQL'); // تحديث رسالة الاستجابة
              } catch (\Exception $e) {
                 return response('Error adding user to PostgreSQL: ' . $e->getMessage(), 500); // معالجة الأخطاء
              }
         }
     
         /**
          * جلب قائمة المستخدمين من قاعدة بيانات PostgreSQL
          * @param Request $request
          * @return Response
          */
         public function pgsqlGet(Request $request): Response
         {
              try {
                 // جلب كافة المستخدمين من جدول users في PostgreSQL
                 $users = Db::connection('pgsql')->table('users')->get();
                 // إرجاع القائمة بصيغة JSON
                 return response(json_encode($users), 200, ['Content-Type' => 'application/json']); // تحديد نوع المحتوى
              } catch (\Exception $e) {
                 return response('Error getting users from PostgreSQL: ' . $e->getMessage(), 500); // معالجة الأخطاء
              }
         }
     }

3. إعداد معلومات الاتصال بقواعد البيانات

   حرر ملف config/database.php في جذر المشروع وأضف معلومات الاتصال بـ MySQL وPostgreSQL. الخادم الافتراضي في ServBay هو 127.0.0.1، والأرقام الافتراضية هي 3306 لـ MySQL و5432 لـ PostgreSQL، واسم المستخدم root وكلمة المرور password.

   <?php
   /**
    * إعدادات قواعد البيانات
    */
   return [
       // الاتصال الافتراضي
       'default' => 'mysql',
   
       // قائمة الاتصالات المتاحة
       'connections' => [
           'mysql' => [
               'driver'    => 'mysql',
               // عنوان و منفذ MySQL الافتراضي في ServBay
               'host'      => '127.0.0.1',
               'port'      => 3306,
               // اسم قاعدة البيانات التي أنشأتها مسبقاً
               'database'  => 'webman_app',
               // اسم المستخدم الافتراضي في ServBay
               'username'  => 'root',
               // كلمة المرور الافتراضية في ServBay
               'password'  => 'password',
               'charset'   => 'utf8mb4',
               'collation' => 'utf8mb4_unicode_ci',
               'prefix'    => '',
               'strict'    => true,
               'engine'    => null,
           ],
           'pgsql' => [
               'driver'   => 'pgsql',
               // عنوان و منفذ PostgreSQL الافتراضي في ServBay
               'host'     => '127.0.0.1',
               'port'     => 5432,
                // اسم قاعدة البيانات التي أنشأتها مسبقاً
               'database' => 'webman_app',
                // اسم المستخدم الافتراضي في ServBay
               'username' => 'root',
                // كلمة المرور الافتراضية في ServBay
               'password' => 'password',
               'charset'  => 'utf8',
               'prefix'   => '',
               'schema'   => 'public',
               'sslmode'  => 'prefer', // أو require, verify-ca, verify-full
           ],
           // يمكن إضافة المزيد من الاتصالات هنا...
       ],
   ];

   تنبيه مهم: لإنتاج التطبيقات في بيئة العمل الفعلية، يجب تغيير كلمة المرور الافتراضية وتجنب حفظ معلومات حساسة مباشرة في الكود.

تشغيل مشروع Webman

عادةً يُشغل مشروع Webman عن طريق ملف start.php الذي يبدأ العمليات في Workerman. تختلف هذه الطريقة عن تشغيل تطبيقات PHP التقليدية عبر Nginx/Apache وPHP-FPM، حيث يعمل Webman كتطبيق في الذاكرة باستمرار.

من جذر المشروع (/Applications/ServBay/www/servbay-webman-app) نفذ الأمر التالي لتشغيل Webman:

php start.php start

ستظهر معلومات بدء تشغيل Webman، وسيستمع تلقائياً على العنوان 127.0.0.1:8787 لطلبات HTTP.

• ملاحظة: أمر php يستخدم نسخة PHP المثبتة بواسطة ServBay تلقائياً، إذ تضبط ServBay بيئة الطرفية لذلك.
• لتشغيل Webman في الخلفية استعمل معامل -d: php start.php start -d.
• لإيقاف الخدمة: php start.php stop.
• لإعادة تشغيل الخدمة: php start.php restart.
• لإعادة التشغيل بسلاسة دون قطع الطلبات الجارية: php start.php reload.

اختبار المشروع

بعد نجاح تشغيل Webman واستماعه على 127.0.0.1:8787، يمكنك اختبار الوظائف عبر الروابط التالية من المتصفح:

• http://localhost:8787/ : سترى صفحة تعرض Hello ServBay & Webman!.
• http://localhost:8787/memcached : سترى رسالة Hello Memcached from ServBay!، ما يعني نجاح الاتصال واستخدام Memcached من ServBay عبر Webman.
• http://localhost:8787/redis : سترى رسالة Hello Redis from ServBay!، ما يعني نجاح الاتصال واستخدام Redis.
• http://localhost:8787/mysql-add : سترى رسالة User added to MySQL، وسيسجل مستخدم جديد في جدول users بقاعدة بيانات MySQL.
• http://localhost:8787/mysql : سترى قائمة المستخدمين من MySQL بصيغة JSON.
• http://localhost:8787/pgsql-add : سترى رسالة User added to PostgreSQL، وسيسجل مستخدم جديد في جدول users بقاعدة بيانات PostgreSQL.
• http://localhost:8787/pgsql : سترى قائمة المستخدمين من PostgreSQL بصيغة JSON.

إذا واجهت أي مشاكل، تحقق من رسائل الخطأ في الطرفية، وتأكد أن الحزم (MySQL, PostgreSQL, Redis, Memcached) تعمل ضمن ServBay، وأن امتدادات PHP مفعلة.

الأسئلة الشائعة (FAQ)

• س: لا أحدد ملف start.php start بالأمر؟
  • ج: تأكد من أنك داخل مجلد المشروع servbay-webman-app في الطرفية. كذلك تأكد أن ServBay أضاف مسار PHP بشكل صحيح إلى نظام التشغيل (ServBay يقوم بذلك تلقائياً عادةً).
• س: فشل الاتصال بـ localhost:8787؟
  • ج: راجع رسائل الطرفية عند تشغيل php start.php start، وتحقق من عدم وجود برامج أخرى تشغل المنفذ 8787. يمكنك تغيير رقم المنفذ من إعدادات Webman (ملف config/server.php).
• س: فشل الاتصال بقاعدة البيانات؟
  • ج: تأكد أن حزم MySQL وPostgreSQL تعمل في ServBay، وتحقق من بيانات الاتصال في config/database.php (العنوان، المنفذ، اسم القاعدة، اسم المستخدم، كلمة المرور). تأكد أنك أنشأت قاعدة البيانات webman_app وجدول users.
• س: فشل الاتصال بـ Memcached أو Redis؟
  • ج: تأكد أن الحزم تعمل، وتحقق من العنوان والمنفذ في app/controller/CacheController.php (127.0.0.1:11211 لـ Memcached و127.0.0.1:6379 لـ Redis). تأكد من تفعيل امتدادات PHP memcached وredis.

ملخص

بعد اتباع الخطوات السابقة، أصبح لديك مشروع Webman أساسي يعمل على بيئة ServBay المحلية. تعلمت كيف تستفيد من ServBay لخدمة تطوير متكاملة، وكيفية دمج قواعد البيانات وأنظمة التخزين المؤقت داخل Webman. يجمع Webman ميزات الأداء العالي مع سهولة ServBay ليمنحك منصة قوية لتطوير تطبيقات PHP غير متزامنة حديثة. نتمنى أن يفيدك هذا الدليل ويمنحك انطلاقة ناجحة نحو بناء تطبيقات ويب احترافية باستخدام ServBay وWebman.