Установка PHP Composer на Debian 11

Логотип Composer и окружение терминала

Зачем нужен Composer

Composer — это менеджер зависимостей для PHP. Он читает файл composer.json в корне проекта и автоматически загружает библиотеки, определённые в нём. Composer упрощает управление пакетами, фиксирует версии в composer.lock и помогает воспроизводимости сборки.

Определение: Зависимость — сторонняя библиотека, которую ваш проект требует для работы (одна строка).

Важно: Composer не устанавливает PHP; он управляет пакетами PHP.

Содержимое этого руководства

Быстрая проверка требований
Пошаговая установка на Debian 11 (глобально и в проект)
Проверка и обновление Composer
Безопасная проверка установщика
Тестирование на примере проекта
Решение типичных проблем и отладка
Альтернативы и рекомендации для продакшна
Роли и чеклисты

Требования

Доступ к терминалу Linux (локально или через SSH).
Права root или sudo для глобальной установки.

Если вы используете виртуальную машину или хостинг с ограничениями, можно установить Composer локально в папку проекта.

Шаг 1 — Обновление системы и установка PHP

Откройте терминал (Ctrl+Alt+T) и обновите список пакетов:

sudo apt-get update

Затем обновите установленные пакеты:

sudo apt-get upgrade

Установите PHP и рекомендованные модули, которые часто требуются пакетам Composer:

sudo apt install php -y

sudo apt install curl git unzip wget php-common php-zip php-cli php-xml php-gd php-mysql php-bcmath php-imap php-curl php-intl php-mbstring -y

Примечание: набор модулей можно адаптировать под конкретный проект. Например, для работы с базой данных MySQL нужен php-mysql.

Шаг 2 — Скачивание установщика Composer

Скачайте скрипт установщика в текущую папку. Можно использовать php-скрипт, curl или wget.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

Или:

wget -O composer-setup.php https://getcomposer.org/installer

Важно: перед запуском установщика рекомендуется проверить его целостность (см. раздел Безопасность).

Безопасная проверка установщика

Чтобы избежать запуска поддельного инсталлятора, сравните контрольную сумму загруженного файла с ожидаемой сигнатурой, которую предоставляет официальный сайт.

Пример шагов (не содержит фиксированных хэшей):

