لمحة سريعة: Composer هو مدير التبعيات لمشاريع PHP. على cPanel، يجب تشغيل Composer من خلال سطر الأوامر (الطرفية Terminal أو عبر SSH) ويجب توفر بعض امتدادات وإعدادات PHP. اعتمادًا على نوع استضافتك، يمكنك تثبيت Composer على مستوى النظام (يتطلب صلاحية root) أو محليًا داخل مجلد مشروعك (مُوصى به على الاستضافة المشتركة).

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

  • الوصول عبر SSH أو عبر ميزة Terminal في لوحة cPanel (cPanel → Home → Advanced → Terminal). إذا كانت ميزة Terminal معطلة، فاطلب من مزود الاستضافة تفعيلها. لمعرفة كيفية الوصول إلى cPanel، راجع دليلنا الداخلي: كيفية الوصول إلى حسابي على cPanel.
  • إذا كنت تنوي تثبيت Composer ليكون متاحًا لجميع الحسابات: يتطلب ذلك وصولًا بصلاحية root root (VPS / خادم مخصّص). على استضافة مشتركة: ثبّت Composer محليًا في مجلد المستخدم الخاص بك (لا حاجة لصلاحية root).
  • امتدادات PHP المطلوبة : phar phar (متاحة عادةً)، و mbstring mbstring أو iconv iconv. تحقّق من تفعيلها أو قم بتفعيلها عبر PHP Selector أو MultiPHP (انظر : كيفية تغيير إصدار PHP والامتدادات).
  • توجيهات PHP المفيدة : allow_url_fopen = On allow_url_fopen = On و (للإصدارات القديمة جدًا) zend.detect_unicode = Off zend.detect_unicode = Off. إذا لم تتمكن من تعديل php.ini php.ini، فهناك حلول بديلة (انظر أدناه).
  • على الخوادم التي تعمل بنظام CloudLinux والمحمية بواسطة CageFS: يجب على المسؤول إتاحة الملف الثنائي الخاص بـ Composer لحسابات CageFS (الإجراء موضح أدناه).
قائمة cPanel: أيقونة Terminal لفتح الطرفية
افتح Terminal من داخل cPanel (Home > Advanced > Terminal) لتشغيل أوامر CLI.

اختيار الطريقة

طريقتان :

  1. التثبيت على مستوى النظام (root) — يقوم المسؤول بتثبيت Composer لجميع الحسابات (مفيد على VPS/خادم مخصّص).
  2. التثبيت المحلي (بدون صلاحيات root) — ثبّت Composer في مجلد المستخدم أو في مجلد المشروع الخاص بك. يُنصح بهذه الطريقة على خطط الاستضافة المشتركة.

الطريقة أ — التثبيت العام (بصلاحيات المسؤول root)

إجراء لجعل Composer متاحًا على مستوى النظام.

  1. سجّل الدخول عبر SSH بصفتك root : ssh [email protected] (استبدل example.com والمستخدم وفقًا لتكوينك).
  2. تحقّق من أن إصدار PHP لواجهة سطر الأوامر (CLI) المستخدم مع Composer يتضمّن phar و mbstring / iconv، وأن allow_url_fopen مفعل. يمكن للمسؤول تعديل هذه الخيارات عبر MultiPHP INI Editor أو EasyApache 4 إذا لزم الأمر.
    3. الوصول إلى محرّر MultiPHP INI في cPanel لتعديل خيارات PHP
    مثال: محرّر INI MultiPHP لتعديل توجيهات PHP المطبّقة على النطاق أو على واجهة CLI.
  3. حمّل وتحقق من مُثبّت Composer الرسمي، ثم ثبّته في /usr/local/bin : 
    cd /tmp
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
EXPECTED_SIG=$(php -r "echo trim(file_get_contents('https://composer.github.io/installer.sig'));")
php -r "if (hash_file('sha384', 'composer-setup.php') === '$EXPECTED_SIG') { echo 'Installer verified'.PHP_EOL; } else { echo 'Installer corrupt'.PHP_EOL; unlink('composer-setup.php'); exit(1); }"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php
    بعد التثبيت, /usr/local/bin/composer يجب أن يكون قابلاً للتنفيذ. (إذا لزم الأمر: chmod +x /usr/local/bin/composer .)
  4. تحقّق من التثبيت : composer --version.
  5. إذا كان الخادم يستخدم CloudLinux و CageFS، اجعل Composer متاحًا لحسابات CageFS: أنشئ ملف تكوين وقم بتحديث CageFS (يُنفَّذ الأمر بصلاحيات root): 
    cat > /etc/cagefs/conf.d/composer.cfg <<'EOF'
