إنشاء وتشغيل مشروع PHPixie على macOS بواسطة ServBay

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

الميزات والمزايا الرئيسية لـ PHPixie

• خفة الوزن: يأتي نظام PHPixie الأساسي بأقل المكونات الضرورية فقط، مما يمنحه سرعة عالية في الإقلاع والتشغيل.
• أداء عالي: تصميم الإطار يركز على الفعالية ويمكنه التعامل بكفاءة مع الطلبات المتزامنة، مما يجعله مناسبًا للتطبيقات التي تتطلب أداءً قويًا.
• سهل التعلم: يوفر واجهات برمجية واضحة وتوثيقًا مفصلاً، ما يتيح للمطورين فهم الإطار والعمل به بسرعة نسبية.
• مرونة: يتمتع هيكل الإطار بترابط منخفض، مما يمنح المطور حرية اختيار ودمج المكتبات والمكونات الخارجية بحسب احتياجات المشروع.
• دعم مجتمعي نشط: يتمتع PHPixie بمجتمع مطورين نشط يقدم إضافات وموارد دعم متنوعة.

يساعد PHPixie المطورين على بناء تطبيقات ويب قوية وعالية الجودة بكفاءة، بدءًا من المشاريع الصغيرة وحتى التطبيقات المؤسسية الكبيرة.

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

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

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

• يجب أن يكون ServBay مثبتًا ويعمل على macOS. يدمج ServBay PHP وComposer وقواعد بيانات متعددة (MySQL، PostgreSQL، MongoDB، Redis وغيرها) بالإضافة إلى خادم Caddy.
• معرفة أساسيات التعامل مع سطر الأوامر.

إنشاء مشروع PHPixie

المسار الموصى به لمشاريع المواقع

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

1. التأكد من توفر Composer: يأتي ServBay مزودًا بـ Composer مدمج مسبقًا، لذا لا يلزم تثبيته. افتح الطرفية وادخل الأمر composer --version للتحقق.
2. إنشاء مجلد المشروع: أنشئ مجلدًا جديدًا ضمن المسار الأساسي المقترح لحفظ مشروع PHPixie وادخل إليه:

   cd /Applications/ServBay/www
   mkdir servbay-phpixie-app
   cd servbay-phpixie-app

3. إنشاء مشروع PHPixie عبر Composer: استخدم Composer لسحب قالب مشروع PHPixie في مجلد المشروع:

   composer create-project phpixie/project .

   سيقوم Composer بتنزيل PHPixie ومتطلباته للمجلد الحالي.

إعداد خادم الويب

استخدم ميزة المواقع في ServBay لإعداد خادم Caddy وتوجيهه بشكل صحيح إلى مشروع PHPixie الخاص بك.

1. افتح واجهة تطبيق ServBay.

2. انتقل إلى قائمة المواقع (Websites).

3. اضغط لإضافة موقع جديد.

4. أدخل معلومات الموقع:

   • الاسم: مثلًا My First PHPixie Dev Site (للتعريف الداخلي ضمن ServBay).
   • اسم النطاق: مثلًا servbay-phpixie-test.local (العنوان المحلي الذي ستستخدمه في المتصفح).
   • نوع الموقع: اختر PHP.
   • إصدار PHP: اختر الإصدار الذي ترغب باستخدامه مثل 8.3.
   • المجلد الجذري (Document Root): وجهه إلى مجلد web ضمن مشروعك: /Applications/ServBay/www/servbay-phpixie-app/web.

   لماذا مجلد /web؟

   ملف الدخول الرئيسي لمشروع PHPixie هو web/index.php. ولأغراض الأمان والممارسات المثلى، يجب أن يكون المسار الجذري لخادم الويب موجهاً مباشرة إلى مجلد web الذي يحتوي ملف الدخول، وليس المجلد الأعلى للمشروع، لمنع الوصول المباشر عبر الويب إلى الملفات الحساسة داخل المشروع (مثل ملفات الإعدادات أو مجلد vendor).

5. احفظ الإعدادات. سيقوم ServBay تلقائيًا بضبط إعدادات Caddy وتحديث ملف hosts المحلي (عند الحاجة) ليوجه servbay-phpixie-test.local إلى خادم ServBay المحلي لديك.

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