EXPECTED_SIG=$(wget -q -O - https://composer.github.io/installer.sig)
ACTUAL_SIG=$(php -r "echo hash_file('sha384', 'composer-setup.php');")

if [ "$EXPECTED_SIG" = "$ACTUAL_SIG" ]; then
  echo 'Сигнатура совпадает — продолжаем установку.'
else
  echo 'Сигнатура не совпадает — удаляю файл.'
  rm composer-setup.php
  exit 1
fi

Этот подход получает актуальную сигнатуру с официального сайта и сверяет её с загруженным файлом.

Шаг 3 — Установка Composer (глобально или в проект)

Есть два распространённых варианта установки:

Глобальная установка — удобна, если на системе много проектов и вы хотите вызывать composer из любой директории.
Локальная установка в проект — подходит для shared‑hosting или когда требуется изолированная версия.

Глобальная установка (поместит исполняемый файл в /usr/local/bin):

php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Сделайте файл исполняемым:

chmod +x /usr/local/bin/composer

Теперь composer должен быть доступен в PATH и запускаться из любой папки.

Локальная установка в проекте (пример):

cd /path/to/the/specific/project/php-application && mkdir -p bin

php composer-setup.php --install-dir=bin --filename=composer

chmod +x bin/composer

При локальной установке вызывайте composer как ./bin/composer или добавьте bin в PATH вашего проекта.

Шаг 4 — Проверка установки

Выполните:

composer -v

Composer обычно предупреждает при запуске от root — такое предупреждение можно проигнорировать, однако запускать Composer под root в продакшене не рекомендуется.

Если вывод показывает версию, установка успешна. Пример корректного вывода: версия и список плагинов.

Информация об установленном Composer

Шаг 5 — Обновление Composer

Чтобы обновить Composer до последней версии используйте:

composer self-update

Если у вас последняя версия — Composer сообщит об этом. Если доступно обновление, он спросит о подтверждении.

Шаг 6 — Тестовое использование в проекте

Создайте тестовый каталог и инициализируйте пример:

mkdir example-project && cd example-project

Найдите пакет на Packagist.org и установите его. В примере используем sebastian/comparator:

composer require sebastian/comparator

Composer загрузит пакет и его зависимости. После успешной установки в каталоге появятся:

composer.json — метаданные проекта и список зависимостей;
composer.lock — зафиксированные версии зависимостей;
vendor — директория с загруженными пакетами.

Composer добавляет зависимости и генерирует vendor

Чтобы увидеть файлы в каталоге:

ls

Ожидаемый результат: composer.json, composer.lock, vendor.

Типичные ошибки и как их исправить

Проблема: “command not found” при вводе composer
- Проверьте, что путь установки (/usr/local/bin или другой) в PATH. Для этого выполните echo $PATH и ls -l /usr/local/bin/composer.
Проблема: Права доступа (Permission denied)
- Проверьте права на файл composer и директории. Для глобальной установки используйте sudo при установке, но избегайте запуска composer как root в процессе работы проекта.
Проблема: PHP не найден или неверная версия
- Убедитесь, что php установлен и доступен: php -v. Некоторые пакеты требуют PHP 7.2+ или 8.x — проверьте требования пакета.
Проблема: SSL/TLS ошибки при загрузке пакетов
- Убедитесь, что установлен пакет ca-certificates и что системное время синхронизировано (timedatectl).

Критерии приёмки

Composer запускается и возвращает версию: composer -v
Успешная установка пакета: composer require завершилась без ошибок
В каталоге проекта появились composer.json, composer.lock и vendor
Обновление через composer self-update не вызывает ошибок

Безопасность и хорошая практика

Не запускайте composer как root в рабочем окружении.
Фиксируйте версии в composer.lock для воспроизводимости сборки.
Храните composer.lock в системе контроля версий (git).
Периодически обновляйте зависимости и проверяйте совместимость.
Для CI/CD используйте phar-версию Composer или зафиксированную версию, если нужна стабильность.

Альтернативные подходы

Использовать phar-архи для запуска Composer без установки в систему.
В CI запускать composer install –no-dev –prefer-dist для оптимальной сборки артефактов.
Для изоляции окружения применять контейнеры Docker с заранее собранным образом PHP+Composer.

Роли и чеклисты

Для разработчика:

Убедиться, что composer.json корректен и содержит необходимые зависимости.
Выполнить composer install и проверить, что тесты проходят.

Для системного администратора:

Установить PHP и необходимые расширения.
Установить Composer глобально, если нужно.
Настроить резервное копирование и мониторинг процессов.

Мини‑методология: Быстрая установка в 6 шагов

apt update && apt upgrade
Установить php и модули
Скачайте composer-setup.php
Проверить сигнатуру установщика
Установить глобально или локально
composer -v и composer require для проверки

Примеры команд — шпаргалка

Установить глобально:

php composer-setup.php --install-dir=/usr/local/bin --filename=composer
chmod +x /usr/local/bin/composer

Установить локально в проект:

php composer-setup.php --install-dir=bin --filename=composer
chmod +x bin/composer

Обновить Composer:

composer self-update

Установить зависимость в проект:

composer require vendor/package

Установить зависимости по composer.lock:

composer install

Обновить зависимости:

composer update

Тесты и критерии приёмки (короткая проверка)

Тест 1: composer -v возвращает версию — успех.
Тест 2: composer require sebastian/comparator — создаёт vendor — успех.
Тест 3: composer install на другом клоне репозитория восстанавливает те же версии из composer.lock — успех.

Совместимость и миграция

Инструкция применима к Debian 11 и другим Debian-подобным дистрибутивам (Ubuntu и т.д.).
При переносе между машинами убедитесь, что версии PHP совпадают или совместимы с зависимостями.

Короткий чеклист для CI/CD

Добавьте composer install –prefer-dist –no-interaction –no-progress
Кешируйте ~/.composer/cache или vendor (в зависимости от CI провайдера)
Используйте composer.lock для воспроизводимости

Часто задаваемые вопросы

Нужно ли устанавливать Composer глобально?

Зависит от сценария: глобальная установка удобна для системного администрирования и разработки на одной машине. Локальная установка предпочтительна в shared-hosting и когда требуется версия Composer, специфичная для проекта.

Как проверить целостность установщика?

Скачать ожидаемую сигнатуру с https://composer.github.io/installer.sig и сравнить её с hash_file(‘sha384’, ‘composer-setup.php’).

Можно ли запускать composer под root?

Можно, но не рекомендуется. Для безопасности лучше запускать от обычного пользователя и использовать sudo только при установке.

Итог

Вы установили Composer на Debian 11, научились безопасно загружать и проверять установщик, различать глобальную и локальную установку, обновлять Composer и тестировать работу на примере пакета. Для продакшена используйте composer.lock, не запускайте Composer под root и интегрируйте установку в CI.

Important: если остались вопросы, опишите окружение, вывод ошибок и версии PHP/Composer для более точной помощи.