مقدمة

يصف هذا الدليل طريقة موثوقة لنشر تطبيق Laravel في بيئة الإنتاج على استضافة مشتركة مزودة بـ cPanel. يغطي التحضير المحلي، رفع الملفات (File Manager أو Git/SSH)، وإدارة Document Root لخدمة مجلد public/ فقط public/، إنشاء قاعدة البيانات، تنفيذ أوامر Artisan/Composer، وإعداد الـ scheduler. إذا كانت باقتك لا تمنحك وصولًا إلى Terminal/SSH فستُوضَّح بدائل.

قبل البدء — المتطلبات المسبقة

  • الوصول إلى لوحة تحكم cPanel للحساب.
  • إصدار PHP المطلوب بحسب إصدار Laravel الذي تستخدمه — راجع الوثائق الرسمية لـ Laravel. (مثال: Laravel 10 يتطلب PHP ≥ 8.1.)
  • الامتدادات الشائعة المطلوبة لـ PHP من قِبل Laravel: OpenSSL، PDO، Mbstring، Tokenizer، Ctype، JSON، BCMath، Fileinfo، XML، ZIP — تحقق من تفعيلها عند الحاجة.
  • وجود Composer على الخادم أو إمكانية تشغيل Composer محليًا ثم رفع المجلد vendor/ vendor/.
  • الوصول إلى أداة MySQL Databases في cPanel لإنشاء قاعدة البيانات والمستخدم.
  • إمكانية تعديل Document Root (جذر النطاق/النطاق الفرعي) ليوجهه إلى /.../projet/public /.../projet/public، أو إمكانية نسخ/تكييف محتوى public/ public/ إلى public_html public_html.
  • الوصول إلى Terminal/SSH (مستحسن) أو إمكانية استخدام أداة Git Version Control في cPanel.
  • تحضير ملف .env .env لبيئة الإنتاج: APP_ENV=production APP_ENV=production، APP_DEBUG=false APP_DEBUG=false، APP_KEY APP_KEY، وإعدادات قاعدة البيانات.
  • حصة القرص وحدود PHP (memory_limit، max_execution_time) كافية لتثبيت التبعيات وتنفيذ المهام.

ملخص الطريقة

  1. تحضير نسخة الإنتاج محليًا (التبعيات، مفتاح APP_KEY، بناء الأصول).
  2. رفع المشروع إلى الخادم (File Manager أو Git/SSH).
  3. توجيه النطاق/النطاق الفرعي إلى /chemin/vers/projet/public /chemin/vers/projet/public أو تعديل ملف public/index.php public/index.php إذا تعذّر تغيير جذر المستند.
  4. إنشاء قاعدة بيانات MySQL وتحديث ملف .env .env.
  5. تشغيل عمليات الترحيل (migrations)، ضبط الأذونات وتكوين المجدول (cron).

خطوات مفصّلة

1) إعداد مشروعك محليًا

على جهاز التطوير الخاص بك:

  • تثبيت التبعيات في وضع الإنتاج: 
    composer install --no-dev --optimize-autoloader
  • توليد مفتاح التطبيق ونسخه إلى ملف .env .env : 
    php artisan key:generate --show
  • بناء الأصول (Vite / Mix) حسب المشروع: 
    npm ci
npm run build
  • احذف الملفات غير الضرورية (مثل node_modules/) node_modules/قبل الأرشفة إذا كنت تستخدم رفع ZIP.

نصيحة: إذا لم توفر استضافتك Composer، فقم بتشغيل composer install محليًا ثم ارفع مجلد vendor/ vendor/.

2) اختيار البنية على جانب الخادم (جذر المستند)

استراتيجيتان:

أ — الطريقة النظيفة (موصى بها إن أمكن)

أنشئ مجلدًا لمشروعك (مثلاً /home/username/monprojet) /home/username/monprojetوقم بتوجيه جذر النطاق أو النطاق الفرعي مباشرةً إلى /home/username/monprojet/public /home/username/monprojet/public.

إنشاء نطاق إضافي بمجلد جذر منفصل في cPanel

مثال: في cPanel، اختر جذر مستند منفصل لنطاق تابع (addon domain) أو لنطاق فرعي ثم ضع ملفاتك في هذا المجلد.

إذا احتجت مساعدة لإنشاء نطاق فرعي أو لتعديل جذر المستند، راجع: كيفية إضافة نطاق فرعي في cPanel.

