تحميل مشروع Laravel من GitHub يبدو بسيطًا ظاهريًا. clone للمستودع وتشغيل المشروع.
لكن أي شخص عمل على مشاريع مفتوحة المصدر يعرف أن هذه الخطوة غالبًا لا تنجح من أول مرة.
السبب ليس Laravel نفسه، بل البيئة المحيطة بالمشروع:
- إصدار PHP
- إصدار Composer
- إصدار Node
- إعدادات قاعدة البيانات
- ملف البيئة
لذلك تشغيل مشروع Laravel بشكل صحيح يعني إعادة بناء بيئة المشروع بالكامل وليس فقط تحميل الكود.
أول خطوة: تحميل المشروع
تحميل المشروع يتم عبر Git:
git clone https://github.com/user/project.git
cd projectبعد هذه الخطوة أصبح لديك الكود فقط، لكن المشروع ما زال غير قابل للتشغيل.
المشكلة التي لا ينتبه لها كثير من المطورين
قبل تشغيل أي مشروع Laravel يجب التأكد من التوافق بين الإصدارات.
أغلب مشاكل تشغيل المشاريع من GitHub تأتي من هنا.
ملف composer.json يحدد إصدار PHP المطلوب.
"require": {
"php": "^8.2",
"laravel/framework": "^11.0"
}
إذا كان لديك PHP 8.0 مثلًا، فالمشروع لن يعمل.
نفس الشيء ينطبق على:
- Node.js
- NPM
- إصدار Laravel نفسه
لهذا من الجيد دائمًا قراءة:
README.mdقبل تشغيل المشروع.
تثبيت الحزم عبر Composer
Laravel يعتمد على Composer لإدارة المكتبات.
بعد تحميل المشروع يجب تثبيت جميع الاعتمادات:
composer installهذا الأمر يقوم بتحميل جميع المكتبات داخل مجلد:
vendor/وهو مجلد لا يتم رفعه عادة إلى GitHub.
تثبيت مكتبات الواجهة (إن وجدت)
بعض المشاريع تستخدم Vite أو أدوات Frontend.
لذلك يجب تثبيت الحزم:
npm installبعدها يتم بناء ملفات الواجهة:
npm run buildأو أثناء التطوير:
npm run devإنشاء ملف البيئة
ملف .env يحتوي إعدادات المشروع.
عادة لا يتم رفعه إلى GitHub لأسباب أمنية.
بدلًا منه يوجد:
.env.exampleلذلك يتم نسخه:
cp .env.example .envإنشاء مفتاح التطبيق
Laravel يحتاج مفتاح تشفير لتشغيل التطبيق.
php artisan key:generateسيتم حفظ المفتاح داخل ملف البيئة.
تشغيل migrations
بعد إعداد قاعدة البيانات داخل .env يتم إنشاء الجداول:
php artisan migrateإذا كان المشروع يحتوي بيانات أولية:
php artisan migrate --seedالأوامر الأساسية لتشغيل المشروع
غالبًا تشغيل المشروع يتطلب الخطوات التالية:
composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate
مشكلة الصلاحيات في Linux و Mac
أحيانًا يظهر خطأ متعلق بكتابة الملفات داخل مجلد storage.
الحل إعطاء صلاحيات للمجلد:
chmod -R 777 storageأو الأفضل:
chmod -R 775 storage bootstrap/cacheمشاكل الإصدارات (Version Compatibility)
هذه المشكلة هي الأكثر شيوعًا عند تشغيل مشاريع Laravel من GitHub.
الأمثلة الشائعة:
- المشروع يحتاج PHP 8.3 وأنت تستخدم 8.1
- المشروع يستخدم Node 20 وأنت تستخدم Node 16
- المشروع يعتمد على إصدار Composer مختلف
بعض المشاريع تستخدم أدوات مثل:
- Docker
- Laravel Sail
- Dev Containers
والسبب هو تثبيت بيئة ثابتة للمشروع.
نصيحة عملية قبل تشغيل أي مشروع
افتح دائمًا هذه الملفات قبل تشغيل المشروع:
- composer.json
- package.json
- README.md
هذه الملفات تخبرك:
- إصدار PHP
- مكتبات المشروع
- الأدوات المطلوبة
تجاهل هذه الخطوة هو السبب الرئيسي لمعظم مشاكل تشغيل المشاريع.