استعادة وتشغيل مشروع Laravel المُصدَّر

توضح هذه الوثيقة مكونات مشروع Laravel المُصدَّر وآلية استعادته وتشغيله على جهاز أو خادم جديد. يتضمن التصدير ملفات المشروع، إعداداته، نسخة قاعدة البيانات، وملفًا مرجعيًا يوضح عناصر الاستعادة الأساسية.

المشروع المُصدَّر يحتوي مسبقًا على ملف .env مُعدّ، ومفتاح تطبيق Laravel تم إنشاؤه سابقًا. لذلك لا يحتاج المشروع إلى إنشاء مفتاح جديد أثناء الاستعادة، كما لا ينبغي إعادة تهيئة قاعدة البيانات من الصفر.

تنبيه مهم

• يحتوي ملف .env على إعدادات خاصة بقاعدة البيانات والخدمات المرتبطة بالمشروع.
• يحتوي ملف النسخة الاحتياطية لقاعدة البيانات على بيانات المشروع الكاملة.
• يجب الحفاظ على خصوصية ملف .env وملف .INFO.md وملف قاعدة البيانات.
• لا يُستخدم الأمر التالي أثناء الاستعادة لأنه يستبدل مفتاح التطبيق الحالي:

php artisan key:generate --force

• لا يُستخدم الأمر التالي لأنه يحذف الجداول والبيانات الحالية ثم يعيد إنشاء قاعدة البيانات:

php artisan migrate:fresh

1. متطلبات النظام

تم إعداد أوامر التشغيل التالية للأنظمة المعتمدة على Ubuntu أو Debian.

يتطلب المشروع بيئة PHP تشمل الإضافات الأساسية التي يستخدمها Laravel، بالإضافة إلى Composer، وعميل وخادم MySQL، وأدوات فك الضغط وإدارة الملفات.

sudo apt update

sudo apt install -y \
    php \
    php-cli \
    php-mbstring \
    php-xml \
    php-curl \
    php-zip \
    php-mysql \
    unzip \
    git \
    composer \
    mysql-server \
    mysql-client

إذا كان المشروع يتضمن واجهة أمامية أو ملفات مبنية باستخدام Vite أو Laravel Mix، فستكون بيئة Node.js وnpm مطلوبة أيضًا:

sudo apt install -y nodejs npm

2. محتويات ملف التصدير

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

يمكن الانتقال إلى مجلد المشروع بعد فك الضغط عبر:

cd /path/to/extracted-project

ويُستخدم الأمر التالي لعرض محتويات المجلد والتحقق من وجود الملفات الرئيسية:

ls -la

من المتوقع أن تتوفر الملفات التالية داخل المشروع:

.env
artisan
composer.json
storage/app/hosteday-backup/database.sql
.INFO.md

يمثل كل ملف منها جزءًا مهمًا من عملية الاستعادة:

3. اعتماديات PHP وLaravel

يحتوي المشروع على ملف composer.json الذي يحدد مكتبات PHP وحزم Laravel المطلوبة. بعد نقل المشروع إلى جهاز أو خادم جديد، تُستعاد هذه الحزم داخل مجلد vendor.

يُنفذ الأمر التالي من جذر المشروع:

composer install --no-interaction --prefer-dist --optimize-autoloader

لا يجب استبدال ملف .env الموجود داخل المشروع بملف جديد، لأن النسخة الحالية تحتوي على الإعدادات المرتبطة بالتصدير وقاعدة البيانات.

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

ملف .env المرفق مع المشروع يحتوي على إعدادات الاتصال بقاعدة البيانات التي تم استخدامها عند تصدير المشروع.

تكون الإعدادات عادةً بالشكل التالي:

DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=db_hoste
DB_USERNAME=u_hoste
DB_PASSWORD=YOUR_EXISTING_DATABASE_PASSWORD

يجب أن تكون قاعدة البيانات، واسم المستخدم، وكلمة المرور المستخدمة عند الاستعادة مطابقة للقيم الحقيقية الموجودة في ملف .env.

ملاحظة أمنية

لا يُنصح بنسخ كلمة مرور قاعدة البيانات داخل مستندات عامة أو مشاركتها عبر البريد أو المحادثات. تبقى القيمة الأصلية محفوظة داخل ملف .env الخاص بالمشروع.