ب — إذا لم تتمكن من تغيير جذر المستند

انسخ محتوى public/ إلى public_html/ وقم بتعديل مسارات index.php لتشير إلى مجلد التطبيق الموجود خارج public_html. مثال (عناصر نائب):

// public_html/index.php (exemple si le projet est dans ../monprojet)
require __DIR__ . '/../monprojet/vendor/autoload.php';
$app = require_once __DIR__ . '/../monprojet/bootstrap/app.php';

مهم — احمِ الملف .env : يجب أن يظل خارج public_htmlلمنع الوصول المباشر إلى الملف، أضف، إن لزم الأمر، قاعدة Apache : 

<Files ".env">
    Require all denied
</Files>

(على الخوادم القديمة جدًا: استخدم Deny from all وفقًا لتكوين Apache.)

3) رفع الملفات

الخيار أ — مدير الملفات (File Manager)

أنشئ أرشيف ZIP للمشروع (بدون node_modules/), ثم: cPanel → File Manager → انتقل إلى المجلد الوجهة و Upload → Extract.

الوصول إلى مدير الملفات من لوحة تحكم cPanel

رفع واستخراج أرشيف ZIP عبر مدير الملفات.

الخيار ب — SSH / Git (مستحسن إذا كان متوفرًا)

إذا كانت باقتك تتيح SSH أو الطرفية (Terminal) في cPanel، فاستنسخ المستودع واستخدم Composer على الخادم: 

git clone git@repo.exemple:monprojet.git /home/username/monprojet
cd /home/username/monprojet
composer install --no-dev --optimize-autoloader
npm ci && npm run build

الوصول إلى الطرفية (Terminal) من لوحة تحكم cPanel

الطرفية المدمجة: متاحة فقط إذا فعّلها مزود الاستضافة. إذا فضّلت استخدام Git عبر الواجهة، راجع إدارة مستودعات Git في cPanel.

4) إنشاء قاعدة البيانات والتهيئة .env

في cPanel → MySQL Databases : أنشئ قاعدة البيانات، أنشئ المستخدم و Add User To Database (صلاحيات ALL). سجّل الأسماء الكاملة (بادئة cPanel) وكلمة المرور.

الوصول إلى قواعد بيانات MySQL من لوحة تحكم cPanel

إنشاء قاعدة بيانات ومستخدم MySQL من واجهة cPanel.

حرّر ملف .env .env (في جذر المشروع، خارج public_html public_html) : 

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nom_de_votre_base
DB_USERNAME=nom_utilisateur
DB_PASSWORD=mot_de_passe
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:...

5) تشغيل عمليات الترحيل (migrations) وتحسين الأداء

إذا كان لديك SSH/الطرفية، نفّذ من جذر المشروع: 

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

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

  • نفّذ composer install composer install محليًا ثم ارفع المجلد vendor/. vendor/.
  • إذا كنت بحاجة لتشغيل أوامر Artisan مؤقتًا دون SSH، يمكنك إنشاء سكربت PHP صغير ينفّذ الأمر على الخادم — حل أخير ومؤقت: احذف السكربت فورًا بعد الاستخدام وقم بتقييد الوصول إليه.

6) الأذونات

يجب أن تكون المجلدات التالية قابلة للكتابة بواسطة PHP : storage و bootstrap/cache. 

chmod -R 775 storage bootstrap/cache
عبر Terminal :

في بعض الاستضافات المشتركة يُطلب استخدام أذونات 755 — عدّل وفقًا لسياسة المزود. يمكنك أيضًا تعديل الأذونات من خلال مدير الملفات (File Manager).

خانات القراءة والكتابة والتنفيذ لأذونات ملف في cPanel

7) تكوين إصدار PHP والحدود في cPanel → MultiPHP Manager memory_limit (أو PHP Selector)، حدِّد إصدار PHP المطلوب لتطبيق Laravel الخاص بك (مثلاً PHP 8.1+ لـ Laravel 10). اضبط، إذا لزم الأمر، max_execution_time و

عبر MultiPHP INI Editor.

اختيار النطاق وإصدار PHP في MultiPHP Manager على cPanel

