مقدمة

يُفصِّل هذا الدليل طريقة موثوقة لنشر تطبيق Laravel على استضافة تُدار بواسطة cPanel (مستضافة مشتركة أو VPS). يغطي: إعداد PHP، رفع الكود، تثبيت التبعيات (Composer)، تكوين قاعدة البيانات، ضبط جذر المستندات (document root) إلى مجلد <code>public</code> public, وإنشاء مهمة Cron لتشغيل المجدول (scheduler) وعمليات التحقق عند النشر إلى بيئة الإنتاج. بعض الميزات (Terminal/SSH، MultiPHP Manager، Composer المدمج) تعتمد على إعدادات الخادم وباقتك.

المتطلبات

  • الوصول إلى حساب cPanel الخاص بك. راجع: كيفية الوصول إلى cPanel.
  • الوصول عبر SSH أو الطرفية المدمجة في cPanel، أو إمكانية تشغيل Composer محليًا ثم رفع مجلد <code>vendor</code> vendor. توضيح: Composer = مدير تبعيات PHP؛ Artisan = أداة سطر الأوامر الخاصة بـ Laravel (php artisan)؛ Cron = مهمة مجدولة.
  • إصدار PHP المتوافق مع إصدار Laravel لديك. تحقق من composer.json ملف <code>composer.json</code> الخاص بالمشروع وإذا لزم الأمر غيّر إصدار PHP باستخدام MultiPHP Manager في cPanel. (MultiPHP Manager — مستندات cPanel).
  • قاعدة بيانات MySQL (أو مكافئ مدعوم) ومستخدم تم إنشاؤهما في cPanel. (MySQL Databases — مستندات cPanel).
  • الوصول إلى مدير الملفات (File Manager) أو FTP/SFTP لرفع الملفات ومساحة تخزين كافية.
  • توفر Composer على الخادم أو إمكانية تشغيله محليًا (راجع مقال cPanel حول تثبيت Laravel/Composer للحالات الخاصة). (كيفية تثبيت Laravel على cPanel — دعم cPanel).

ملخص سريع (الإجراء)

  1. تسجيل الدخول إلى cPanel.
  2. التحقق / تعيين إصدار PHP (MultiPHP Manager).
  3. إنشاء قاعدة البيانات والمستخدم MySQL.
  4. رفع الشيفرة (Git / FTP / File Manager).
  5. تثبيت التبعيات باستخدام Composer (أو محليًا ثم الرفع).
  6. تكوين ملف .env وإنشاء APP_KEY.
  7. تعيين المجلد الجذري (document root) للنطاق إلى /chemin/vers/projet/public أو، إذا تعذّر ذلك، نقل/تعديل public.
  8. تعيين الأذونات (storage، bootstrap/cache) وإنشاء مهمة Cron للـ scheduler.

تفاصيل النشر (خطوات مرقمة)

1) تسجيل الدخول إلى cPanel

افتح cPanel باستخدام بيانات اعتمادك عبر عنوان URL الذي زوّده مزود الاستضافة.

الوصول إلى cPanel من منطقة العميل
الوصول إلى cPanel (مثال على الرابط المؤدي إلى اللوحة).

2) التحقق / تعيين إصدار PHP

يتطلب Laravel إصدار PHP أدنى بحسب الإصدار المستخدم. في cPanel، افتح MultiPHP Manager وحدد إصدار PHP للنطاق المعني.

اختيار إصدار PHP عبر MultiPHP Manager في cPanel
اختيار إصدار PHP المناسب للنطاق عبر MultiPHP Manager.

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

3) إنشاء قاعدة بيانات MySQL

في cPanel، افتح MySQL Databases أو Database Wizard؛ أنشئ قاعدة بيانات ومستخدمًا، ثم اربط المستخدم بالقاعدة ومنحه الصلاحيات اللازمة. سجّل اسم القاعدة واسم المستخدم وكلمة المرور — .envستُستخدم هذه القيم في ملف .env.

إنشاء قاعدة بيانات MySQL عبر cPanel
إنشاء قاعدة بيانات MySQL في cPanel.

4) رفع الشيفرة (Git / FTP / File Manager)