5. إنشاء قاعدة البيانات ومستخدم التطبيق

يتطلب المشروع قاعدة بيانات MySQL ومستخدمًا مخصصًا يمتلك الصلاحيات اللازمة للوصول إليها.

يوضح المثال التالي البنية المطلوبة لإنشاء قاعدة البيانات، وإنشاء مستخدم التطبيق، ومنحه الصلاحيات الكاملة على قاعدة البيانات الخاصة بالمشروع:

sudo mysql <<'SQL'
CREATE DATABASE IF NOT EXISTS `db_hoste`
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

CREATE USER IF NOT EXISTS 'u_hoste'@'localhost'
    IDENTIFIED BY 'YOUR_EXISTING_DATABASE_PASSWORD';

ALTER USER 'u_hoste'@'localhost'
    IDENTIFIED BY 'YOUR_EXISTING_DATABASE_PASSWORD';

GRANT ALL PRIVILEGES ON `db_hoste`.*
    TO 'u_hoste'@'localhost';

FLUSH PRIVILEGES;
SQL

يجب استبدال القيمة التالية بكلمة المرور الفعلية الموجودة في ملف .env:

YOUR_EXISTING_DATABASE_PASSWORD

يعتمد المشروع على ترميز utf8mb4 لضمان دعم النصوص العربية والرموز الخاصة وبيانات Unicode بشكل كامل.

6. استعادة قاعدة البيانات المُصدَّرة

تتضمن حزمة المشروع نسخة SQL كاملة من قاعدة البيانات الأصلية في المسار التالي:

storage/app/hosteday-backup/database.sql

يحتوي هذا الملف على بنية الجداول والبيانات التي كانت موجودة عند إنشاء التصدير.

يتم استيراد النسخة إلى قاعدة البيانات التي تم إنشاؤها سابقًا عبر:

sudo mysql --database='db_hoste' < storage/app/hosteday-backup/database.sql

بعد اكتمال الاستيراد، يمكن التحقق من ظهور الجداول داخل قاعدة البيانات عبر:

sudo mysql --database='db_hoste' -e "SHOW TABLES;"

ظهور الجداول في النتيجة يعني أن نسخة قاعدة البيانات تم استعادتها بنجاح.

7. تهيئة ملفات Laravel والتخزين

يعتمد Laravel على مجلدات قابلة للكتابة لتخزين السجلات، والجلسات، والملفات المؤقتة، وملفات العرض المترجمة.

تُستخدم الأوامر التالية لتنظيف الملفات المؤقتة، وإنشاء المجلدات الضرورية، ومنح الصلاحيات المناسبة:

php artisan optimize:clear

mkdir -p \
    storage/framework/cache \
    storage/framework/sessions \
    storage/framework/views \
    storage/logs

chmod -R ug+rwx storage bootstrap/cache

php artisan storage:link

يقوم الأمر التالي بإنشاء رابط رمزي بين مجلد التخزين العام ومسار Laravel العام:

php artisan storage:link

يسمح ذلك بالوصول إلى الصور والملفات المرفوعة من خلال المسار العام للتطبيق.

يمكن التحقق من قدرة Laravel على الاتصال بقاعدة البيانات المستعادة باستخدام:

php artisan migrate:status

هذا الأمر يعرض حالة ملفات Migration دون إجراء أي تعديل على قاعدة البيانات.

لا يُستخدم الأمر التالي إلا عند وجود ملفات Migration أحدث من نسخة قاعدة البيانات المستوردة، وعند التأكد من الحاجة إلى تطبيقها:

php artisan migrate

8. بناء ملفات الواجهة الأمامية

بعض مشاريع Laravel تتضمن واجهة أمامية مبنية باستخدام Node.js وVite أو أدوات مشابهة. في هذه الحالة يكون ملف package.json موجودًا في جذر المشروع.

يتحقق الأمر التالي من وجود ملفات Node.js المناسبة، ثم يثبت الحزم ويبني ملفات الإنتاج:

if [ -f package-lock.json ]; then
    npm ci
    npm run build
elif [ -f package.json ]; then
    npm install
    npm run build
