إنشاء وتشغيل مشروع FuelPHP في بيئة ServBay المحلية

ما هو FuelPHP؟

يعد FuelPHP إطار عمل PHP مرنًا وذو طابع معياري صُمّم خصيصًا لبناء تطبيقات الويب الحديثة. يعتمد على نمط التصميم الهيكلي HMVC (النموذج-العرض-المتحكم الهيراركي)، ويوفر مجموعة غنية من الميزات والأدوات التي تهدف إلى مساعدة المطورين في بناء تطبيقات ويب عالية الجودة بسرعة وكفاءة. أصبح FuelPHP اختياراً مفضلاً لدى العديد من مطوري PHP بفضل مرونته المتقدمة، أدائه العالي، وسهولة توسعته.

أبرز ميزات وخصائص FuelPHP

• بنية HMVC: يدعم نمط التصميم الهيكلي (HMVC)، مما يسهم في تنظيم الكود وإعادة استخدامه وتطويره بطريقة معيارية، وهو مناسب بشكل خاص للمشاريع الكبيرة والمعقدة.
• أداء عالي: يتميز FuelPHP بتحسينات في الأداء وكفاءة استخدام الموارد، ويشتهر بسرعته وقدرته على التعامل مع طلبات متزامنة عديدة بدون تعطّل.
• قابلية التوسعة: يتيح الإطار آلية توسعة قوية تُمكّن المطورين من دمج مكتبات طرف ثالث أو إضافة وظائف مخصصة بسهولة لتلبية متطلبات المشاريع الخاصة.
• الحماية والأمان: يتضمن وظائف أمان متعددة منها الفحص التلقائي للمدخلات، وتصفية المخرجات لمنع هجمات XSS، والحماية من CSRF، ومنع حقن SQL، وغير ذلك للحفاظ على سلامة التطبيق.
• دعم مجتمعي قوي: يوجد مجتمع نشط من المطورين حول FuelPHP يمكن من خلاله الحصول على دعم سريع والكثير من الموارد الإضافية.

تُسهم هذه الميزات في تمكين المطورين من بناء تطبيقات ويب عالية الأداء وآمنة وسهلة الصيانة، وتناسب مشاريع من كل الأحجام من الصغرى حتى المؤسسية.

إعداد بيئة تطوير FuelPHP باستخدام ServBay

يعتبر ServBay بيئة تطوير ويب محلية موجهة للمطورين، حيث يأتي مزودًا مسبقًا بخدمات وأدوات برمجية مثل PHP، وخوادم الويب (Caddy/Nginx/Apache)، وقواعد البيانات (MySQL/PostgreSQL/MongoDB)، وأنظمة التخزين المؤقت مثل Redis. باستخدام ServBay، يمكنك إعداد البيئة اللازمة لمشاريع FuelPHP بسهولة دون الحاجة للتثبيت اليدوي أو تهيئة الاعتمادات.

سيوضح هذا الدليل كيفية الاستفادة من بيئة PHP المتكاملة من ServBay، وخادم الويب (Caddy)، وقواعد البيانات وخدمات التخزين المؤقت لإنشاء وتشغيل مشروع FuelPHP. سنعتمد على ميزة المواقع في ServBay لإعداد خادم الويب والوصول السريع إلى المشروع للاختبار.

المتطلبات المسبقة

قبل أن تبدأ، تأكد من تحقق النقاط التالية:

• تم تثبيت ServBay بنجاح والعمل عليه في نظام macOS.
• تم تفعيل بيئة PHP في ServBay (مفعّلة افتراضيًا).
• بدء تشغيل كافة خدمات قاعدة البيانات (مثل MySQL) وخدمات التخزين المؤقت (مثل Redis، Memcached) التي ترغب بستخدامها في ServBay وتعمل بصورة طبيعية.
• يأتي Composer مثبتًا مع ServBay ولا يتطلب تثبيتًا إضافيًا.

إنشاء مشروع FuelPHP

