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

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

ما هو Slim؟

Slim هو إطار عمل PHP خفيف الوزن يُصنّف كإطار مصغر (microframework)، صُمم لتسهيل إنشاء تطبيقات الويب وواجهات البرمجة (APIs) بسرعة وسهولة، مع تقديم خصائص أساسية مثل التوجيه (routing) ومعالجة الطلبات والاستجابات. وهو مناسب جدًا للمشاريع التي تتطلب تطويرًا سريعًا ونشرًا مرنًا أو يُعتمد عليه كقاعدة لبناء تطبيقات أكبر وأكثر تعقيدًا.

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

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

يُعد Slim خيارًا مثاليًا لبناء واجهات RESTful وإنشاء النماذج الأولية بسرعة أو إدارة وظائف خاصة ومستقلة.

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

في هذا الدليل، سنستفيد من بيئة PHP المعدة مسبقًا ضمن ServBay وميزة "المواقع" (Websites) لإعداد خادم الويب وتفعيل الوصول إلى مشروع Slim عبر بعض الإعدادات البسيطة.

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

قبل البدء، تأكد من إتمام الآتي:

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

إنشاء مشروع Slim

توصي ServBay بجمع مشاريع المواقع ضمن المسار /Applications/ServBay/www لتسهيل إدارتها.

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

   cd /Applications/ServBay/www

2. أنشئ مجلدًا جديدًا للمشروع:

   mkdir servbay-slim-app

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

   cd servbay-slim-app

4. استخدم Composer لتثبيت Slim:

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

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

تهيئة تطبيق Slim

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

   mkdir public
   touch public/index.php

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

   <?php
   // تحميل autoload من Composer
   require __DIR__ . '/../vendor/autoload.php';
   
   // استيراد واجهات PSR-7 ومصنع 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

حتى تتمكن من الوصول إلى مشروعك من المتصفح، يجب عليك إضافة "موقع" جديد عن طريق ServBay (أو "مضيف" في الإصدارات القديمة).

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

للحصول على خطوات مفصلة، راجع إضافة أول موقع ويب.

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

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

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

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

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

المتطلبات: إنشاء قواعد البيانات وتشغيل الهجرات

قبل دمج قاعدة البيانات، عليك إنشاء قاعدة بيانات مناسبة والهيكل اللازم للجداول.

1. إنشاء قاعدة بيانات جديدة:
   • افتح تطبيق ServBay واختر الحزمة المناسبة (مثل MySQL أو PostgreSQL).
   • استخدم أدوات الإدارة المضمّنة (phpMyAdmin لـ MySQL/MariaDB أو pgAdmin لـ PostgreSQL) أو الطرفية لإنشاء قاعدة بيانات وليكن الاسم servbay_slim_app.
   • غالبًا كلمة مرور مستخدم root هي password (يمكن مراجعتها أو تعديلها من واجهة ServBay).
2. تثبيت وتهيئة أداة Phinx للهجرات: أداة شهيرة لإدارة وإصدار التحويلات (migrations) لهيكلة قاعدة البيانات.
   • ثبّت Phinx في مجلد مشروعك:

     composer require robmorgan/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  # أو 5432 لـ PostgreSQL
             charset: utf8mb4
             collation: utf8mb4_unicode_ci
     
     version_order: creation

3. إنشاء ملف هجرة: استخدم Phinx لإضافة هجرة جديدة.

   vendor/bin/phinx create CreateUsersTable

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

   <?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
        *
        * Remember to call "create()" or "update()" and NOT "save()" when working
        * with the Table class.
        */
       public function change(): void
       {
           $table = $this->table('users');
           $table->addColumn('name', 'string')
                 ->addColumn('email', 'string', ['unique' => true])
                 ->addTimestamps() // يضيف created_at و updated_at تلقائياً
                 ->create();
       }
   }

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

   vendor/bin/phinx migrate

   ملاحظة هامة: لابد من إتمام إعداد قاعدة البيانات وتشغيل الهجرة قبل تطبيق أمثلة الكود لاحقًا.

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

سنستخدم مكون illuminate/database (نفس قاعدة ORM لارافيل) لتشغيل الاستعلامات وربط قاعدة البيانات.

1. تثبيت illuminate/database:

   composer require illuminate/database

2. تهيئة الاتصال في public/index.php: أضف الكود التالي بعد تحميل autoload من Composer وقبل تهيئة Slim:

   // ... بقية require و use ...
   
   use Illuminate\Database\Capsule\Manager as Capsule;
   
   // إعداد الارتباط بقاعدة البيانات (حدد driver حسب قاعدة البيانات)
   $capsule = new Capsule;
   
   $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',
       'prefix' => '',
       // مع PostgreSQL استعمل:
       // 'schema' => 'public',
   ]);
   
   $capsule->setAsGlobal();
   $capsule->bootEloquent();
   
   // ... إنشاء تطبيق Slim ($app = AppFactory::create();)

مثال 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 وإنشاء قاعدة المستخدمين:

عدل إعدادات الاتصال في public/index.php واعتمد معطيات PostgreSQL:

$capsule->addConnection([
    'driver' => 'pgsql',
    'host' => '127.0.0.1',
    'database' => 'servbay_slim_app',
    'username' => 'root',
    'password' => 'password',
    'charset' => 'utf8',
    'prefix' => '',
    'schema' => 'public',
]);
// ... بقية التهيئة كما هي ...

ثم أضف التوجيهات التالية:

// ... التهيئة والتوجيهات السابقة ...

use Illuminate\Database\Capsule\Manager as Capsule;

// إضافة مستخدم جديد
$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;
});

// جلب المستخدمين
$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 لإضافة مستخدم.
• https://servbay-slim-test.local/pgsql-get-users لجلب المستخدمين وعرضهم.

مثال Memcached

يقدم ServBay حزمة Memcached وامتداد PHP لهذه الخدمة؛ ستحتاج فقط لتثبيت مكتبة عميل PHP (سنستخدم memcached/memcached).

1. تثبيت المكتبة:

   composer require memcached/memcached

2. أضف مسار Memcached في public/index.php:

   // ... التهيئة وروابط قواعد البيانات...
   
   // مثال استخدام Memcached
   $app->get('/memcached-example', function (Request $request, Response $response, $args) {
       $memcached = new Memcached();
       $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.';
           $memcached->set($cacheKey, $cachedData, 60); // TTL 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 لها. سنحتاج لتثبيت عميل Predis:

1. تثبيت العميل:

   composer require predis/predis

2. أضف مسار Redis في public/index.php:

   // ... التهيئة والمسارات الأخرى ...
   
   use Predis\Client as RedisClient;
   
   // مثال استخدام Redis
   $app->get('/redis-example', function (Request $request, Response $response, $args) {
       try {
           $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.';
               $redis->setex($cacheKey, 60, $cachedData);
               $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 في مشروعك باستخدام الامتدادات والأدوات المناسبة. يوفر ServBay بيئة فعالة لإدارة وتطوير تطبيقات Slim على جهازك، لتتمكن من التركيز على منطق التطبيق دون العناء في إعداد الخوادم اليدوي.