[composer]
comment=Composer
paths=/usr/local/bin/composer
EOF
cagefsctl --force-update
    تجعل هذه الخطوة الملف التنفيذي متاحًا للمستخدمين المحصورين داخل CageFS.

الطريقة B — تثبيت Composer محليًا (بدون صلاحيات root) — موصى به على الاستضافة المشتركة

قم بتثبيت Composer داخل مجلد مشروعك أو في مجلدك الشخصي وشغّله كمستخدم cPanel.

  1. افتح الطرفية (Terminal) في cPanel أو اتصل عبر SSH باستخدام حساب cPanel الخاص بك.
  2. انتقل إلى مجلد المشروع (مثلاً ~/public_html/mon-projet) : 
    cd ~/public_html/mon-projet
    طرفية cPanel مع الأمر cd public_html للوصول إلى مجلد الويب
    انتقل إلى جذر المشروع قبل تثبيت التبعيات.
  3. حمّل برنامج التثبيت وأنشئ composer.phar في المجلد الحالي: 
    php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"
# Résultat : composer.phar dans le répertoire courant
    شغّل Composer محليًا بواسطة php composer.phar أو أنشئ alias (الخطوة التالية).
  4. لتشغيل Composer كأمر عادي، هناك خياران بسيطان :
    1. إنشاء alias (مؤقت/للمستخدم) : 
      echo "alias composer='php ~/public_html/mon-projet/composer.phar'" >> ~/.bashrc
source ~/.bashrc
    2. أو نقله وجعله قابلاً للتنفيذ في ~/.local/bin أو ~/bin وإضافة هذا المجلد إلى PATH : 
      mkdir -p ~/bin
mv composer.phar ~/bin/composer
chmod +x ~/bin/composer
# si nécessaire, ajoutez au PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

تشغيل Composer عندما لا يمكنك تعديل php.ini

إذا لم يكن بإمكانك تحرير php.ini، فيمكنك فرض توجيهات PHP عبر سطر الأوامر : 

php -d allow_url_fopen=1 -d zend.detect_unicode=0 composer.phar install
ملاحظة : zend.detect_unicode ينطبق ذلك على إصدارات PHP القديمة جدًا؛ في الإصدارات الأحدث لم يعد هذا التوجيه موجودًا.

أوامر مفيدة

  • composer --version — يعرض إصدار Composer.
  • composer diagnose — أداة تشخيص ذاتية لاكتشاف مشكلات التكوين.
  • composer install — يثبت التبعيات المدرجة في composer.json ملف composer.json.
  • composer update — يحدّث التبعيات وفقًا للقيود.
  • composer self-update — يحدّث Composer نفسه (فقط للنسخة التي تديرها).
  • في حال حدوث خطأ متعلق بالذاكرة: 
    COMPOSER_MEMORY_LIMIT=-1 composer install

استكشاف الأخطاء وإصلاحها — الأخطاء الشائعة والحلول

1) « command not found »

