Composer چیست و چرا برای PHP لازم است؟

در گذشته بسیاری از پروژه‌های PHP با کپی دستی فایل‌های کتابخانه‌ها راه‌اندازی می‌شدند. این روش در پروژه‌های کوچک شاید ساده به نظر برسد، اما در پروژه‌های واقعی باعث مشکل نسخه، ناسازگاری کتابخانه‌ها، سخت شدن آپدیت و خطاهای امنیتی می‌شود. Composer این مشکل را با فایل‌های composer.json و composer.lock حل می‌کند.

فایل composer.json مشخص می‌کند پروژه به چه پکیج‌هایی نیاز دارد. فایل composer.lock نسخه دقیق پکیج‌هایی را نگه می‌دارد که قبلاً نصب و تست شده‌اند. به همین دلیل وقتی پروژه را روی سرور دیگری منتقل می‌کنید، Composer می‌تواند همان نسخه‌های تست‌شده را نصب کند و احتمال ناسازگاری را کم کند.

آیا Composer قدیمی شده؟ چه چیزهایی را نباید آموزش اصلی قرار دهیم؟

خود Composer قدیمی یا بی‌استفاده نشده است؛ هنوز یکی از ابزارهای اصلی اکوسیستم PHP است. اما بعضی روش‌ها و نسخه‌ها دیگر انتخاب خوبی برای آموزش عمومی نیستند.

پیش‌نیازهای نصب Composer روی سرور لینوکس

قبل از نصب، باید مطمئن شوید PHP CLI، ابزارهای دانلود و افزونه‌های رایج PHP روی سرور فعال هستند. در سرورهای کنترل‌پنل‌دار ممکن است نسخه PHP وب‌سایت با نسخه PHP خط فرمان متفاوت باشد؛ این موضوع یکی از پرتکرارترین علت‌های خطاهای Composer است.

بررسی نسخه PHP و مسیر اجرایی

php -v
which php
php -m | sort | egrep 'curl|openssl|zip|mbstring|json|phar|iconv|fileinfo' || true

نصب پیش‌نیازها در Ubuntu و Debian

apt update
apt install -y php-cli php-curl php-zip php-mbstring php-xml php-json unzip curl git

نصب پیش‌نیازها در AlmaLinux، Rocky Linux و CentOS

dnf install -y php-cli php-curl php-zip php-mbstring php-xml unzip curl git
# اگر dnf در دسترس نبود:
yum install -y php-cli php-curl php-zip php-mbstring php-xml unzip curl git

نصب Composer با SSH به روش امن

روش امن این است که نصب‌کننده Composer را از سایت رسمی دریافت کنید، checksum آن را از منبع رسمی بررسی کنید و بعد فایل composer.phar را بسازید. این روش برای مقاله‌های آموزشی ماندگار بهتر از کپی کردن checksum ثابت است.

cd /tmp
EXPECTED_CHECKSUM="$(php -r 'copy("https://composer.github.io/installer.sig", "php://stdout");')"
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"

if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
  >&2 echo 'ERROR: Invalid installer checksum'
  rm -f composer-setup.php
  exit 1
fi

php composer-setup.php --quiet
rm -f composer-setup.php
php composer.phar --version

اگر خروجی نسخه Composer را دیدید، نصب محلی انجام شده است و فایل composer.phar در همان مسیر قرار دارد.

نصب Composer به صورت Global

برای اینکه بتوانید در هر مسیر فقط دستور composer را اجرا کنید، فایل composer.phar را به مسیر قابل اجرا منتقل کنید.

sudo mv /tmp/composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer
composer --version

دستورهای مهم Composer که هر کاربر باید بداند

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

مشکل چند نسخه PHP در سرور و کنترل‌پنل‌ها

یکی از رایج‌ترین مشکلات کاربران این است که سایت با PHP 8.2 اجرا می‌شود، اما Composer در SSH با PHP 7.4 یا PHP 8.0 اجرا می‌شود. نتیجه آن خطاهایی مثل ناسازگاری نسخه PHP، نبود ext-zip، ext-curl یا ext-intl است.

بررسی مسیرهای PHP

which php
php -v
ls -lah /usr/local/bin/php /usr/bin/php 2>/dev/null || true
find /usr/local -type f -name php 2>/dev/null | head -n 30

اجرای Composer با نسخه خاص PHP

# نمونه عمومی، مسیر PHP شما ممکن است متفاوت باشد
/usr/local/bin/php /usr/local/bin/composer install

# در بعضی سرورهای cPanel مسیرها شبیه این هستند
/opt/cpanel/ea-php82/root/usr/bin/php /usr/local/bin/composer install

# در بعضی سرورهای OpenLiteSpeed/CyberPanel مسیر PHP CLI می‌تواند متفاوت باشد
/usr/local/lsws/lsphp82/bin/php /usr/local/bin/composer install