طرق شائعة:

  • Git: إذا كانت أداة Git أو وصول SSH متاحة، استنسخ المستودع مباشرة على الخادم.
  • FTP/SFTP: ارفع ملف ZIP ثم استخرجه عبر File Manager.
  • File Manager: ارفع الأرشيف واستخدم خيار Extract.
File Manager في cPanel لرفع واستخراج الأرشيفات
رفع واستخراج أرشيف عبر File Manager.

5) تثبيت التبعيات (Composer)

إذا كان لديك وصول إلى الطرفية/SSH، انتقل إلى مجلّد المشروع ثم نفّذ: composer install --no-dev --optimize-autoloader

composer install --no-dev --optimize-autoloader

لإنشاء مشروع مباشرةً: composer create-project laravel/laravel nom-du-projet

composer create-project laravel/laravel nom-du-projet

نصائح إذا لم يتوفر Composer على الخادم:

  • نفّذ الأمر composer install على جهازك المحلي composer install ثم ارفع مجلد vendor وملف composer.lock. vendor + الملف composer.lock.
  • تحقق من إصدار PHP الخاص بواجهة سطر الأوامر (CLI) الذي يستخدمه Composer: في الطرفية، which php و php -v. في بعض بيئات cPanel، استخدم الغلاف EA-PHP (مثلاً /usr/local/bin/ea-php82) لاستدعاء الإصدار الصحيح.
الطرفية المدمجة في cPanel لتشغيل Composer وArtisan
طرفية cPanel: مفيدة لتشغيل Composer وأوامر Artisan.

6) تكوين .env وتوليد APP_KEY

انسخ .env.example إلى .env ثم املأ إعدادات قاعدة البيانات (DB_CONNECTION, DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD). قم بتوليد مفتاح التطبيق:

php artisan key:generate
php artisan migrate --force

إذا لم يكن لديك وصول SSH:

  • قم بتوليد المفتاح محليًا: php artisan key:generate --show ثم ألصق القيمة في .env.
  • بالنسبة للترحيلات (migrations)، صدّر قاعدة البيانات بعد الترحيل محليًا واستورد ملف SQL عبر phpMyAdmin إذا لم تتمكن من تشغيل artisan migrate على الخادم.

7) جذر المستند (Document root): توجيه الجذر إلى public

يجب أن يخدم Laravel من المجلد project/public. حلّان:

  1. تعديل مجلد الجذر (document root) للنطاق / النطاق الفرعي في cPanel : Domains → Manage → New Document Root، وأدخل المسار /home/username/mon-projet/public. (يتطلب توفر هذا الخيار في استضافتك.)
  2. إذا لم تتمكن من تغيير مجلد الجذر، يمكنك نسخ محتويات public إلى public_html وقم بتعديل المسارات في index.php (غير مُوصى به من ناحية الأمان). في index.php استبدل المسارات النسبية بمسارات مطلقة إلى /home/username/mon-projet : 
    require '/home/username/mon-projet/vendor/autoload.php';
$app = require_once '/home/username/mon-projet/bootstrap/app.php';
اختيار مجلد جذر مخصص عند إنشاء نطاق في cPanel
تعيين مجلد جذر مخصص لـ Addon Domain / Subdomain.

8) الأذونات والتخزين

امنح صلاحيات الكتابة للمجلد storage وإلى bootstrap/cache. يُفضّل 0755 أو 0775 حسب بيئة التشغيل. تجنّب 0777. إذا كان لديك SSH :

chmod -R 775 storage bootstrap/cache
chown -R username:username storage bootstrap/cache

أنشئ الرابط الرمزي إلى public/storage :

php artisan storage:link

إذا لم يتوفر Terminal : أنشئ يدوياً public/storage وقم بتعديل طريقة رفع الملفات.

تعديل أذونات الملفات عبر مدير الملفات في cPanel
تعديل أذونات ملف أو مجلد من خلال File Manager.

9) المهام المجدولة (scheduler)

يستخدم Laravel المجدول الخاص بـ Artisan: أنشئ مهمة Cron في cPanel (Cron Jobs) لتشغيلها كل دقيقة:

* * * * * /usr/local/bin/ea-php82 /home/username/mon-projet/artisan schedule:run >> /dev/null 2>&1