السبب: الملف التنفيذي composer composer غير موجود في PATH PATH. الحلول:

  • إذا ثبتته على مستوى النظام: تأكد من أن /usr/local/bin /usr/local/bin مُدرَج في PATH PATH أو نفّذ مباشرةً /usr/local/bin/composer --version /usr/local/bin/composer --version.
  • إذا كان لديك نسخة محلية: أضِف المجلد الذي يحتوي على composer composer (مثلاً ~/bin ~/bin) إلى PATH PATH في الملف ~/.bashrc ~/.bashrc و نفّذ source ~/.bashrc source ~/.bashrc، أو أنشئ alias.

2) تحذير « Composer should be invoked via the CLI version of PHP, not the cgi-fcgi SAPI »

المعنى: المفسّر PHP الذي يستدعيه composer هذا يعني أن المفسّر المستدعى هو SAPI الخاص بخادم الويب (cgi/fcgi) وليس مفسّر سطر الأوامر (CLI). الحل: استدعِ صراحة مفسّر PHP الخاص بواجهة سطر الأوامر. مثال (استبدل رقم الإصدار): 

/opt/cpanel/ea-php74/root/usr/bin/php ~/bin/composer diagnose
إذا كانت استضافتك توفر عدة إصدارات من PHP عبر SCL، يمكنك استخدام scl enable ea-php74 'composer diagnose' (متاح فقط إذا كان SCL مثبتًا).

3) يستخدم Composer إصدارًا خاطئًا من PHP

السبب: php في متغير PATH PATH يشير إلى إصدار آخر. الحل: استدعِ الثنائي الكامل لواجهة سطر الأوامر (المسار المطلق) كما في المثال أعلاه، أو عدِّل الـ alias ليشير إلى ثنائي CLI الصحيح.

4) « تعذَّر على Composer العثور على ملف composer.json »

تأكد من أنك في المجلد الذي يحتوي على composer.json (جذر المشروع) قبل تشغيل composer install.

5) أخطاء في الكتابة داخل vendor/ أو رفض الأذونات

تحقّق من أنك تشغّل Composer بصفتك المستخدم صاحب ملكية ملفات الويب (لا تُشغّل Composer كمستخدم root على مشروع ويب). صحِّح الملكية إذا لزم الأمر: 

chown -R votre_user:votre_user vendor/

6) مشاكل متعلقة بـ CageFS (CloudLinux)

إذا كان CageFS يمنع الوصول إلى ثنائي Composer، فاطلب من المسؤول إضافة Composer إلى تكوين CageFS وتنفيذ cagefsctl --force-update (انظر الإجراء أعلاه).

أفضل الممارسات والأمان

  • لا تُشغّل composer install أو composer update بصفتك root على مشروع ويب: قد تقوم بعض الحزم بتشغيل سكربتات ما بعد التثبيت التي تُنفَّذ بنفس الصلاحيات.
  • للموقع في بيئة الإنتاج: استخدم composer install --no-dev --optimize-autoloader واحتفظ بـ composer.lock في نظام إدارة الإصدارات الخاص بك لضمان تبعيات قابلة لإعادة الإنتاج.
  • إذا كنت تقوم بأتمتة عمليات التثبيت (CI/CD)، فقلّل المخاطر باستخدام --no-plugins --no-scripts عند الضرورة وتحقق من الحزم المستوردة.

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

الموارد والمراجع

هل تحتاج إلى مساعدة؟ إذا كنتم تفضلون أن يقوم فريقنا بتنفيذ التثبيت على VPS/خادم مخصّص أو التحقق من إعدادات CageFS، فافتحوا تذكرة دعم مع توضيح إصدار PHP المستهدف وما إذا كان الخادم يستخدم CloudLinux/CageFS. على استضافة مشتركة، يبقى التثبيت محليًا داخل مجلد مشروعكم الطريقة الموصى بها.

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

  • كيفية إعداد Composer لـ PHP — وثائق cPanel & WHM
  • كيفية تثبيت Composer على cPanel إصدار 130 وما فوق — دعم cPanel

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