اگر پروژه شما Laravel یا یک اسکریپت PHP حساس است، همیشه اول نسخه PHP CLI را با نیاز پروژه تطبیق دهید.

خطاهای رایج Composer و راه‌حل‌ها

خطای ۱: Your requirements could not be resolved to an installable set of packages

این خطا یعنی نسخه PHP، نسخه پکیج‌ها یا وابستگی‌های پروژه با هم سازگار نیستند. ابتدا نسخه PHP و محتوای composer.json را بررسی کنید.

php -v
composer why-not php 8.2 || true
composer diagnose

خطای ۲: ext-zip، ext-curl، ext-intl یا ext-mbstring نصب نیست

این خطا معمولاً یعنی افزونه موردنیاز روی همان PHP CLI که Composer با آن اجرا شده فعال نیست.

php -m | egrep 'zip|curl|intl|mbstring|xml|fileinfo' || true
php --ini

بعد از نصب افزونه، دوباره با همان PHP تست کنید. اگر چند نسخه PHP دارید، نصب افزونه روی نسخه اشتباه مشکل را حل نمی‌کند.

خطای ۳: Allowed memory size exhausted

در پروژه‌های بزرگ، حل وابستگی‌ها ممکن است حافظه بیشتری بخواهد. ابتدا علت را بررسی کنید، اما برای اجرای موقت می‌توانید محدودیت حافظه Composer را افزایش دهید.

COMPOSER_MEMORY_LIMIT=-1 composer install
# یا:
php -d memory_limit=-1 /usr/local/bin/composer install

خطای ۴: proc_open disabled یا توابع PHP غیرفعال هستند

روی برخی هاست‌ها یا سرورهای سخت‌گیرانه، توابعی مثل proc_open در php.ini غیرفعال شده‌اند. Composer برای بعضی عملیات‌ها به این توابع نیاز دارد. باید php.ini نسخه CLI بررسی شود.

php --ini
php -i | grep disable_functions

خطای ۵: The zip extension and unzip command are both missing

Composer برای دانلود و استخراج پکیج‌ها به zip extension یا دستور unzip نیاز دارد.

apt install -y unzip php-zip
# یا در AlmaLinux/Rocky:
dnf install -y unzip php-zip

خطای ۶: SSL certificate problem یا خطای CA

این خطا معمولاً از قدیمی بودن بسته‌های CA یا اختلال در TLS می‌آید. راه‌حل درست، خاموش کردن secure-http نیست؛ باید CA certificates را به‌روز کنید.

apt install -y ca-certificates
update-ca-certificates

# AlmaLinux/Rocky/CentOS
dnf install -y ca-certificates
update-ca-trust

خطای ۷: composer update سایت را خراب کرد

دستور update نسخه وابستگی‌ها و composer.lock را تغییر می‌دهد. در سرور اصلی، به‌خصوص برای Laravel، WHMCS یا فروشگاه‌های فعال، بدون بکاپ و تست اجرا نشود.

# در production معمولاً این امن‌تر است:
composer install --no-dev --optimize-autoloader

خطای ۸: اجرای Composer با root

اگر Composer را با root اجرا می‌کنید، دقت کنید مالکیت فایل‌های پروژه به هم نریزد. در پروژه‌های کاربرمحور بهتر است Composer با همان کاربر مالک فایل‌های سایت اجرا شود.

pwd
ls -ld . vendor composer.json composer.lock 2>/dev/null || true
whoami

چک‌لیست امن قبل از اجرای Composer روی پروژه واقعی

• از فایل‌های پروژه و دیتابیس بکاپ بگیرید.
• نسخه PHP CLI را با نیاز پروژه تطبیق دهید.
• اگر composer.lock وجود دارد، روی سرور اصلی از composer install استفاده کنید، نه update.
• برای production از –no-dev و –optimize-autoloader استفاده کنید.
• بعد از نصب، سطح دسترسی و مالکیت فایل‌های vendor را بررسی کنید.
• اگر پروژه فعال است، تغییرات را اول روی محیط تست اجرا کنید.
• از –ignore-platform-reqs فقط وقتی استفاده کنید که دقیقاً می‌دانید چه ریسکی دارد.

جمع‌بندی

Composer هنوز یکی از ابزارهای ضروری برای پروژه‌های PHP است؛ اما روش نصب و استفاده از آن باید به‌روز، امن و متناسب با نسخه PHP سرور باشد. برای پروژه‌های جدید، Composer 2 را مبنا قرار دهید، نصب‌کننده را از منبع رسمی و با بررسی checksum اجرا کنید، روی production به‌جای update بی‌احتیاط از install بر اساس composer.lock استفاده کنید و قبل از هر تغییر مهم، نسخه PHP، افزونه‌ها و بکاپ را بررسی کنید. با رعایت همین چند اصل، بیشتر خطاهای رایج مثل ext-zip، memory limit، SSL certificate، platform requirements و خراب شدن vendor قابل پیشگیری هستند.