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

سيوضح لك هذا المقال كيفية إنشاء وتكوين وتشغيل مشروع PHP مبني على إطار عمل Slim باستخدام بيئة تطوير ServBay المحلية والقوية. ServBay يوفر تكاملاً بين PHP وخوادم الويب (Caddy/Nginx/Apache) وأنواع متعددة من قواعد البيانات، مما يجعله منصة مثالية لتطوير تطبيقات Slim.

ما هو Slim؟

Slim هو إطار عمل PHP خفيف الوزن (Microframework) يهدف لتوفير طريقة سريعة لبناء تطبيقات ويب وواجهات API بسيطة وفعّالة. يمنحك ميزات التوجيه، معالجة الطلبات والاستجابة، ويعد أساسًا ممتازًا لبناء التطبيقات المعقدة أو المشاريع ذات الإطلاق السريع.

أهم ميزات Slim وفوائده

• خفة الوزن: مكتبة Slim الأساسية صغيرة جدًا وتستهلك موارد قليلة وتوفر سرعة بدء عالية، وهي مثالية للتطبيقات الصغيرة والمتوسطة أو خدمات مصغرة (microservices).
• مرونة: تم تصميم Slim ليكون قابلاً للتوسيع ويمكن دمجه مع أي مكون أو مكتبة خارجية (مثل محركات القوالب، ORM، مكتبات المصادقة)، مما يمنحك حرية اختيار الأدوات الأنسب لمتطلبات مشروعك.
• سهولة الاستخدام: بفضل واجهته البرمجية البسيطة وتوثيقه الواضح، يستطيع المطوّرون استيعاب مفاهيمه الأساسية والانطلاق بسرعة في التطوير.
• توجيه قوي: يدعم مجموعة واسعة من طرق HTTP (GET, POST, PUT, DELETE) وإعدادات توجيه متقدمة مثل مجموعات التوجيه (routing groups)، الوسطاء (middleware) والالتقاط الذكي للمعاملات.
• دعم الوسيط البرمجي: تسمح طبقة الوسيط في Slim بتنفيذ مهام مثل التحقق من الهوية أو تسجيل الأحداث أو معالجة CORS سواء قبل الوصول إلى منطق التطبيق أو قبل إرسال الاستجابة إلى العميل.

Slim هو الخيار المثالي لتطوير واجهات RESTful API، بناء نماذج أولية سريعة، أو تنفيذ وظائف مستقلة محددة.

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

سيشرح هذا الدليل كيفية الاستفادة من بيئة PHP المعدة مسبقًا في ServBay وميزة المواقع لإعداد خادم ويب، مع خطوات لتكوين وصول سريع لمشروع Slim خاصتك.

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

قبل البدء، تأكد من تجهيز ما يلي:

1. تنصيب وتشغيل ServBay: تأكد أن ServBay مثبت بنجاح على نظام macOS أو Windows الخاص بك وأن التطبيق يعمل.
2. Composer متكامل مع ServBay: لا حاجة لتنصيب Composer منفصل، فهو مضمن افتراضيًا في ServBay.

إنشاء مشروع Slim

ينصح فريق ServBay بوضع جميع مشاريع المواقع ضمن المسارات التالية لسهولة إدارة وتكوين المشاريع:

• macOS: /Applications/ServBay/www
• Windows: C:\ServBay\www

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

   macOS:

   cd /Applications/ServBay/www

   Windows:

   cd C:\ServBay\www

2. أنشئ دليل المشروع: قم بإنشاء مجلد جديد لمشروع Slim.

   mkdir servbay-slim-app

3. ادخل على مجلد المشروع:

   cd servbay-slim-app

4. قم بتنصيب Slim باستخدام Composer: من داخل مجلد المشروع، قم بتنصيب إطار عمل Slim ومكوّن psr7.

   composer require slim/slim "^4.0" slim/psr7 -W

   ينفذ هذا الأمر تنزيل مكتبة Slim ومكتبة slim/psr7 إلى مجلد vendor، ويُنشئ ملفات composer.json وcomposer.lock.

تهيئة تطبيق Slim

1. أنشئ ملف الدخول الرئيسي: تعتمد تطبيقات Slim عادةً على ملف دخول واحد (public/index.php) لمعالجة جميع الطلبات. أنشئ مجلد public في جذر المشروع وضع بداخله ملف index.php.

   mkdir public
   touch public/index.php