إضافة شفرة نموذجية

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

1. إنشاء متحكم نموذجي: أضف الشفرة التالية إلى ملف src/App/HTTP/Controller/Home.php. إذا لم يكن الملف أو المجلد موجودًا، أنشئه يدويًا.

   <?php
   
   namespace App\HTTP\Controller;
   
   use PHPixie\HTTP\Request;
   use PHPixie\Template;
   use PHPixie\Database\Query; // استيراد فئة الاستعلام
   
   class Home extends \PHPixie\Controller
   {
       protected $template;
   
       public function __construct(Template $template)
       {
           $this->template = $template;
       }
   
       // Action الصفحة الرئيسية الافتراضية
       public function action_index(Request $request)
       {
           // عرض قالب assets/templates/app/home.php
           return $this->template->render('app:home');
       }
   
       // Action مثال على Memcached
       public function action_memcached(Request $request)
       {
           $cache = $this->components->cache();
           $cache->set('key', 'Hello Memcached from ServBay!', 60); // تخزين بيانات، صلاحية 60 ثانية
           $value = $cache->get('key'); // جلب البيانات
           return $this->response()->string($value); // استجابة نصية
       }
   
       // Action مثال على Redis
       public function action_redis(Request $request)
       {
           $redis = $this->components->redis();
           $redis->set('key', 'Hello Redis from ServBay!'); // تخزين بيانات
           $value = $redis->get('key'); // جلب البيانات
           return $this->response()->string($value); // استجابة نصية
       }
   
       // Action إضافة مستخدم إلى MySQL/PostgreSQL
       public function action_add_user(Request $request)
       {
           // استخدام مكون قاعدة البيانات لجلب منشئ الاستعلام
           $query = $this->components->database()->query();
           // إدراج بيانات مستخدم جديد إلى جدول 'users'
           $query->insert('users')->data([
               'name' => 'ServBay Demo User',
               'email' => 'demo-' . uniqid() . '@servbay.test', // بريد إلكتروني فريد
           ])->execute(); // تنفيذ عملية الإدراج
   
           return $this->response()->string('User added successfully.'); // رسالة نجاح
       }
   
       // Action استعراض قائمة المستخدمين من MySQL/PostgreSQL
       public function action_list_users(Request $request)
       {
           // استخدام مكون قاعدة البيانات لجلب منشئ الاستعلام
           $query = $this->components->database()->query();
           // استعلام جميع المستخدمين من جدول 'users'
           $users = $query->select('*')->from('users')->execute()->fetchAll(); // تنفيذ الاستعلام وجلب كل النتائج
   
           return $this->response()->json($users); // إرجاع قائمة المستخدمين بصيغة JSON
       }
   }