fi

في حال عدم وجود ملف package.json، فهذا يعني أن المشروع لا يتطلب بناء واجهة أمامية عبر npm.

9. تشغيل المشروع محليًا

بعد استعادة قاعدة البيانات، وتثبيت الاعتمادات، وتجهيز ملفات التخزين، يصبح المشروع جاهزًا للتشغيل محليًا.

يتم تشغيل خادم Laravel المحلي عبر:

php artisan serve --host=127.0.0.1 --port=8000

بعد بدء الخادم، يكون التطبيق متاحًا عبر الرابط التالي:

http://127.0.0.1:8000

حماية واجهات API

تتضمن واجهات API في هذا المشروع طبقة حماية إضافية عبر Middleware باسم:

api-protection

تتطلب هذه الحماية إرسال مفتاح API ضمن ترويسة كل طلب، بما في ذلك طلبات تسجيل الدخول وإنشاء الحساب.

تكون الترويسة المطلوبة بالشكل التالي:

X-Api-Token: YOUR_API_TOKEN

تمثل القيمة التالية مفتاح الحماية الخاص بالتطبيق:

YOUR_API_TOKEN

يجب أن تكون هذه القيمة طويلة وعشوائية وفريدة، ولا ينبغي استخدام قيم بسيطة أو متوقعة مثل:

token

مثال على قيمة قوية:

YOUR_API_TOKEN=GENERATE_A_LONG_RANDOM_SECRET_TOKEN_HERE

عند استخدام تطبيق Flutter أو أي تطبيق عميل آخر، تُرسل الترويسة مع جميع طلبات API:

headers: {
  'X-Api-Token': 'YOUR_API_TOKEN',
  'Accept': 'application/json',
  'Content-Type': 'application/json',
}

تمثل هذه الحماية طبقة إضافية لتقليل الوصول غير المباشر إلى واجهات API، لكنها لا تُعد بديلًا عن نظام مصادقة المستخدمين.

يظل رمز الوصول الخاص بالمستخدم، مثل Bearer Token، ضروريًا لحماية بيانات الحسابات والصلاحيات والعمليات الخاصة بكل مستخدم.

Authorization: Bearer YOUR_ACCESS_TOKEN

تنبيه أمني

يمكن استخراج القيم المضمنة داخل تطبيقات Flutter أو تطبيقات الهاتف بعد نشرها، لذلك لا ينبغي اعتبار X-Api-Token وسيلة مصادقة نهائية للمستخدمين.

يوصى باستخدامه كطبقة حماية إضافية فقط، مع استمرار الاعتماد على رموز المصادقة الخاصة بالمستخدمين.

يمكن تدوير مفتاح API عند إصدار تحديثات جديدة للتطبيق، مع تحديث القيمة داخل إصدار التطبيق الجديد. يجب تنسيق عملية التغيير بعناية، لأن تغيير المفتاح مباشرة قد يمنع الإصدارات القديمة من التطبيق من الوصول إلى API.

يمكن تعطيل هذه الطبقة بإزالة Middleware باسم api-protection من المسارات المحمية داخل الملف التالي:

routes/api.php

لكن تعطيل الحماية لا يُنصح به في بيئة الإنتاج.

تجربة واجهات API

بعد تشغيل التطبيق محليًا، يمكن اختبار واجهات API باستخدام أدوات مثل Postman أو Insomnia أو Bruno أو أي عميل HTTP مشابه.

تتطلب جميع الطلبات ترويسة مفتاح API:

X-Api-Token: YOUR_API_TOKEN

تسجيل الدخول

POST /api/auth/login

إنشاء حساب جديد

POST /api/auth/register

الحصول على بيانات المستخدم الحالي

GET /api/user

يتطلب هذا المسار إرسال رمز المصادقة الذي تم الحصول عليه بعد تسجيل الدخول أو إنشاء حساب جديد:

Authorization: Bearer YOUR_ACCESS_TOKEN

10. الخدمات الخلفية الاختيارية

قد يعتمد المشروع على خدمات إضافية تعمل بجانب خادم Laravel الرئيسي. لا تكون هذه الخدمات مطلوبة في جميع المشاريع، لكنها ضرورية عند استخدام الطوابير أو المهام المجدولة أو الاتصال الفوري.