اختر إصدار PHP المناسب، وإذا لزم الأمر، عدّل الخيارات في محرّر INI. تحقّق أيضًا من تفعيل الملحقات المذكورة في بداية هذا الدليل. لمعرفة كيفية تغيير إصدار PHP :

كيف أغيّر إصدار PHP والملحقات على استضافتي cPanel؟

8) المجدول والمهام المجدولة (cron) php artisan schedule:run لتشغيل مجدول Laravel، أنشئ مهمة cron (cPanel → Cron Jobs) التي تُنفّذ 

* * * * * /usr/bin/php /home/username/chemin/vers/projet/artisan schedule:run >> /dev/null 2>&1

كل دقيقة :

نموذج إعداد الجدولة وأمر مهمة Cron في cPanel — جدولة مهمة Cron

إنشاء مهمة cron لتشغيل مجدول Laravel.

* * * * * /usr/bin/php /home/username/chemin/vers/projet/artisan queue:work --once --tries=3 >> /dev/null 2>&1

يُشغّل عاملًا (worker) يعالج المهام ثم يتوقف؛ مناسب إذا لم يكن تدفّق المهام كثيفًا.

التحقّقات النهائية

  • قم بزيارة نطاقك: الصفحة الرئيسية لتطبيق Laravel تؤكّد أن عملية النشر ناجحة.
  • خطأ 500: راجع أولاً storage/logs/laravel.log ثم سجلات أخطاء cPanel (Errors / Raw Access). انظر: كيف أطلع على سجلات الوصول إلى موقعي في cPanel؟
  • ظهور شفرة PHP بدلاً من الصفحة: يعني أن الخادم لا ينفّذ PHP في جذر المستندات (Document Root) هذا — تحقّق من إصدار PHP والمُعالج (PHP handler) وإعداد Document Root.
  • إذا فشل الاتصال بقاعدة البيانات: تحقق من بادئة اسم قاعدة البيانات واسم المستخدم (غالبًا ما يضيف cPanel بادئة).

القيود الشائعة على الاستضافة المشتركة

  • غياب (أو ندرة) العمليات المستمرة: Supervisor والـ workers طويلة التشغيل عادةً غير متاحة.
  • نادراً ما تدعم الاستضافة المشتركة WebSockets وخدمات الوقت الحقيقي.
  • موارد CPU/RAM محدودة: راقِب الاستخدام وحسّن التخزين المؤقت وتجميع الأصول (assets).
  • صلاحيات root وإعدادات الخادم مقيدة — لاحتياجات متقدمة (Redis مخصّص، قوائم انتظار كثيفة، WebSockets) يُفضّل استخدام VPS أو حل مُدار.

استكشاف الأعطال السريع

خطأ 500 — راجع storage/logs/laravel.logتحقّق من الأذونات (storage، bootstrap/cache)، وإصدار PHP والامتدادات المفقودة. Composer غير متوفّر نفّذ Composer محليًا ثم ارفع vendor/أو اطلب من الدعم تفعيل Composer/Terminal لحسابك. صفحة 404 / محتوى غير صحيح تحقّق من Document Root للنطاق/النطاق الفرعي وتأكد أنه يشير إلى /.../public أو أن public_html/index.php يشير بشكل صحيح إلى autoload وbootstrap. APP_KEY مفقودة أنشئ المفتاح محليًا (php artisan key:generate --show) ثم ضع المفتاح في .env بصيغة APP_KEY=base64:....

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

ملخص

يمكن نشر تطبيق Laravel على استضافة مشتركة تعمل بنظام cPanel إذا تم الالتزام بعدة قواعد: تقديم محتوى مجلد <code>public/</code> فقط public/، والتحقق من إصدار PHP والامتدادات، وتثبيت التبعيات (Composer)، وحماية ملف <code>.env</code>. .envيسهّل الوصول إلى SSH/الطرفية وإمكانية تعديل Document Root العملية بشكل كبير. للمتطلبات التي تحتاج إلى عمليات مستمرة (مثل workers أو WebSockets)، فكّر في استخدام VPS أو خدمة مُدارة.

المصادر: الوثائق الرسمية لـ Laravel لمتطلبات النظام (انظر «المصادر» أدناه) ووثائق/قاعدة المعرفة cPanel للأدوات المذكورة.

الوثائق المرجعية

تمت مراجعة الوثائق في 28 أكتوبر 2026. قد تختلف الأدوات حسب مزود الاستضافة.