المسار الموصى به لمجلدات المشاريع

تنصح ServBay المطورين بوضع جميع مشاريعهم في المسار /Applications/ServBay/www لأغراض الإدارة والتنظيم. سيتم استخدام هذا المسار ضمن الدليل كمثال توضيحي.

1. الانتقال إلى مجلد المواقع الجذر

   افتح تطبيق الطرفية (Terminal) وانتقل إلى مجلد المواقع المقترح أعلاه:

   cd /Applications/ServBay/www

2. إنشاء مجلد المشروع

   أنشئ مجلدًا جديدًا لمشروعك ثم ادخل إليه:

   mkdir servbay-fuelphp-app
   cd servbay-fuelphp-app

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

   من داخل مجلد المشروع، استخدم Composer لتنزيل وإعداد إطار العمل. النقطة (.) تعني أن المشروع سينشأ في نفس المجلد الحالي:

   composer create-project fuel/fuel .

   سيقوم Composer تلقائيًا بتنزيل FuelPHP وجميع المكونات التابعة إلى مجلد servbay-fuelphp-app.

إعداد خادم الويب (باستخدام ميزة المواقع في ServBay)

لتتمكن من زيارة مشروع FuelPHP من المتصفح، يجب إعداد موقع افتراضي له من خلال ميزة المواقع في ServBay.

1. افتح واجهة ServBay الرئيسية.
2. انقر على قائمة المواقع من الشريط الجانبي.
3. اضغط زر إضافة موقع في الزاوية اليمنى العلوية.
4. في نافذة التهيئة المنبثقة، أدخل المعلومات التالية:
   • الاسم: ضع اسمًا تعريفياً لموقعك، مثل My First FuelPHP Dev Site.
   • النطاق: اختر نطاق تطوير محلي مثل servbay-fuelphp-test.local. سيقوم ServBay تلقائيًا بإعداد التوجيه لهذا النطاق محليًا.
   • نوع الموقع: اختر PHP.
   • إصدار PHP: حدد الإصدار المناسب (مثلاً 8.3).
   • المجلد الجذري للموقع: عيّن دليل الدخول الرئيسي للمشروع. في FuelPHP هو ملف public/index.php، لذا اجعل المجلد الجذري هو مجلد public داخل المشروع: /Applications/ServBay/www/servbay-fuelphp-app/public.
5. اضغط على زر إضافة لحفظ الإعدادات.

سيقوم ServBay تلقائياً بتحديث ضبط Caddy وإعادة تحميل الخدمة لتفعيل النطاق الجديد.

يمكنك الرجوع إلى دليل ServBay لمزيد من التفاصيل في قسم إضافة أول موقع.

إعداد اتصالات خدمات مشروع FuelPHP

عادة ما يتطلب مشروع FuelPHP إعداد بيانات الاتصال مع قاعدة البيانات وخدمات التخزين المؤقت وغيرها من الخدمات.

إعداد قاعدة البيانات

ضبط قاعدة البيانات يتم من خلال الملف fuel/app/config/development/db.php. عدّل هذا الملف وادخل بيانات اتصالك. في المثال سنفترض استخدام MySQL الافتراضي في ServBay:

<?php
/**
 * إعدادات قاعدة بيانات التطوير. يتم دمجها مع الإعدادات العامة.
 */
return [
    'default' => [
        'connection' => [
            'dsn'      => 'mysql:host=localhost;dbname=fuel_dev', // تأكد من وجود قاعدة بيانات باسم fuel_dev
            'username' => 'root', // اسم مستخدم MySQL الافتراضي في ServBay
            'password' => 'root', // كلمة مرور MySQL الافتراضية في ServBay (للتطوير المحلي فقط!)
        ],
        'identifier' => '`', // مطلوب لمعرّفات MySQL
    ],
];

ملاحظات:

• عليك إنشاء قاعدة بيانات باسم fuel_dev يدويًا عبر أداة إدارة قواعد البيانات مثل phpMyAdmin أو Adminer في ServBay. اسم المستخدم الافتراضي هو root وكلمة مروره root، ويوصى باستخدام ذلك فقط في بيئة التطوير المحلي.
• 'identifier' => ''` ضروري في MySQL لضمان التعامل الصحيح مع أسماء الجداول والحقول.

إعداد التخزين المؤقت (Memcached وRedis)

يدعم FuelPHP عدة أنظمة تخزين مؤقت. قابلية الربط مع كل نظام تتم من خلال ملف fuel/app/config/cache.php. تأكد من أنك فعّلت خدمات Memcached و/أو Redis في ServBay.

إعداد Memcached (fuel/app/config/cache.php):

إذا رغبت بتعيين Memcached كخيار افتراضي للتخزين المؤقت:

<?php
return [
    'driver' => 'memcached', // تعيين السائق الافتراضي إلى memcached
    'memcached' => [
        'cache_id' => 'fuel', // معرف الكاش
        'servers' => [
             'default' => [
                'host'   => '127.0.0.1', // عنوان Memcached الافتراضي
                'port'   => 11211,      // منفذ Memcached الافتراضي
                'weight' => 100,
            ],
        ],
        'compression' => false, // هل التفعيل للضغط
    ],
    // ... إعدادات التخزين المؤقت الأخرى
];

في الغالب، تكون ملحقات Memcached مثبتة مسبقاً مع نسخ PHP في ServBay.

إعداد Redis (fuel/app/config/redis.php):

لاستخدام Redis، قم بتكوين معلومات الاتصال ضمن ملف الإعداد المنفصل redis.php:

<?php
return [
    'default' => [
        'hostname' => '127.0.0.1', // المضيف الافتراضي
        'port'     => 6379,      // المنفذ الافتراضي
        'database' => 0,         // فهرس قاعدة بيانات Redis
    ],
    // يمكن إعداد أكثر من اتصال Redis حسب الحاجة
];

عادة تكون ملحقات Redis مثبتة مسبقًا مع PHP في ServBay.

أمثلة على قواعد البيانات وخدمات التخزين المؤقت

لتوضيح كيفية التفاعل مع قاعدة البيانات وأنظمة التخزين المؤقت في FuelPHP، سنضيف بعض الأمثلة البرمجية.

تحضير جداول قاعدة البيانات (باستخدام Migrations في FuelPHP)

يوفر FuelPHP أداة Oil لإدارة ترحيلات بنية قاعدة البيانات (Migrations)، وهي أسلوب لتتبع التغييرات في جداول قاعدة البيانات.

1. إنشاء ملف ترحيل

   أنشئ ملف ترحيل جديد لتعريف بنية جدول users مستخدمًا أداة Oil من المجلد الرئيسي للمشروع (servbay-fuelphp-app):

   php oil generate migration create_users_table

   سيتم إنشاء ملف ترحيل جديد مع طابع زمني ضمن مجلد fuel/app/migrations.

2. تحرير ملف الترحيل

   افتح ملف الترحيل الذي تم إنشاؤه (fuel/app/migrations/xxxxxxxxxxxx_create_users_table.php)، ثم عدل دالة up() لتعريف الجدول، ودالة down() للتراجع:

   <?php
   namespace Fuel\Migrations;
   
   use Fuel\Core\DBUtil;
   
   class Create_users_table
   {
       public function up()
       {
           // إنشاء جدول users
           DBUtil::create_table('users', [
               'id'          => ['type' => 'int', 'constraint' => 11, 'auto_increment' => true],
               'name'        => ['type' => 'varchar', 'constraint' => 100],
               'email'       => ['type' => 'varchar', 'constraint' => 100, 'unique' => true],
           ], ['id'], true, 'InnoDB', 'utf8mb4_unicode_ci'); // تعيين المفتاح الرئيسي، وتفعيل الفهارس، وتعيين المحرك والترميز
       }
   
       public function down()
       {
           // حذف جدول users (تراجع)
           DBUtil::drop_table('users');
       }
   }

3. تشغيل الترحيل

   من المجلد الرئيسي للمشروع (servbay-fuelphp-app)، استخدم Oil لتطبيق الترحيلات:

   php oil refine migrate

   إذا تمت الأمور بنجاح، سيتم إنشاء جدول users في قاعدة بيانات fuel_dev.

إضافة كود تحكم تجريبي (Controller)

قم بتحرير الملف fuel/app/classes/controller/welcome.php، وأضف إليه بعض الدوال لتوضيح التعامل مع قاعدة البيانات وخدمات الكاش:

<?php
use Fuel\Core\Controller;
use Fuel\Core\Response;
use Fuel\Core\Cache;
use Fuel\Core\DB; // استيراد DB facade
use Fuel\Core\Redis; // استيراد Redis facade

class Controller_Welcome extends Controller
{
    // الإجراء الافتراضي للصفحة الرئيسية
    public function action_index()
    {
        return Response::forge('Hello ServBay!');
    }

    // إجراء مثال Memcached
    public function action_memcached()
    {
        // محاولة جلب البيانات من الكاش
        $value = Cache::get('servbay_memcached_key');

        if ($value === false) {
            // في حال عدم وجود بيانات، يتم تعيينها في الكاش
            $value = 'Hello Memcached from ServBay!';
            Cache::set('servbay_memcached_key', $value, 60); // الكاش لمدة 60 ثانية
            $value .= ' (from cache)';
        } else {
            $value .= ' (cached)';
        }

        return Response::forge($value);
    }

    // إجراء مثال Redis
    public function action_redis()
    {
        // الحصول على مثيل Redis (الاتصال الافتراضي)
        $redis = \Redis_Db::instance(); // في FuelPHP 1.x يستخدم Redis_Db::instance()
        // أو استخدم \Redis_Db::instance('connection_name') في حال تعدد الاتصالات

        // تعيين بيانات في Redis
        $redis->set('servbay_redis_key', 'Hello Redis from ServBay!');

        // جلب البيانات من Redis
        $value = $redis->get('servbay_redis_key');

        return Response::forge($value);
    }

    // إجراء إضافة بيانات إلى MySQL
    public function action_mysql_add()
    {
        try {
            // إضافة سجل جديد في جدول users
            $result = DB::insert('users')->set([
                'name' => 'ServBay Demo User ' . time(), // اسم فريد مع الطابع الزمني
                'email' => 'demo_user_' . time() . '@servbay.test',
            ])->execute(); // ترجع execute() مصفوفة بها رقم السجل الجديد

            return Response::forge('User added with ID: ' . $result[0]);
        } catch (\Database_Exception $e) {
            // التقاط استثناءات قاعدة البيانات مثل تكرار البريد الإلكتروني
            return Response::forge('Error adding user: ' . $e->getMessage(), 500);
        }
    }

    // إجراء قراءة بيانات MySQL
    public function action_mysql()
    {
        // جلب جميع السجلات من جدول users
        $users = DB::select('id', 'name', 'email')->from('users')->execute()->as_array();

        // إرجاع قائمة المستخدمين على شكل JSON
        return Response::forge(json_encode($users, JSON_PRETTY_PRINT));
    }
}

ملاحظات:

• تم استيراد كلًا من DB و Redis لسهولة التعامل معهما مباشرة.
• استخدمت مفاتيح تخزين مؤقت تبدأ بـ servbay_ لتجنب حدوث تصادم مع بيانات أخرى.
• في مثال الإدخال إلى MySQL، تم تضمين الطابع الزمني للتأكد من التفرد ومعالجة الأخطاء بصورة مناسبة.
• في FuelPHP 1.x، يتم استخدام \Redis_Db::instance() للحصول على اتصال Redis.

إعداد التوجيه (Routes)

للسماح بالوصول إلى الدوال السابقة من خلال الروابط، عدّل ملف fuel/app/config/routes.php لإضافة التوجيهات المناسبة. عادة ما يكون هناك توجيه افتراضي لـ Controller_Welcome، لكنك بحاجة لإضافة توجيهات أخرى للطرق الجديدة.

أضف أو عدل المصفوفة الراجعة في هذا الملف كما يلي:

<?php
return array(
    '_root_'  => 'welcome/index',  // التوجيه الافتراضي للصفحة الرئيسية
    '_404_'   => 'welcome/404',    // صفحة الخطأ 404

    // إضافة طرق للإجراءات الجديدة
    'memcached'   => 'welcome/memcached',
    'redis'       => 'welcome/redis',
    'mysql_add'   => 'welcome/mysql_add',
    'mysql'       => 'welcome/mysql',

    // ... إعدادات توجيه أخرى
);

الوصول إلى الموقع واختبار الخدمات

الآن يمكنك زيارة النطاق الذي أعددته في ServBay، مثلاً https://servbay-fuelphp-test.local لتجربة مشروع FuelPHP والتأكد من نجاح الاتصال بالخدمات الداعمة.

• زيارة الصفحة الرئيسية: https://servbay-fuelphp-test.local
  • الناتج المتوقع: Hello ServBay!
• اختبار Memcached: https://servbay-fuelphp-test.local/memcached
  • أول زيارة: Hello Memcached from ServBay! (from cache) (مع عمل خدمة الكاش)
  • زيارات لاحقة: Hello Memcached from ServBay! (cached) (طالما أن الكاش لا يزال فعالاً)
• اختبار Redis: https://servbay-fuelphp-test.local/redis
  • الناتج المتوقع: Hello Redis from ServBay! (مع عمل خدمة Redis)
• إضافة مستخدم إلى MySQL: https://servbay-fuelphp-test.local/mysql_add
  • الناتج المتوقع: User added with ID: [رقم السجل الجديد] (مع توفر قاعدة البيانات والجدول)
• عرض قائمة مستخدمي MySQL: https://servbay-fuelphp-test.local/mysql
  • الناتج المتوقع: مصفوفة JSON تضم جميع سجلات جدول users (مع توفر بيانات)

حول HTTPS: يقوم ServBay افتراضياً بتوليد شهادة SSL للمواقع المحلية وربطها مع ServBay User CA أو ServBay Public CA. إذا تلقيت تحذيراً في المتصفح عن الشهادة، تأكد من أنك وثقت شهادة CA الخاصة بـ ServBay في النظام.

ملاحظات هامة

• تأكد دائماً من عمل جميع الخدمات الأساسية من واجهة ServBay (مثل PHP، خادم الويب، MySQL، Redis، Memcached) للإصدار المرغوب قبل بدء الاختبار.
• تذكر إنشاء قاعدة بيانات fuel_dev يدوياً عبر أداة إدارة القواعد أو استخدم اسماً بقاعدة بيانات موجودة في ملف db.php. أداة الترحيلات في FuelPHP (oil refine migrate) تقوم بإنشاء الجدول المطلوب فقط.
• ملف الدخول الرئيسي لـ FuelPHP هو public/index.php؛ لذا عند إعداد الموقع على ServBay، تأكد من تعيين المجلد الجذري على هذا المسار الفرعي تحديدًا.

الخلاصة

يتيح لك ServBay إعداد بيئة تطوير متكاملة لمشروع FuelPHP على macOS بسهولة وسرعة. وضّحنا في هذا الدليل خطوات إنشاء مشروع جديد، وضبط ميزة المواقع في ServBay، وربط الخدمات المساندة مثل قاعدة البيانات وأنظمة الكاش، مع أمثلة برمجية عملية لاختبار التكامل. بفضل الخدمات المسبقة والإعداد السلس في ServBay، سيتضاعف إنتاجك وسرعة التطوير لديك.

نتمنى أن يساعدك هذا الدليل في بدء رحلتك مع FuelPHP على ServBay بكل ثقة واحترافية!