В настоящее время сложно представить проект без менеджера зависимостей, независимо от того, на каком языке программирования он написан. Для PHP таким менеджером является Composer.
Цель данной статьи – не только познакомить вас с пакетным менеджером Composer, но и рассказать немного больше, чем просто о способах установки и обновления сторонних пакетов.
Что такое Composer?
Composer - это инструмент, который позволяет управлять сторонними библиотеками в PHP-проекте. Он позволяет подключать, устанавливать и обновлять библиотеки или «пакеты», а также управлять их версиями.
Разработка Composer была вдохновлена уже существующими на тот момент менеджерами пакетов: npm (Node.js) и bundler (Ruby). Первый релиз состоялся 1 марта 2012 года.
Composer является кроссплатформенным инструментом: он одинаково работает на операционных системах Windows, Linux и OSX.
Чем Composer отличается от Pear
До появления Composer в мире PHP-разработки существовал PEAR (PHP Extension and Application Repository) – это фреймворк и система распространения повторно используемых PHP-компонентов.
PEAR позволял создавать библиотеки на PHP, хранить их в общем репозитория и использовать в проектах. Для чего же понадобилась разработка Composer?
Дело в том, что у PEAR есть несколько существенных минусов:
- Библиотека устанавливается в масштабе всей системы, а не для каждого проекта отдельно, таким образом, невозможно использовать несколько разных версий одной библиотеки на компьютере.
- Чтобы загрузить библиотеку в PEAR, необходимо набрать определенное количество голосов.
- Существующие решения были часто устаревшими, неактивными или неподдерживающимися.
Основы использования Composer
Основное назначение Composer – это простое управление библиотеками и пакетами в PHP-проекте.
Для быстрого старта разработчику необходимо знать всего несколько команд, например:
init – инициализация проекта (а зачастую она не требуется при использовании PHP-фреймворка);
require – подключить пакет;
install – установить зависимости;
update – обновить пакеты;
При использовании этих команд можно без проблем продолжить работу над проектом, не вдаваясь в подробности. Также у Composer есть подробная официальная документация, там можно прочесть всю необходимую информацию по установке и использованию.
Но Composer – это больше, чем просто пакетный менеджер. Чтобы в этом разобраться, для начала пройдемся по основам использования:
Composer.json
Центральным файлом для управления пакетами в проекте является файл composer.json. В нем описываются различные настройки и, самое главное, пакеты, от которых зависит наш проект:
В блоке require указываются необходимые нашему проекту пакеты, но также пакет можно добавить и с помощью команды:
Версии пакетов
Большинство разработчиков при разработке своих пакетов следуют соглашению SemVer – семантическое версионирование. Это соглашение, при котором номер версии указывается в следующем виде:
| MAJOR.MINOR.PATCH,
где MAJOR, MINOR и PATСH - целые числа, начиная с 0.
Когда следует увеличивать версию:
- Major (мажорная версия) - обратно несовместимые изменения в API.
- Minor (минорная версия) - добавлена функциональность и при этом не нарушена обратная совместимость.
- Patch (патч-версия) - баг-фиксы, незначительные доработки.
Некоторые способы указания версий пакетов в composer.json:
Точная версия
"worksolutions/php-collections": "1.1.7"
Диапазон версий
"worksolutions/php-collections": ">=1.0.0"
Диапазон тильды
"worksolutions/php-collections": "~1.2.3"
Эквивалентно >=1.2.3 <1.3.0
Диапазон каретки
"worksolutions/php-collections": "^1.2.3"
Эквивалентно >=1.2.3 <2.0.0. Используется для ограничения мажорной версии, чтобы гарантировать обратную совместимость.
Диапазон версий подстановочных знаков
"worksolutions/php-collections": "1.0.*"
Эквивалентно >=1.0.0 <1.1
Также, в качестве версии можно указать название ветки или хэш коммита, если в качестве поставщика пакета используется git-репозиторий.
Файл блокировки
При первой установке всех пакетов в проект, которые описаны в composer.json будет создан файл composer.lock, в котором будут указаны точные версии каждого установленного пакета.
При следующей попытке установить пакеты Composer будет брать информацию из файла блокировки, загружая точные версии каждого пакета, чтобы не допустить случайных ошибок из-за новых минорных обновлений пакетов.
Рекомендуется сохранять файл composer.lock в системе контроля версий.
Основные команды
Инициализация проекта
$ composer init
Установка пакетов
$ composer install
При первом запуске Composer берет информацию о пакетах из файла composer.json, затем создается файл composer.lock, на основе которого происходит установка пакетов.
Обновление пакетов
$ composer update
Выполняет установку пакетов как будто файла composer.lock не существует. Composer установит пакеты согласно composer.json, а затем обновит composer.lock.
Обновление пакетов
$ composer require
Composer добавит пакет в composer.json
Автозагрузка
Чтобы использовать классы проекта или установленных библиотек, необходимо подключить файл, который генерирует Composer:
Пример autoload в файле composer.json:
Данную запись можно понимать следующим образом: класс, который имеет путь src/Service/Logger.php будет иметь пространство имен App\Service.
Подключить данный класс можно с использованием директивы use:
Пакеты
Каждый проект по сути является пакетом. Единственное различие между проектом и библиотекой в том, что библиотека имеет название, которое является обязательным, а проект нет.
Способы подключения пакетов
Существует немало различных способов подключить библиотеку в проект. Так, библиотеку можно подключить, если она доступна через VCS (систему контроля версий), либо использовать прямую ссылку на zip-файл с пакетом.
Более популярным, простым и удобным способом является подключение пакетов, опубликованных на Packagist.
Packagist - это репозиторий пакетов Composer. Опубликованные там пакеты можно подключить в проект, не указывая никакой дополнительной информации, кроме названия пакета и версии в блоке require. Необходимо, чтобы предварительно пакет был опубликован на packagist.org.
Рассмотрим подключение библиотеки PHP-коллекций через git-репозиторий:
Для подключения в блоке require необходимо указать название репозитория и ветку, а в блоке repositories добавить ссылку на репозиторий.
Данный способ выглядит несложным, однако, проще подключать библиотеки, которые хранятся на Packagist. Рассмотрим пример подключения той же библиотеки, но через Packagist:
Репозиторий Packagist не нужно специально указывать в Composer - он зарегистрирован там по-умолчанию.
Создание собственного пакета
Создание репозитория
Перед тем, как начать разработку нашего пакета, создадим репозиторий на GitHub:
Клонируем репозиторий и переходим в папку проекта
Перед началом инициализации проекта необходимо создать файл .gitignore, где нужно указать директорию vendor, а также файл блокировки composer.lock. Это необходимо для того, чтобы пользователь мог развернуть любую подходящую версию пакета.
Инициализация проекта
Генерируем конфигурационный файл Composer, выполнив команду инициализации
Далее отвечаем на вопросы, именуем пакет в формате <vendor>/<name>, где vendor - имя автора, например, имя пользователя на Github, name - имя пакета.
Тип пакета указываем library, так как мы создаем пакет. Указание дополнительных пакетов на данном этапе пропускаем.
В итоге при завершении работы команды будет создан файл composer.json:
Создание файла README
Рекомендуется в файле README.md указать:
- Название пакета
- Доступную версию PHP
- Способ установки пакета
- Примеры использования
Версионирование
Версии пакета добавляются с помощью команды git tag.
Пример:
Создаем тег
Отправляем тег в репозиторий
Добавлен тег:
Публикация пакета на Packagist
Переходим на сайт packagist.org, выбираем «Submit».
Указываем ссылку на репозиторий Github и выполняем проверку:
После проверки снова нажимаем «Submit», после чего пакет будет опубликован:
Скрипты Composer
Composer-скрипт - это определенный сценарий, который выполняется по какому-либо событию Composer, например, установка зависимостей или сброс автозагрузчика.
Таким сценарием может являться любой набор команд командной строки или статический метод PHP-класса.
Существует несколько видов событий:
- Командные события
- События установщика
- События пакета
- События плагина
Определение сценариев
Чтобы определить сценарий, в файле composer.json добавляется свойство scripts, которое содержит пары «событие» - «сценарий». Сценарий может быть объявлен как строка для выполнения одного действия или как массив для указания нескольких скриптов.
Пример объявления скрипта как статический метод PHP:
Пример объявления скрипта как команда командной строки:
Запуск скриптов и пользовательские команды
При необходимости скрипты можно запустить вручную, а не использовать их только при возникновении какого-либо события Composer.
Например, команда:
запустит все сценарии, которые определены для события post-install-cmd.
Если существует необходимость добавить пользовательский сценарий, но все доступные события не подходят под этот сценарий, то существует возможность определить под собственным именем.
Пример:
Запустить скрипт можно с помощью команды run-script, либо как собственную команду composer:
Плагины Composer
Плагин - это обычный пакет Composer, который используется для расширения функциональности Composer при необходимости.
Основное отличие заключается в том, что в composer.json пакет плагина должен иметь тип composer-plugin, атрибут extra должен содержать один или множество классов плагина, а также должен быть подключен специальный пакет composer-plugin-api.
Плагин подключается в проект как обычный пакет Composer. Он также должен быть загружен на Packagist.
Пример:
Создание плагина
Каждый плагин Composer должен реализовывать интерфейс PluginInterface.
Интерфейс содержит методы, в которые передаются экземпляры классов Composer\Composer и Composer\IO\IOInterface.
С помощью этих двух объектов можно прочитать всю конфигурацию, а также по желанию можно управлять всеми внутренними объектами и состоянием.
Также, плагины Composer могут реализовывать EventSubscriberInterface для автоматической регистрации обработчиков событий при загрузке плагина.
Пример класса плагина с обработками события:
Возможности плагина
Composer предоставляет так называемый набор возможностей, которые могут быть реализованы плагинами. Их цель состоит в том, чтобы расширить возможности Composer, не прибегая к изменению внутреннего состояния экземпляра класс Composer.
Чтобы добавить использование возможностей, класс плагина должен реализовывать интерфейс Capable. Данный интерфейс содержит метод getCapabilities(), который возвращает массив с ключом в качестве имени класса Composer Capability и значением в виде собственного имени класса реализации плагина указанной возможности.
Пример реализации собственного поставщика команд.
Команда:
Поставщик команд:
После этого в проекте, где подключен плагин, можно использовать команду:
Выводы
- Composer - это не просто менеджер пакетов, но и удобный инструмент для управления PHP-проектом.
- Composer имеет большой ряд дополнительных возможностей, которые могут быть полезны при разработке проектов на PHP.
- Лучшим способом погружения в какой-либо инструмент является изучение его официальной документации.