2. حرر ملف الدخول: افتح public/index.php وأضف الكود الأولي التالي:

   <?php
   // تحميل ملف autoload الخاص بـ Composer
   require __DIR__ . '/../vendor/autoload.php';
   
   // استيراد واجهات PSR-7 وFactory الخاصة بـ Slim
   use Psr\Http\Message\ResponseInterface as Response;
   use Psr\Http\Message\ServerRequestInterface as Request;
   use Slim\Factory\AppFactory;
   
   // إنشاء نسخة من تطبيق Slim
   $app = AppFactory::create();
   
   // إضافة مسار أساسي للتعامل مع طلب GET إلى المسار '/'
   $app->get('/', function (Request $request, Response $response, $args) {
       // كتابة محتوى في جسم الاستجابة
       $response->getBody()->write("Hello ServBay!");
       // إعادة كائن الاستجابة
       return $response;
   });
   
   // تشغيل تطبيق Slim
   $app->run();

   يقوم هذا الكود بضبط تطبيق Slim بسيط يستجيب لمسار الجذر (/) ويعيد نص "Hello ServBay!".

إعداد الموقع في ServBay

لكي تستطيع تصفّح مشروع Slim من خلال المتصفح، عليك تكوين موقع جديد في ServBay (يطلق عليه "Host" في الإصدارات القديمة).

1. افتح واجهة تطبيق ServBay.
2. انتقل إلى قسم المواقع (Websites).
3. اضغط لإضافة موقع جديد.
4. أدخل إعدادات موقعك بناءً على المعلومات التالية:

   • الاسم (Name): My First Slim Dev Site (أو أي اسم تفضله)

   • النطاق (Domain): servbay-slim-test.local (يفضّل استخدام النهاية .local أو .test لتطوير محلي)

   • نوع الموقع (Website Type): PHP

   • إصدار PHP (PHP Version): اختر الإصدار المطلوب، مثل 8.3.

   • جذر الموقع (Document Root): من خلال زر التصفح، اختر مجلد public من مشروعك:

     • macOS: /Applications/ServBay/www/servbay-slim-app/public
     • Windows: C:\ServBay\www\servbay-slim-app\public

     لأن ملف الدخول الخاص بـ Slim (index.php) يوجد في مجلد public ويجب على الخادم توجيه الطلبات إلى هذا المجلد.

5. اضغط حفظ ليتم تحديث إعدادات الخادم تلقائيًا.

للمزيد حول إعداد الموقع في ServBay، راجع إضافة أول موقع.

الوصول إلى موقع Slim الخاص بك

بعد انتهاء التكوين، افتح متصفح الإنترنت وادخل النطاق الذي اخترته مثل https://servbay-slim-test.local.

إذا تم كل شيء بنجاح، سترى عبارة Hello ServBay! على الصفحة. يوضح ذلك أن تطبيق Slim يعمل فعليًا على خادم ServBay المحلي.

أمثلة التكامل مع قواعد البيانات

لا يتضمن Slim بنفسه طبقة تجريد قواعد البيانات، لكن من السهل دمج العديد من حزم قواعد البيانات الخاصة بـ PHP. سنستخدم كمثال ORM الخاص بـ Laravel (عن طريق مكون illuminate/database) للاتصال بـ MySQL وPostgreSQL، وسنقدم أيضًا أمثلة لتكامل Memcached وRedis.

المتطلبات الأولية: إنشاء قاعدة بيانات وتنفيذ الهجرة

قبل دمج قاعدة البيانات، تحتاج أولاً إلى إنشاء قاعدة بيانات مناسبة في ServBay، ثم إنشاء جداول المشروع عبر أداة الهجرة.

1. أنشئ قاعدة بيانات:
   • افتح تطبيق ServBay وانتقل إلى الحزمة الخاصة بقاعدة البيانات التي ستستخدمها (مثل MySQL أو PostgreSQL).
   • أنشئ قاعدة بيانات جديدة باستخدام أدوات ServBay (مثل phpMyAdmin لـ MySQL/MariaDB أو pgAdmin لـ PostgreSQL)، أو عبر الطرفية، مثلاً باسم servbay_slim_app.
   • كلمة مرور مستخدم root الافتراضية عادة هي password، ويمكنك مراجعتها أو تعديلها من واجهة ServBay.