استبدل /usr/local/bin/ea-php82 بالمسار الفعلي لملف تنفيذ PHP (قابل للتحقق بواسطة الأمر which php which php عبر SSH) وقم بتعديل مسار المشروع. أنشئ المهمة عبر واجهة مهمة Cron في قاعدة المعرفة (KB) الخاصة بنا لمزيد من التفاصيل.

نموذج إضافة مهمة Cron في cPanel
إضافة مهمة Cron في cPanel — حدد الأمر الكامل والجدولة.

10) SSL والنشر في بيئة الإنتاج

ثبّت شهادة SSL عبر قسم SSL/TLS في cPanel (Let's Encrypt أو غيرها). قم بتجميع وتحسين الأصول لبيئة الإنتاج:

composer dump-autoload -o
php artisan config:cache
php artisan route:cache
php artisan view:cache
الوصول إلى شهادات SSL/TLS من cPanel
تثبيت شهادة SSL/TLS عبر cPanel.

القيود الشائعة والحلول

  • لا يوجد وصول إلى SSH/الطرفية: شغّل Composer محليًا وارفع مجلد vendor vendor؛ وقم بتوليد APP_KEY APP_KEY محليًا واستورد الترحيلات عبر SQL إذا لزم الأمر.
  • MultiPHP Manager أو بعض الامتدادات المفقودة: إذا لم يعرض نطاقك النسخة المطلوبة، فاتصل بالدعم؛ بعض الامتدادات (مثل fileinfofileinfo، mbstring mbstring) ضرورية لـ Laravel.
  • لا يمكن تغيير document root للنطاق الرئيسي : يمكنك استخدام نطاق فرعي / addon domain أو نقل محتوى public إلى public_html مع تعديل index.php، لكن الحل الأكثر أمانًا يظل تعديل document root.
  • قيود الحصص/الموارد: تفرض الاستضافات المشتركة حدودًا (مساحة القرص، الذاكرة، زمن المعالج CPU). للتطبيقات الكبيرة، يُفضّل استخدام VPS أو خطة مناسبة.

استكشاف الأخطاء والأعطال الشائعة

  • خطأ 500 : تحقّق من storage/logs/laravel.log (افتح عبر File Manager أو استخدم tail عبر SSH) وسجلات Apache. انظر أيضًا دليلنا الداخلي حول خطأ 500.
  • SoftException / الأذونات : رسائل من النوع «File ... is writeable by group» أو «Permission denied» → عدّل الأذونات/الملكية (تجنّب 777)؛ بعض معالجات PHP (مثل suPHP) صارمة بشأن ملكية الملفات.
  • يشير Composer إلى أن امتدادًا مفقودًا (مثلاً fileinfo) : فعّل الامتداد عبر PHP Selector / MultiPHP INI Editor إن أمكن، وإلا فاطلب من الدعم.
  • تم استدعاء Composer باستخدام SAPI خاطئ : رسالة «Composer should be invoked via the CLI version of PHP not the CGI/FCGI SAPI» → استخدم إصدار CLI من PHP (مثلاً /usr/local/bin/ea-php82 composer install).
  • فشل عمليات الترحيل (Migrations) : تحقّق من معلومات اتصال قاعدة البيانات في .env، اختبر الاتصال عبر phpMyAdmin ونفّذ php artisan migrate --force في بيئة الإنتاج (أو استورد SQL إذا لم يكن لديك وصول SSH).
  • Scheduler / Cron الذي لا يعمل : استخدم المسار الكامل لثنائي PHP ولملف artisan artisan في مهمة Cron وتحقق من سجلات النظام أو سجلات Cron.

موارد داخلية مفيدة

إذا رغبتم أن نتولى نحن عملية النشر (التحقق من إصدار PHP، Composer، الأذونات وdocument root)، افتحوا تذكرة من خلال منطقة العميل مع ذكر النطاق وطريقة النشر المطلوبة.

توثيق مرجعي

  • كيفية تثبيت Laravel على cPanel — دعم cPanel
  • MultiPHP Manager لـ cPanel — وثائق cPanel
  • قواعد بيانات MySQL® — وثائق cPanel

تم الاطلاع على الوثائق في 17 أكتوبر 2026. قد تختلف الأدوات حسب استضافتك.