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

ما هو FuelPHP؟

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

ميزات وفوائد FuelPHP الرئيسية

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

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

بناء بيئة تطوير FuelPHP باستخدام ServBay

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

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

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

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

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

إنشاء مشروع FuelPHP

مسار حفظ المشروع المقترح

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

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

   افتح تطبيق الطرفية، وانتقل إلى مسار المواقع الإلكترونية المقترح في ServBay:

   cd /Applications/ServBay/www

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

   أنشئ مجلد جديد لمشروع FuelPHP الخاص بك وادخل إليه:

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

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

   في مجلد المشروع، استخدم Composer لتحميل وتثبيت إطار FuelPHP. تشير النقطة . إلى التثبيت في المجلد الحالي:

   composer create-project fuel/fuel .

   سيقوم Composer تلقائياً بتحميل إطار FuelPHP وتبعياته في مجلد servbay-fuelphp-app.

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

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

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

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

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

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

عادة ما يحتاج مشروع 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 بواسطة أداة إدارة قواعد البيانات في ServBay مثل phpMyAdmin أو Adminer. اسم المستخدم الافتراضي هو 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', // عنوان الاستماع الافتراضي لـ Redis
        'port'     => 6379,      // المنفذ الافتراضي لـ Redis
        'database' => 0,         // رقم قاعدة بيانات Redis
    ],
    // يمكنك إعداد أكثر من اتصال Redis هنا
];

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

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

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

تجهيز الجدول في قاعدة البيانات (باستخدام نظام الهجرات في FuelPHP)

يقدم FuelPHP أداة Oil لإدارة الهجرات، وهي طريقة للتحكم في هيكل قاعدة البيانات بشكل إصدارات.

1. إنشاء ملف هجرة

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

   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)، قم بتشغيل الهجرة لإنشاء الجدول بقاعدة البيانات:

   php oil refine migrate

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

إضافة كود تحكمات توضيحي

قم بتحرير الملف fuel/app/classes/controller/welcome.php وأضف الطرق التالية لعرض العمليات على القاعدة والتخزين المؤقت:

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

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 (use Fuel\Core\DB;, use Fuel\Core\Redis;) للاستخدام المباشر.
• استخدمت المفاتيح الخاصة بـ Memcached وRedis بادئة servbay_ لتجنب التعارض.
• مثال الإدخال لـ MySQL يستخدم الطابع الزمني لضمان التفرد مع معالجة الأخطاء بطريقة معقولة وكتابة واضحة للتجارب العملية.
• في FuelPHP 1.x يستخدم \Redis_Db::instance() للحصول على نسخة Redis.

ضبط المسارات

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

في ملف fuel/app/config/routes.php عدل أو أضف ما يلي:

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

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

    // ... إعدادات مسارات أخرى
);

اختبار الموقع والتأكد من عمل الخدمات

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

• زيارة الصفحة الرئيسية: 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! (عند عمل الخدمة بشكل صحيح)
• إضافة مستخدم إلى MySQL: https://servbay-fuelphp-test.local/mysql_add
  • النتيجة المتوقعة: User added with ID: [رقم السجل الجديد] (عند عمل قاعدة البيانات والجدول بشكل صحيح)
• جلب قائمة المستخدمين من MySQL: https://servbay-fuelphp-test.local/mysql
  • النتيجة المتوقعة: مصفوفة JSON تتضمن جميع سجلات جدول users (عند وجود بيانات)

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

ملاحظات مهمة

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

الخلاصة

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

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