2. إنشاء قالب نموذجي: أضف الشفرة التالية إلى ملف assets/templates/app/home.php. إذا لم يكن الملف أو المجلد موجودًا، أنشئه يدويًا.

   <!doctype html>
   <html lang="en">
   <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>Welcome to PHPixie on ServBay</title>
       <style>
           body { font-family: sans-serif; line-height: 1.6; margin: 20px; }
           h1 { color: #333; }
           p { margin-bottom: 15px; }
           code { background-color: #f4f4f4; padding: 2px 5px; border-radius: 4px; }
           ul { list-style: none; padding: 0; }
           li { margin-bottom: 10px; }
           li a { text-decoration: none; color: #007bff; }
           li a:hover { text-decoration: underline; }
       </style>
   </head>
   <body>
       <h1>مرحباً بك في PHPixie على ServBay</h1>
       <p>يتم توليد هذه الصفحة ديناميكياً بواسطة تطبيق PHPixie الخاص بك على ServBay.</p>
   
       <h2>روابط الميزات النموذجية:</h2>
       <ul>
           <li><a href="/home/memcached">اختبار Memcached</a></li>
           <li><a href="/home/redis">اختبار Redis</a></li>
           <li><a href="/home/add_user">إضافة مستخدم إلى قاعدة البيانات</a></li>
           <li><a href="/home/list_users">عرض المستخدمين في قاعدة البيانات</a></li>
       </ul>
   
       <p>تأكد من أنك أتممت خطوات إعداد قاعدة البيانات وأنظمة التخزين المؤقت.</p>
   
   </body>
   </html>

الوصول إلى الموقع الأساسي

بعد الانتهاء من إعداد موقع ServBay وإضافة الشفرة النموذجية، يمكنك الآن زيارة النطاق المحلي الذي حددته عبر المتصفح:

• افتح المتصفح وزر https://servbay-phpixie-test.local.
• ينبغي أن تظهر لك صفحة مكتوب فيها "Welcome to PHPixie on ServBay" وروابط للميزات النموذجية.

إذا لم تتمكن من الوصول للصفحة، تحقق من الآتي:

• هل ServBay يعمل فعليًا؟
• هل إعدادات الموقع داخل ServBay صحيحة، خصوصًا النطاق ونوع الموقع والمجلد الجذري؟
• هل ملف hosts المحلي يوجه النطاق servbay-phpixie-test.local بشكل صحيح (غالبًا يتولى ServBay الأمر تلقائيًا)؟
• هل إصدار PHP المختار فعال في ServBay؟

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

يدعم PHPixie مباشرة العديد من أنظمة قواعد البيانات والتخزين المؤقت. يوفر لك ServBay حزماً مثل MySQL وPostgreSQL وRedis وMemcached يمكن دمجها بسهولة ضمن مشروعك.

ملاحظة مهمة: قبل الشروع في العمليات على قاعدة البيانات، تأكد من تشغيل خدمة قاعدة البيانات المختارة ضمن ServBay (مثل MySQL أو PostgreSQL)، وأنك أنشأت قاعدة بيانات للمشروع، مثل servbay_phpixie_app. يمكنك استخدام أدوات إدارة قواعد البيانات المقدمة (مثل Sequel Ace، Postico، TablePlus) أو واجهة سطر الأوامر لإنشاء قاعدة البيانات. بيانات الدخول الافتراضية عادة هي المستخدم root وكلمة المرور password (راجع إعدادات ServBay لديك).

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

بحسب نوع قاعدة البيانات (MySQL أو PostgreSQL)، قم بتعديل ملف assets/config/database.php في مجلد المشروع الرئيسي. عادة ما يكون عنوان قاعدة البيانات الافتراضي في ServBay هو 127.0.0.1.

مثال إعداد MySQL (assets/config/database.php):

<?php

return [
    'default' => [
        'driver'    => 'pdo',
        // عدل سلسلة الاتصال بموجـب نوع قاعدة البيانات وإعدادات ServBay
        'connection' => 'mysql:host=127.0.0.1;dbname=servbay_phpixie_app',
        'user'      => 'root', // المستخدم الافتراضي في ServBay
        'password'  => 'password', // كلمة المرور الافتراضية (راجع إعداداتك)
        'options'   => []
    ]
];

مثال إعداد PostgreSQL (assets/config/database.php):

<?php

return [
    'default' => [
        'driver'    => 'pdo',
        // عدل سلسلة الاتصال بموجـب نوع قاعدة البيانات وإعدادات ServBay
        'connection' => 'pgsql:host=127.0.0.1;dbname=servbay_phpixie_app',
        'user'      => 'root', // المستخدم الافتراضي في ServBay
        'password'  => 'password', // كلمة المرور الافتراضية (راجع إعداداتك)
        'options'   => []
    ]
];

إنشاء جداول قاعدة البيانات (عبر الهجرة/migrations)

يوفر PHPixie أدوات التحكم بسطر الأوامر لإدارة عمليات الهجرة (migrations)، وهي طريقة فعالة لتنظيم وتحديث هيكل قاعدة البيانات.

1. فتح الطرفية: انتقل إلى المجلد الجذري لمشروع PHPixie:

   cd /Applications/ServBay/www/servbay-phpixie-app

2. إنشاء ملف هجرة جديد: استخدم أداة CLI الخاصة بـ PHPixie لإنشاء ملف هجرة جديد لإنشاء جدول users:

   php pixie generate:migration create_users_table

   سيتم إنشاء ملف جديد باسم يحمل توقيت الإنشاء داخل assets/migrations.
3. تعديل ملف الهجرة: افتح ملف الهجرة الجديد (مثال: YYYY_MM_DD_HHMMSS_create_users_table.php) وعدل طريقتي up() و down() لتعريف هيكل الجدول:

   <?php
   
   use PHPixie\Database\Migration;
   use PHPixie\Database\Schema\Table;
   
   class CreateUsersTable extends Migration
   {
       public function up()
       {
           // استخدم منشئ الهيكل لإنشاء جدول 'users'
           $this->schema->create('users', function(Table $table) {
               $table->increments('id'); // مفتاح أساسي تلقائي التزايد
               $table->string('name'); // حقل الاسم
               $table->string('email')->unique(); // حقل البريد الإلكتروني، فريد
               $table->timestamps(); // حقولا تاريخ الإنشاء والتحديث
           });
       }
   
       public function down()
       {
           // حذف جدول 'users'
           $this->schema->drop('users');
       }
   }

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

   php pixie migrate

   إذا تمت العملية بنجاح فسيظهر تنبيه بذلك في الطرفية. يمكنك أيضًا التأكد من وجود الجدول عبر أدوات إدارة قواعد البيانات.

استخدام قواعد البيانات العلائقية (MySQL/PostgreSQL)

في متحكم المثال (src/App/HTTP/Controller/Home.php) أضفنا مسبقًا الطريقتين action_add_user و action_list_users لعرض كيفية التفاعل مع قاعدة البيانات عبر PHPixie.

• إضافة مستخدم: زيارة https://servbay-phpixie-test.local/home/add_user ستدرج بيانات مستخدم جديد في جدول users.
• عرض المستخدمين: زيارة https://servbay-phpixie-test.local/home/list_users ستجلب كل مستخدمي الجدول وتعرضهم بصيغة JSON.

إعداد واستخدام قواعد بيانات NoSQL (Memcached/Redis)

ServBay يأتي مثبتًا مسبقًا مع حزمي Memcached وRedis وإضافاتهما لـ PHP. ما عليك سوى تعديل إعدادات مشروعك للاستفادة منهما.

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

عدل أو أنشئ ملف الإعداد وأضف ما يلي:

<?php

return [
    'default' => [
        'driver' => 'memcached',
        'servers' => [
            [
                'host'   => '127.0.0.1', // عنوان ServBay الافتراضي لـ Memcached
                'port'   => 11211, // المنفذ الافتراضي لـ Memcached
                'weight' => 100,
            ],
        ],
    ],
];

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

عدل أو أنشئ ملف الإعداد وأضف ما يلي:

<?php

return [
    'default' => [
        'hostname' => '127.0.0.1', // عنوان ServBay الافتراضي لـ Redis
        'port'     => 6379, // المنفذ الافتراضي لـ Redis
        'timeout'  => 0,
        'database' => 0, // مؤشر قاعدة بيانات Redis
    ],
];

استخدام Memcached/Redis:

في المتحكم النموذجي (src/App/HTTP/Controller/Home.php) تم تضمين طريقتي action_memcached و action_redis لاستعراض استخدام مكون التخزين المؤقت في PHPixie (يمكن تخصيصه عبر الإعداد لاستخدام Memcached أو Redis).

• اختبار Memcached: زيارة https://servbay-phpixie-test.local/home/memcached ستخزن وتعرض قيمة عبر Memcached.
• اختبار Redis: زيارة https://servbay-phpixie-test.local/home/redis ستخزن وتعرض قيمة عبر Redis.

تأكد دائماً من تشغيل البرامج المقابلة (Memcached وRedis) في ServBay.

الخلاصة

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

يوفر ServBay بيئة متكاملة تسهل بشكل كبير إنشاء بيئة تطوير PHP، لتتمكن من التركيز على كتابة الكود وبناء التطبيق. نأمل أن يساعدك هذا الدليل على بدء مشروعك القادم بتقنيات PHPixie بسرعة وفاعلية!