عامل الطوابير Queue Worker

إذا كان المشروع يستخدم Jobs أو Notifications أو عمليات خلفية، يعمل عامل الطوابير في نافذة طرفية مستقلة:

php artisan queue:work

تُستخدم هذه الخدمة لمعالجة المهام التي لا ينبغي تنفيذها أثناء طلب المستخدم مباشرة، مثل إرسال البريد، إنشاء الملفات، معالجة الوسائط، أو تنفيذ العمليات الطويلة.

مجدول المهام Scheduler

إذا كان المشروع يتضمن أوامر مجدولة داخل Laravel Scheduler، يعمل المجدول عبر:

php artisan schedule:work

تُستخدم هذه الخدمة لتنفيذ المهام المتكررة، مثل إرسال التقارير، تنظيف البيانات، التحقق من الحالات، أو تشغيل العمليات اليومية.

خادم Realtime

إذا احتوى ملف .env على الإعداد التالي:

ALLOW_REALTIME=true

فإن المشروع يدعم تشغيل الاتصال الفوري عبر Laravel Reverb.

يعمل خادم Realtime في نافذة طرفية مستقلة عبر:

php artisan reverb:start

تتيح هذه الخدمة إرسال واستقبال الأحداث اللحظية بين الخادم والعملاء المتصلين، مثل الإشعارات الفورية، الدردشة، تحديثات الطلبات، ولوحات التحكم الحية.

11. ملاحظات النشر على بيئة الإنتاج

عند نشر المشروع على خادم Apache أو Nginx، يجب أن يشير Document Root إلى مجلد public داخل مشروع Laravel فقط.

لا يجب إتاحة جذر المشروع مباشرة من خادم الويب، لأن ذلك قد يكشف ملفات حساسة مثل:

.env
.INFO.md
storage/app/hosteday-backup/database.sql

تشمل متطلبات بيئة الإنتاج ما يلي:

• توجيه Document Root إلى مجلد public.
• منع الوصول الخارجي إلى ملف .env.
• منع الوصول الخارجي إلى ملفات النسخ الاحتياطية.
• منح مستخدم خادم الويب صلاحية الكتابة على storage وbootstrap/cache.
• تشغيل خدمات Queue وScheduler وRealtime عند الحاجة.
• استخدام HTTPS في بيئة الإنتاج.
• استخدام إعدادات قاعدة بيانات آمنة ومخصصة للخادم الإنتاجي.

الأوامر الموصى بها لتجهيز المشروع في بيئة الإنتاج هي:

composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader

php artisan optimize:clear

php artisan optimize

php artisan storage:link

chmod -R ug+rwx storage bootstrap/cache

موقع النسخة الاحتياطية لقاعدة البيانات

تبقى نسخة قاعدة البيانات التي تم تصديرها مع المشروع متاحة في المسار التالي:

storage/app/hosteday-backup/database.sql

يمثل هذا الملف نسخة كاملة من قاعدة بيانات المشروع في وقت التصدير، ويشمل الجداول والبيانات المرتبطة بالتطبيق.

يجب التعامل معه كملف حساس، وعدم وضعه داخل مجلد عام أو مستودع Git عام أو رابط تحميل متاح للجميع.

التحقق من نجاح الاستعادة

تُعد عملية الاستعادة مكتملة عند تحقق العناصر التالية:

• تثبيت مكتبات PHP داخل مجلد vendor.
• وجود ملف .env الأصلي وعدم استبداله.
• إنشاء قاعدة البيانات ومستخدم التطبيق بنجاح.
• استيراد ملف database.sql وظهور الجداول داخل MySQL.
• نجاح أمر php artisan migrate:status.
• تشغيل خادم Laravel المحلي دون أخطاء.
• فتح التطبيق عبر http://127.0.0.1:8000.
• نجاح طلبات API بعد إرسال ترويسة X-Api-Token.
• نجاح المصادقة باستخدام Authorization: Bearer YOUR_ACCESS_TOKEN للمسارات المحمية.
• تشغيل Queue أو Scheduler أو Realtime عند اعتماد المشروع عليها.