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

example — دليل إعداد المشروع وتشغيله

يحتوي هذا المستند على الخطوات المطلوبة لاستعادة وتشغيل مشروع Laravel هذا على جهاز جديد.

مهم:

• يتضمن المشروع مسبقًا ملف .env مُعدًا وجاهزًا.
• يتضمن المشروع مسبقًا مفتاح تطبيق Laravel تم إنشاؤه.
• لا تقم بتشغيل الأمر php artisan key:generate --force.
• لا تقم بتشغيل الأمر php artisan migrate:fresh.

---

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

هذه الأوامر مخصصة لأنظمة Ubuntu أو الأنظمة المعتمدة على Debian.

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

إذا كان المشروع يتضمن ملفات واجهة أمامية، ثبّت Node.js وnpm:

sudo apt install -y nodejs npm

---

2. فك الضغط وفتح المشروع

فك ضغط ملف ZIP المُصدّر، ثم انتقل إلى مجلد المشروع الناتج:

cd /path/to/extracted-project

تأكد من وجود الملفات المطلوبة:

ls -la

يجب أن تتوفر الملفات التالية:

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

---

3. تثبيت حزم PHP

شغّل الأمر التالي من داخل المجلد الرئيسي للمشروع:

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

لا تقم باستبدال أو إعادة إنشاء ملف .env الموجود.

---

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

ملف .env الخاص بالمشروع مُعد مسبقًا بقيم مشابهة للقيم التالية:

DB_HOST=YOUR_DATABASE_HOST
DB_PORT=YOUR_DATABASE_PORT
DB_DATABASE=YOUR_DATABASE_NAME
DB_USERNAME=YOUR_DATABASE_USERNAME
DB_PASSWORD=YOUR_DATABASE_PASSWORD

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

---

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

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

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

CREATE USER IF NOT EXISTS 'YOUR_DATABASE_USERNAME'@'localhost'
    IDENTIFIED BY 'YOUR_DATABASE_PASSWORD';

ALTER USER 'YOUR_DATABASE_USERNAME'@'localhost'
    IDENTIFIED BY 'YOUR_DATABASE_PASSWORD';

GRANT ALL PRIVILEGES ON `YOUR_DATABASE_NAME`.*
    TO 'YOUR_DATABASE_USERNAME'@'localhost';

FLUSH PRIVILEGES;
SQL

---

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

توجد نسخة قاعدة البيانات الاحتياطية ضمن المشروع في المسار التالي:

storage/app/hosteday-backup/database.sql

استورد النسخة الاحتياطية إلى قاعدة البيانات التي أنشأتها:

sudo mysql `YOUR_DATABASE_NAME` < storage/app/hosteday-backup/database.sql

تحقق من استيراد جداول قاعدة البيانات بنجاح:

sudo mysql `YOUR_DATABASE_NAME` -e "SHOW TABLES;"

---

7. تجهيز ملفات 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 migrate:status

لا تقم بتشغيل php artisan migrate إلا إذا كنت تريد عمدًا تطبيق migrations أحدث من النسخة الاحتياطية المستوردة لقاعدة البيانات.

---

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

شغّل هذا الجزء فقط عندما يحتوي المشروع على ملف package.json:

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

---

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 إلى قيمة جديدة عند إصدار تحديث جديد للتطبيق، ثم تحديث القيمة المستخدمة داخل التطبيق قبل نشر الإصدار الجديد.

تنبيه أمني: مفتاح API المضمن داخل تطبيق Flutter يمكن استخراجه من التطبيق، لذلك لا يجب اعتباره بديلًا عن مصادقة المستخدم. استمر في استخدام رموز المصادقة الخاصة بالمستخدمين، مثل Bearer Token، لحماية بيانات كل مستخدم وصلاحياته.

يمكن إلغاء هذه الحماية من خلال إزالة Middleware باسم api-protection من المسارات المحمية داخل ملف routes/api.php، لكن لا يُنصح بذلك في بيئة الإنتاج.

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

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

تسجيل الدخول

• Method: POST
• URL:

http://127.0.0.1:8000/api/auth/login

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

• Method: POST
• URL:

http://127.0.0.1:8000/api/auth/register

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

• Method: GET
• URL:

http://127.0.0.1:8000/api/user

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

Authorization: Bearer YOUR_ACCESS_TOKEN

---

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

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

شغّل هذا الأمر في نافذة Terminal منفصلة إذا كان التطبيق يستخدم الوظائف المؤجلة:

php artisan queue:work

المجدول Scheduler

شغّل هذا الأمر في نافذة Terminal منفصلة إذا كان التطبيق يستخدم المهام المجدولة:

php artisan schedule:work

خادم الوقت الفعلي Realtime Server

شغّل هذا الجزء فقط عندما يحتوي ملف .env على القيمة التالية:

ALLOW_REALTIME=true

شغّل Laravel Reverb في نافذة Terminal منفصلة:

php artisan reverb:start

---

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

عند النشر باستخدام Apache أو Nginx:

• اضبط مجلد الجذر الخاص بالموقع ليشير إلى مجلد public داخل المشروع.
• لا تعرض المجلد الرئيسي للمشروع مباشرة من خلال خادم الويب.
• تأكد من أن مستخدم خادم الويب يمتلك صلاحية الكتابة على storage وbootstrap/cache.
• امنع الوصول العام إلى ملفات .env و.INFO.md وملف تفريغ قاعدة البيانات.

الأوامر المقترحة لبيئة الإنتاج:

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