2. تنصيب وتكوين Phinx (أداة الهجرة): Phinx أداة شهيرة للهجرة في PHP وتساعدك في إدارة نسخ جداول قاعدة البيانات.
   • من جذر مشروع Slim، ثبت Phinx باستخدام Composer:
     • macOS: /Applications/ServBay/www/servbay-slim-app
     • Windows: C:\ServBay\www\servbay-slim-app

     composer require robmorgan/phinx

   • ابدأ ملف إعدادات Phinx:

     vendor/bin/phinx init

     سينشئ ذلك ملف phinx.yml في جذر المشروع. حرره وأدخل إعدادات الاتصال الخاصة بقاعدة البيانات مثل:

     paths:
         migrations: '%%PHINX_CONFIG_DIR%%/db/migrations'
         seeds: '%%PHINX_CONFIG_DIR%%/db/seeds'
     
     environments:
         default_migration_table: phinxlog
         default_environment: development # أو اسم البيئة التي تستخدمها
     
         development: # حسب نوع قاعدة البيانات
             adapter: mysql # أو pgsql
             host: 127.0.0.1
             name: servbay_slim_app # اسم القاعدة الذي أنشأته
             user: root
             pass: password # كلمة مرور قاعدة البيانات
             port: 3306 # لمن يستخدم MySQL، و5432 لـ PostgreSQL
             charset: utf8mb4 # يُنصح بها لـ MySQL
             collation: utf8mb4_unicode_ci # يُنصح بها لـ MySQL
     
     version_order: creation

3. أنشئ ملف الهجرة: أنشئ ملف هجرة جديد من خلال أمر Phinx.

   vendor/bin/phinx create CreateUsersTable

   سينشئ ذلك ملف PHP جديد ضمن مجلد db/migrations. افتحه وعدل دالة change() لتعريف جدول users:

   <?php
   
   declare(strict_types=1);
   
   use Phinx\Migration\AbstractMigration;
   
   final class CreateUsersTable extends AbstractMigration
   {
       /**
        * Change Method.
        *
        * Write your reversible migrations using this method.
        *
        * More information on writing migrations is available here:
        * https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
        *
        * تذكير: استخدم 'create()' أو 'update()' ولا تستخدم 'save()' عند العمل
        * مع فئة الجداول.
        */
       public function change(): void
       {
           $table = $this->table('users');
           $table->addColumn('name', 'string')
                 ->addColumn('email', 'string', ['unique' => true])
                 ->addTimestamps() // إضافة حقول created_at و updated_at
                 ->create();
       }
   }

4. نفّذ الهجرة: من جذر المشروع، شغّل أمر Phinx لتنفيذ الهجرة وإنشاء جدول users.

   vendor/bin/phinx migrate

   هام: يجب الانتهاء من إنشاء قاعدة البيانات وتشغيل الهجرة قبل تجربة أكواد قاعدة البيانات التالية.

استخدام مكوّن illuminate/database

سنستخدم مكوّن قاعدة البيانات من Laravel (illuminate/database) كـ ORM ومنشئ استعلامات.

1. تنصيب illuminate/database: من جذر المشروع، ثبّت الحزمة المطلوبة:

   • macOS: /Applications/ServBay/www/servbay-slim-app
   • Windows: C:\ServBay\www\servbay-slim-app

   composer require illuminate/database

