Composer: всё, что нужно знать о системе управления зависимостями в PHP

В проектах на PHP, будь то простые сайты, блоги или крупные системы с сотнями микросервисов, часто используется сторонний код. Например, библиотеки для формирования HTTP-запросов, работы с видео и изображениями, геолокацией и так далее. Это ускоряет разработку приложения и позволяет разработчикам не тратить время на задачи, которые уже решили другие программисты.

Несмотря на множество очевидных преимуществ, у такого подхода есть свои проблемы: часто сторонний код тоже использует функции других библиотек, и для безопасной разработки нужно быть уверенным в том, что эти библиотеки установлены на вашем компьютере. В мире PHP с этим (и не только) помогает утилита Composer, о которой и поговорим далее.

Содержание

• Что такое Composer
• Как установить Composer
• Синтаксис composer.json
• Основные команды Composer

Что такое Composer

Composer — это бесплатная программа, которая позволяет легко устанавливать, удалять и обновлять зависимости в проектах на PHP.

Зависимости — это любые внешние компоненты, которые используются в проекте: библиотеки, фреймворки, базы данных, CMS и так далее. Например, если вам нужно внедрить в проект функцию для хеширования паролей, можно не писать её с нуля, а использовать библиотеку — то есть добавить в проект зависимость.

Проблема в том, что по мере роста числа зависимостей работать с ними становится всё сложнее. Например, чтобы обновить библиотеку, вам придётся идти на сайт разработчика, скачивать архив и подключать его в проект. А если после обновления изменится сигнатура функций библиотеки или структура пространств имён, то проект и вовсе «рассыпется». Придётся исследовать исходный код и переписывать модули, в которых задействованы проблемные функции.

Поэтому разработчики используют менеджеры зависимостей, к коим и относится Composer.

Менеджер зависимостей решает следующие задачи:

• Скачивает зависимости из центрального репозитория и других источников (опционально).
• Формирует список зависимостей, необходимых для работы проекта.
• Обновляет их.
• Фиксирует стабильные версии библиотек и фреймворков, спасая разработчиков от неожиданной поломки проекта после обновления.
• Упрощает автозагрузку классов.

Теперь коротко по каждому пункту.

Быстрое скачивание пакетов

Конечно, никто не запрещает скачивать пакеты командой git clone <имя_пакета> из GitHub. Однако этот способ влечёт за собой серьёзные проблемы, о которых мы поговорим чуть ниже.

До Composer для этих целей использовали другой репозиторий и одноимённый менеджер — PEAR (PHP Extension and Application Repository). Но у PEAR был ряд недостатков:

• все пакеты устанавливались глобально, то есть нельзя было использовать разные версии для разных проектов;
• каждый класс должен был решать уникальную задачу, из-за чего было практически невозможно добавлять альтернативные решения;
• чтобы пакет попал в PEAR, он должен был набрать достаточное количество голосов в сообществе.

К началу 2010-х PEAR перестал удовлетворять потребности PHP-разработчиков и в сообществе встал вопрос о новом менеджере зависимостей.

Появившийся в 2012 году Composer решал обозначенные проблемы. Он устанавливает пакеты на уровне проекта (в папку vendor) и позволяет поставщикам свободно добавлять библиотеки в репозиторий. По умолчанию Composer получает пакеты из центрального хранилища пакетов Packagist, но вы можете указать и другие источники в файле конфигурации.

Автоматическое разрешение дерева зависимостей

Управление зависимостями не сводится к одному лишь скачиванию необходимого кода. Нельзя просто клонировать репозиторий в папку libs и подключить его. Практически у каждого пакета есть свой ряд зависимостей, у которых, в свою очередь, есть свой и так далее. Распутывать этот клубок довольно утомительно.

Рассмотрим проблему на примере популярной библиотеки Guzzle для отправки HTTP-запросов.

Клонируем репозиторий в папку проекта:

git clone https://github.com/guzzle/guzzle.git

Теперь у нас есть папка guzzle с исходниками и служебными файлами, но пользы от неё пока мало. При попытке инициализировать объект класса Client PHP ругается, что не нашёл некоторые классы:

require_once "guzzle/src/Client.php";
$newGuzzle = new \GuzzleHttp\Client();

Вывод:

Fatal error: Trait "GuzzleHttp\ClientTrait" not found in D:\xampp\htdocs\project_without_composer\guzzle\src\Client.php on line 17

Можно подключить их напрямую командой require или зарегистрировать автозагрузчик, но это поможет отыскать лишь классы, которые шли в пакете guzzle:

function guzzleAutoloader($classname)
{
    $classnameGroup = explode('\\', $classname);
    $directories = ['', 'Cookie/', 'Exception/', 'Handler/'];
    foreach ($directories as $directory) {
        $filename = __DIR__ . "/guzzle/src/{$directory}" . end($classnameGroup) . ".php";
        if(file_exists($filename)) {
            require_once($filename);
        }
    }
}

spl_autoload_register('guzzleAutoloader');

Вывод:

PHP Fatal error: Uncaught Error: Interface "Psr\Http\Client\ClientInterface" not found in D:\xampp\htdocs\project_without_composer\guzzle\src\Client.php:17

Psr\Http\Client\ClientInterface и прочие классы придётся устанавливать отдельно. Полный их список можно найти в секции require файла guzzle/composer.json.

Без Composer мы бы вручную устанавливали каждый компонент и писали для них автозагрузчики, пока интерпретатор не перестал бы «ругаться». C Composer достаточно такой команды:

composer require <полное_имя_пакета>

Эта команда пройдётся по дереву зависимостей и сама всё установит.

Почти все современные PHP-проекты на GitHub содержат файл composer.json, в котором хранится список зависимостей вместе с информацией об их версиях. Если файл составлен корректно, то вам даже не нужно знать названия компонентов: достаточно ввести команду composer install, и умница-менеджер сделает всё за вас.

Подробнее о composer.json читайте в разделе «Синтаксис composer.json».

Фиксация стабильных версий пакетов

Неизменный спутник composer.json — его тёзка composer.lock. Из-за схожих названий и синтаксиса их часто путают, но на самом деле оба файла незаменимы и выполняют чётко определённые задачи. Если в composer.json перечислены зависимости и их минимальные версии, то composer.lock содержит информацию о точных версиях зависимостей, которые использовались во время разработки и тестирования.

Слово lock в расширении появилось не случайно: файл будет блокировать попытки обновить библиотеки до более свежих версий, чем те, что в нём указаны. Таким образом, например, можно гарантировать одинаковые условия для всех разработчиков в проекте.

Автозагрузка классов

Composer упрощает подключение файлов благодаря собственному универсальному автозагрузчику. С ним можно почти забыть о директивах include и require — достаточно подключить файл vendor/autoload.php, после чего любой класс, именованный в соответствии с PSR-4, будет подключаться только тогда и в том месте, где это потребуется.

Установка Composer

Composer можно установить глобально или локально. В первом случае менеджер будет доступен для работы из любого каталога; при локальной установке — только из папки, которую вы выберете.

Ниже приведены самые доступные и простые способы установки для трёх основных операционных систем: Windows, macOS и Linux.

В Windows

Самый простой способ — скачать, запустить исполняемый файл Composer-Setup.exe с официального сайта и следовать указаниям установщика. Экзешник сам добавит путь к Composer в переменную PATH, открыв к нему глобальный доступ.

Порядок установки:

• Перейдите на официальный сайт Composer и скачайте установщик, нажав на кнопку Composer-Setup.exe. Запустите его.
• Следуйте инструкциям установщика. Укажите путь к PHP, если он не обнаруживается автоматически (например, D:\xampp\php\php.exe в XAMPP). Завершите установку, нажав Install.
• Проверьте установку. Откройте командную строку (нажмите Win + R, введите cmd и нажмите Enter). Введите команду composer и убедитесь, что выводится текст, подтверждающий успешную установку:

Второй способ — ручной, через командную строку (cmd.exe) или PowerShell. С его описанием вы можете ознакомиться в официальной документации.

Читайте также:

PowerShell для чайников: что это и как с ним работать

В Linux (Ubuntu)

1. Откройте терминал и обновите список пакетов:

sudo apt update

2. Убедитесь, что на вашей машине установлены расширения, необходимые для корректной работы Composer:

sudo apt install curl php-cli php-mbstring git unzip

3. Установите программу с помощью утилиты install:

sudo apt install composer

4. Проверьте установку командой composer. В случае успеха терминал вернёт следующий текст:

В macOS

В macOS самый простой и предпочтительный способ установки — с помощью утилиты Homebrew:

• Убедитесь, что Homebrew установлен на вашем компьютере. Для этого откройте терминал и введите команду brew -v. Если Homebrew не установлен, сделайте это по инструкции с официального сайта.
• Установите Composer командой brew install composer.
• Проверьте установку: введите в терминале команду composer и убедитесь, что выводится текст, подтверждающий успешную установку.

Синтаксис composer.json

В composer.json описаны зависимости проекта в формате JSON. Как уже было сказано ранее, он позволяет одной командой установить все необходимые сторонние компоненты.

Файл хранит следующую информацию:

• списки зависимостей для продакшена и разработки;
• директории, в которых автозагрузчик будет искать классы;
• справочная информация (имя и тип проекта, описание, ключевые слова, лицензия);
• конфигурации Composer.

Содержимое файла представляет собой простой JSON-объект с ключами и значениями:

{
  "name": "laravel/laravel",
   "type": "project",
   "description": "The skeleton application for the Laravel framework.",
   "keywords": ["laravel", "framework"],
   "license": "MIT",
   "require": {
       "php": "^8.2",
       "doctrine/dbal": "^4.0",
       "guzzlehttp/guzzle": "^7.8",
       "laravel/framework": "^11.9",
       "laravel/tinker": "^2.9",
       "spatie/laravel-html": "^3.11"
   },
   "require-dev": {
       "fakerphp/faker": "^1.23",
       "laravel/pint": "^1.13",
       "laravel/sail": "^1.26",
       "mockery/mockery": "^1.6",
       "nunomaduro/collision": "^8.0",
       "phpunit/phpunit": "^11.0.1"
   },
   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Database\\Factories\\": "database/factories/",
           "Database\\Seeders\\": "database/seeders/"
       },
       "files": [
           "app/Helpers/helpers.php"
       ]
   }
}

Ключи в JSON всегда берутся в кавычки, а значениями могут быть как числа, булевы значения, сроки и массивы, так и вложенные объекты. За более подробным описанием JSON приглашаем в нашу статью об этом формате.

Теперь познакомимся с некоторыми свойствами.

name — имя пакета. Оно состоит из имени вендора и имени пакета, разделёнными прямым слешем /. Именно его пользователи будут вызывать при установке, поэтому для публичных проектов параметр необходим.

type — тип пакета, по умолчанию принято ставить library («библиотека»). Поле используется для определения порядка установки и развёртывания пакета. Например, файлы из library будут скопированы в папку vendor, а пакет metapackage не содержит никаких файлов, зато вызовет установку других пакетов, содержащихся в графе require.

description — короткое описание проекта (обязательно для публичных пакетов).

keywords — массив ключевых слов, по которым можно найти пакет командой composer search.

require — тот самый список зависимостей. В примере выше (это реальный composer.json проекта на Laravel) рядом с каждой версией стоит знак каретки ^, который ограничивает мажорную версию. Это значит, что при работе над проектом лучше ограничиться PHP v8, Laravel v11, PHPUnit v11 и так далее.

Другие символы версионирования в Composer:

• <, >, <=, >= и ! = — диапазон версий, например >=1.1.0<=1.1.8;
• - — диапазон версий через дефис, например 1.1.0-1.18;
• * — подстановка, например 1.1.*;
• ~ — последний разряд должен быть равен или больше указанного. Например, ~1.1.3 эквивалентен >=1.1.3<1.2.

autoload — список директорий, в которых автозагрузчик будет искать классы.

Composer предоставляет четыре метода автозагрузки:

• Файловый — файлы подключаются целиком, по аналогии с require и include. Полезно, когда нужно подключить наборы функций.
• Карты классов — Composer получает список директорий, составляет список классов, которые в них хранятся, и автоматически загружает их при необходимости.
• PSR-0 — каждому пространству имён в соответствие ставится директория (пара «ключ — значение»), при этом структура папок должна воспроизводить структуру пространства имён. Например, если класс LoginController находится в пространстве App\Http\Controllers, то файл LoginController.php должен лежать в папке App\Http\Controllers.
• PSR-4 — то же, что и PSR-0, но структура папок не должна имитировать структуру пространств имён.

Для каждого из методов есть своя секция в разделе autoload: files, classmap, psr-0 и psr-4. Чаще всего вы будете работать с psr-4 — современным стандартом автозагрузки в PHP — и чуть реже с files.

Основные команды Composer

Теперь, когда вы знакомы с устройством Composer, пришло время узнать его основные команды.

Установка пакета

Пожалуй, самая популярная задача, которую разработчики решают с помощью Composer, — установка библиотек и фреймворков. Для этого есть команда require:

composer require <имя_пакета>

Сразу возникает вопрос: а как узнать точное имя искомого пакета? Кратчайший путь лежит через поисковики: гуглим или яндексим библиотеку, копируем название с официального сайта или из README на GitHub и передаём команде require.

Жмём Enter — и вуаля! Composer начинает установку зависимостей, о чём станет понятно по череде сообщений оптимистичного зелёного цвета в терминале. Если установка прошла без проблем, Composer покажет версию установленного пакета.

Установка всех пакетов из composer.json

Обычно в корневой папке PHP-проектов на GitHub лежит файл composer.json со списком необходимых пакетов (о нём мы говорили выше). С помощью этого файла можно установить все зависимости одной командой:

composer install

После выполнения команды в корневой директории появится папка vendor с файлами зависимостей и автозагрузчиком autoload.php.

В 99% случаев установка проходит без сучка и задоринки. Проблемы могут доставить пакеты, которые используют функции отсутствующих расширений. Composer сообщит о них в отчёте:

league/flysystem-local 3.28.0 requires ext-fileinfo * -> it is missing from your system. Install or 
enable PHP's fileinfo extension.

Обычно проблема решается банальным раскомментированием соответствующей строки в php.ini. Но даже если расширения нет в списке — не страшно: его можно скачать в виде файла в формате .dll (в Windows) или .so (в Linux), скопировать в папку с расширениями (точный путь зависит от операционной системы и версии PHP) и прописать название файла в php.ini.

Обновление зависимостей

Обновить все зависимости в проекте можно с помощью команды:

composer update

Для обновления конкретной зависимости укажите её имя:

composer update <vendor-name/project-name>

Обновление Composer

У Composer обновления тоже выходят регулярно. Чтобы обновиться до последней версии, используйте следующую команду:

composer self-update

Для установки последней стабильной версии добавьте флаг -- stable.

Удаление пакета

Команда remove удаляет пакет из проекта:

composer remove <vendor-name/project-name>

После выполнения пакет исчезнет из папки vendor и разделов require и require-dev файла composer.json.

Проверка валидности файла composer.json

Чтобы composer отработал установку пакетов так, как вы этого ожидаете, файл composer.json должен быть составлен корректно.

Для этого есть команда:

composer validate

Если файл составлен корректно, вы увидите следующее сообщение:

./composer.json is valid

В противном случае Composer укажет на ошибки:

./composer.json is valid for simple usage with Composer but has
strict errors that make it unable to be published as a package
See https://getcomposer.org/doc/04-schema.md for details on the schema
# Publish errors
- description : The property description is required

В этом примере файл вполне пригоден для использования. Но если мы захотим разместить проект в центральном репозитории Packagist, то он не пройдёт проверку, потому что в composer.json нет поля description.

Вывод

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

Сегодня Composer используется практически везде, поэтому бэкенд-разработчику полезно знать не только основные команды, но и принципы, по которым Composer управляет зависимостями в проектах.