2. تهيئة الاتصال بقاعدة البيانات ضمن public/index.php: بعد سطر require __DIR__ . '/../vendor/autoload.php'; وقبل إنشاء التطبيق ($app = AppFactory::create();`)، أضف التالي:

   // ... بقية أسطر require و use ...
   
   use Illuminate\Database\Capsule\Manager as Capsule; // استيراد مدير الكبسولة
   
   // تهيئة Eloquent ORM
   $capsule = new Capsule;
   
   // إضافة إعدادات الاتصال بقاعدة البيانات (عدل type والقيم الأخرى حسب نوع القاعدة)
   $capsule->addConnection([
       'driver' => 'mysql', // أو 'pgsql'
       'host' => '127.0.0.1',
       'database' => 'servbay_slim_app', // اسم القاعدة
       'username' => 'root', // اسم المستخدم
       'password' => 'password', // كلمة المرور
       'charset' => 'utf8mb4', // لمستخدمي MySQL
       'collation' => 'utf8mb4_unicode_ci', // لمستخدمي MySQL
       'prefix' => '',
       // لـ PostgreSQL: أضف خاصية schema
       // 'schema' => 'public',
   ]);
   
   // تفعيل الوصول العالمي
   $capsule->setAsGlobal();
   
   // تشغيل Eloquent
   $capsule->bootEloquent();
   
   // ... إنشاء تطبيق Slim ...

مثال MySQL

بافتراض تشغيل حزمة MySQL في ServBay، وإنشاء قاعدة البيانات servbay_slim_app وتنفيذ هجرة جدول users بنجاح.

في ملف public/index.php، وقبل $app->run(); أضف المسارات التالية:

// ... تهيئة سابقة و مسار '/'

use Illuminate\Database\Capsule\Manager as Capsule; // تأكد من الاستيراد

// مسار لإضافة مستخدم جديد
$app->get('/mysql-add-user', function (Request $request, Response $response, $args) {
    try {
        Capsule::table('users')->insert([
            'name' => 'ServBay Demo User',
            'email' => 'servbay-demo-' . time() . '@servbay.test', // لضمان أن البريد الإلكتروني فريد
            'created_at' => date('Y-m-d H:i:s'),
            'updated_at' => date('Y-m-d H:i:s'),
        ]);
        $response->getBody()->write('User added to MySQL');
    } catch (\Exception $e) {
        $response->getBody()->write('Error adding user: ' . $e->getMessage());
        $response = $response->withStatus(500); // كود خطأ
    }
    return $response;
});

// مسار لجلب جميع المستخدمين
$app->get('/mysql-get-users', function (Request $request, Response $response, $args) {
    try {
        $users = Capsule::table('users')->get();
        $response->getBody()->write($users->toJson()); // إخراج البيانات بصيغة JSON
        $response = $response->withHeader('Content-Type', 'application/json');
    } catch (\Exception $e) {
         $response->getBody()->write('Error fetching users: ' . $e->getMessage());
         $response = $response->withStatus(500);
    }
    return $response;
});

// ... $app->run();

الوصول:

• زيارة https://servbay-slim-test.local/mysql-add-user تضيف مستخدم جديد إلى الجدول.
• زيارة https://servbay-slim-test.local/mysql-get-users تعرض جميع المستخدمين بصيغة JSON.

مثال PostgreSQL

بافتراض أنك شغّلت حزمة PostgreSQL، وأنشأت قاعدة بيانات servbay_slim_app ونفذت هجرة جدول users (تأكد من ضبط adapter على pgsql وport على 5432 في ملف Phinx).

عدّل إعدادات الاتصال في public/index.php لتكون كما يلي:

$capsule->addConnection([
    'driver' => 'pgsql', // استخدم pgsql
    'host' => '127.0.0.1',
    'database' => 'servbay_slim_app',
    'username' => 'root',
    'password' => 'password',
    'charset' => 'utf8',
    'prefix' => '',
    'schema' => 'public', // مطلوب لـ PostgreSQL
]);
// ... إعدادات Eloquent الأخرى كما هي ...

وأضف المسارات التالية قبل $app->run();:

// ... إعدادات مسبقة ومسارات أخرى ...

use Illuminate\Database\Capsule\Manager as Capsule; // تأكد من الاستيراد

// مسار لإضافة مستخدم في PostgreSQL
$app->get('/pgsql-add-user', function (Request $request, Response $response, $args) {
    try {
        Capsule::table('users')->insert([
            'name' => 'ServBay PG Demo User',
            'email' => 'servbay-pg-demo-' . time() . '@servbay.test',
            'created_at' => date('Y-m-d H:i:s'),
            'updated_at' => date('Y-m-d H:i:s'),
        ]);
        $response->getBody()->write('User added to PostgreSQL');
    } catch (\Exception $e) {
        $response->getBody()->write('Error adding user: ' . $e->getMessage());
        $response = $response->withStatus(500);
    }
    return $response;
});

// مسار لجلب جميع المستخدمين في PostgreSQL
$app->get('/pgsql-get-users', function (Request $request, Response $response, $args) {
    try {
        $users = Capsule::table('users')->get();
        $response->getBody()->write($users->toJson());
        $response = $response->withHeader('Content-Type', 'application/json');
    } catch (\Exception $e) {
         $response->getBody()->write('Error fetching users: ' . $e->getMessage());
         $response = $response->withStatus(500);
    }
    return $response;
});

// ... $app->run();

الوصول:

• زيارة https://servbay-slim-test.local/pgsql-add-user تضيف مستخدم جديد في الجدول الخاص بـ PostgreSQL.
• زيارة https://servbay-slim-test.local/pgsql-get-users تعرض جميع المستخدمين بصيغة JSON.

مثال Memcached

يوفر ServBay حزمة Memcached وامتداد PHP الخاص بها (ext-memcached). يبقى عليك فقط تنصيب مكتبة عميل PHP للتعامل مع Memcached. سنستخدم المكتبة memcached/memcached.

1. تنصيب مكتبة Memcached: من جذر المشروع، ثبّت المكتبة:

   • macOS: /Applications/ServBay/www/servbay-slim-app
   • Windows: C:\ServBay\www\servbay-slim-app

   composer require memcached/memcached

2. أضف مسار Memcached في public/index.php: قبل $app->run(); أضف التالي:

   // ... إعدادات مسبقة ومسارات أخرى ...
   
   // مسار اختبار Memcached
   $app->get('/memcached-example', function (Request $request, Response $response, $args) {
       // إنشاء عميل Memcached
       $memcached = new Memcached();
       // إضافة الخادم (ServBay يعمل افتراضياً على 127.0.0.1:11211)
       $memcached->addServer('127.0.0.1', 11211);
   
       $cacheKey = 'my_servbay_cache_key';
       // محاولة جلب بيانات من الكاش
       $cachedData = $memcached->get($cacheKey);
   
       if ($cachedData === false) {
           // لو لم يكن هناك بيانات، أنشئ بيانات واكتبها في الكاش
           $cachedData = 'Hello Memcached from ServBay! This was not cached.';
           // حفظ البيانات بالكاش مع صلاحية 60 ثانية
           $memcached->set($cacheKey, $cachedData, 60);
           $response->getBody()->write($cachedData);
       } else {
           // إذا البيانات موجودة بالكاش
           $response->getBody()->write('Hello Memcached from ServBay! This was served from cache.');
       }
   
       return $response;
   });
   
   // ... $app->run();

الوصول: زيارة https://servbay-slim-test.local/memcached-example. أول زيارة ستظهر "This was not cached."، والزيارات التالية (قبل انتهاء صلاحية الكاش) ستظهر "This was served from cache."

مثال Redis

يوفر ServBay حزمة Redis وامتداد PHP الخاص بها (ext-redis). يبقى عليك فقط تنصيب مكتبة عميل PHP ملائمة. سنستخدم مكتبة predis/predis.

1. تنصيب مكتبة Redis: من جذر المشروع، ثبّت المكتبة:

   • macOS: /Applications/ServBay/www/servbay-slim-app
   • Windows: C:\ServBay\www\servbay-slim-app

   composer require predis/predis

2. أضف مسار Redis في public/index.php: قبل $app->run(); أضف التالي:

   // ... إعدادات مسبقة ومسارات أخرى ...
   // ... مسار Memcached إذا احتجت ...
   
   use Predis\Client as RedisClient; // استيراد فئة العميل
   
   // مسار اختبار Redis
   $app->get('/redis-example', function (Request $request, Response $response, $args) {
       try {
           // إنشاء عميل Redis (ServBay يعمل افتراضياً على 127.0.0.1:6379)
           $redis = new RedisClient([
               'scheme' => 'tcp',
               'host' => '127.0.0.1',
               'port' => 6379,
           ]);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           // محاولة جلب بيانات من الكاش
           $cachedData = $redis->get($cacheKey);
   
           if ($cachedData === null) {
               // لو لم تكن هناك بيانات في الكاش
               $cachedData = 'Hello Redis from ServBay! This was not cached.';
               // حفظ البيانات مع صلاحية 60 ثانية
               $redis->setex($cacheKey, 60, $cachedData); // SETEX key seconds value
               $response->getBody()->write($cachedData);
           } else {
               // إذا تم إيجاد البيانات في الكاش
               $response->getBody()->write('Hello Redis from ServBay! This was served from cache.');
           }
       } catch (\Exception $e) {
           // التقاط أي أخطاء متعلقة بالاتصال أو العمليات
           $response->getBody()->write('Error connecting to Redis or performing operation: ' . $e->getMessage());
           $response = $response->withStatus(500);
       }
   
       return $response;
   });
   
   // ... $app->run();

الوصول: زيارة https://servbay-slim-test.local/redis-example. أول زيارة ستعرض "This was not cached."، والزيارات اللاحقة (قبل انتهاء وقت الكاش) ستعرض "This was served from cache."

الخلاصة

من خلال الخطوات السابقة، أصبحت قادرًا على إنشاء مشروع Slim Framework وتشغيله ضمن بيئة ServBay المحلية، وتكوين خيار المواقع لاستضافته والوصول إليه عبر المتصفح. بالإضافة إلى ذلك، تعلمت كيفية دمج حزم قواعد البيانات (MySQL, PostgreSQL, Memcached, Redis) وتوسيعات PHP اللازمة لاستغلال الإمكانيات الكاملة في تطبيقك. تسهّل ServBay عملية إعداد وإدارة البيئة المحلية، حتى تركز أكثر على تطوير تطبيقك مع Slim.