Composer (getcomposer.org) — это относительно новый и уже достаточно популярный менеджер зависимостей для PHP. Вы можете описать от каких библиотек зависит ваш проект и Composer установит нужные библиотеки за вас! Причём Composer — это не менеджер пакетов в классическом понимании. Да, он оперирует с сущностями, которые мы будем называть «пакетами» или библиотеками, но устанавливаются они внутрь каждого проекта отдельно, а не глобально (это одно из основных отличий от старого-доброго PEAR).
Кратко, как это работает:
- У вас есть проект, который зависит от нескольких библиотек.
- Некоторые из этих библиотек зависят от других библиотек.
- Вы описываете в своём проекте те библиотеки, от которых непосредственно зависит ваш код.
- Composer находит нужные версии требуемых библиотек для всего проекта, скачивает их и устанавливает в папку вашего проекта.
При создании Composer авторы черпали идеи и вдохновение из аналогичных проектов: npm для Node.js и Bundler для Ruby.
Изначально он был спроектирован и разработан двумя людьми Nils Adermann и Jordi Boggiano, сейчас в проекте участвует более двадцати контрибьюторов, Проект написан на PHP 5.3, распространяется под лицензией MIT и доступен на github.
Первые коммиты были сделаны апреле 2011 года и на сегодняшний день Composer находится в стадии «alpha3». Однако, он уже достаточно стабилен и используется многими популярными PHP проектами (например, Symfony 2). Список проектов использующих Composer можно посмотреть на сайте packagist.org — это официальный репозиторий Composer пакетов. Кстати, на недавней конференции Devconf 2012 разработчик фреймворка Yii в своём докладе упомянул, что Yii2 скорее всего тоже будет использовать Composer.
В этой статье я кратко опишу основные возможности Composer и мы попробуем создать демонстрационный проект использующий Composer для загрузки необходимых библиотек. Все примеры будут доступны на github.com и bitbucket.org.
Что умеет Composer?
- Скачивать пакеты и их зависимости;
- по умолчанию, пакеты скачиваются из официального репозитория packagist.org. Любой человек может свободно добавить туда свой пакет, чтобы сделать его установку максимально лёгкой и удобной для всего мира;
- пакеты можно скачивать не только с packagist.org, но и из любого git, mercurial или svn репозитория;
- при скачивании пакетов с github.com или bitbucket.org не требуется установленной системы контроля версий (git или hg), Composer работает через API этих сайтов;
- git/hg/svn репозиторий с пакетом может находиться не только на одном из перечисленных выше сайтов, но в любом другом месте, например, в локальной сети предприятия или вообще на локальном жестком диске;
- кроме того, устанавливаемая библиотека не обязательно должна быть оформлена в виде Composer-пакета, вы можете сделать установку из любого git/hg/svn репозитория произвольной структуры;
- наконец, устанавливаемый пакет не обязательно должен быть git/hg/svn репозиторием, это может быть произвольный zip файл доступный по любому uri!
- все пакеты устанавливаются в текущую директорию (откуда была выполнена команда install), это позволяет иметь несколько различных версий библиотек при работе над разными проектами параллельно;
- команда update обновляет все установленные (или установит заново случайно удалённые) пакеты до свежих версий. А может и не обновлять версии до самых свежих, если создать специальный composer.lock файл — это позволяет зафиксировать комбинацию из стабильных версий всех используемых в проекте библиотек;
- после установки пакетов автоматически генерируется autoload.php, с помощью которого можно подключить установленные библиотеки в коде ваше вашего проекта. При подготовке Composer-пакета рекомендуется использовать PSR-0 — стандарт расположения и именования php файлов, чтобы autoload смог их легко найти. В любом случае, автор пакета может описать правила, по которым autoload будет искать файлы тех или иных классов или неймспейсов. Если вы устанавливаете библиотеку, которая не оформлена как Composer-пакет (например, произвольный git репозиторий с github), то задача описания правил autoload ложится на ваши плечи. Так что никакой магии с генерируемым autoload.php нет — он умеет загружать всё (даже библиотеки с набором функций вне классов), главное, чтобы были описаны правила (автором библиотеки или вами).
Рабочий пример: используем Composer в своём проекте
Чтобы разобраться, как пользоваться Composer'ом, напишем маленький проектик на PHP: «Super Hello World». Поскольку мы не хотим изобретать велосипед и писать код «с нуля», возьмём готовые библиотеки и фреймворки.
Мы будем использовать cледующие библиотеки:
- микрофреймворк Silex (доступен в виде Composer пакета на packagist.org),
- шаблонизатор Twig (доступен в виде Composer пакета на packagist.org),
- наш собственный логер посещений SuperLogger, который я оформил в виде Composer-пакета и опубликовал на github
- нашу старую, но любимую легаси-библиотеку superlib, которая состоит из мешанины классов без неймспейсов и функций без классов; библиотека опубликована на github, но не является оформленным Composer-пакетом
Как мы это делали раньше: скачивали нужные нам фреймворки и библиотеки, думали куда их распаковать, писали в проекте кучу require (или require_once для надёжности).
Как мы это сделаем теперь: используем Composer — он сам скачает все библиотеки и сгенерирует для нас autoload.php. Кроме того, если мы захотим показать «Super Hello World» коллегам, достаточно будет опубликовать код нашего проекта на github (или ещё где-нибудь), не включая всех требуемых библиотек в репозиторий и не готовя длинной инструкции по их установке. Нашим коллегам достаточно будет скачать (склонировать) «Super Hello World» и выполнить команду
php composer.phar install
Composer распространяется в виде одного файла composer.phar (phar — это php-архив) — по сути это PHP скприт, который может принимать несколько команд (install, update, ...) и умеет скачивать и распаковывать библиотеки.
Кстати, немного о синтаксисе запуска.
Если вы работаете под Windows, то скорее всего вы будете писать что-то вроде
php C:pathtocomposer.phar install
Можно упростить себе жизнь, создав composer.bat и положив его в %PATH%.
В Linux и OS X можно настроить на исполнение команду типа
composer install
composer.json
Итак, мы готовы написать наш Super Hello World проект. И я его только что написал: http://github.com/pqr/superhelloworld. Код состоит из одного index.php файла в директории web и шаблона layout.twig в директории views.
Голова всему — это файл composer.json. Он должен быть в корне проекта, в нашем случае рядом с директориями web и view. В этом файле необходимо указать от каких библиотек зависит наш проект. Кроме того, если эти библиотеки не являются оформленными Composer-пакетами, то нужно указать некоторую дополнительную информацию об устанавливаемой библиотеке (например, описать правила автозагрузки классов и функций для autoload.php).
composer.json, как вы догадались, имеет формат данных JSON. На вопрос "почему именно JSON?" разработчики Composer отвечают "Потому что. Просто примите это.".
Нам нужно описать один js-объект, в котором будут находиться все инструкции. Первая и самая главная инструкция: require.
Подключаем пакеты с сайта packagist.org
{
"require": {
"php":">=5.3.0",
"silex/silex":"dev-master",
"twig/twig":">=1.8,<2.0-dev"
}
}
Здесь я описал зависимость проекта от PHP версии 5.3.0 и выше, от silex (микрофреймворк) и от twig (шаблонизатор). Silex и Twig доступны в виде Composer-пакетов на сайте packagist.org, поэтому дополнительных настроек не требуют. Замечу, что Silex в свою очередь зависит ещё от нескольких пакетов — все они будут скачены и установлены автоматически.
Имя пакета состоит из двух частей разделёных косой чертой: названия поставщика (vendor name) и названия библиотеки. Названием поставщика зачастую является ник автора или имя компании. Иногда, название поставщика совпадает с именем самой библиотеки или фреймворка.
Для каждого пакета обязательно нужно указать номер версии. Это может быть бранч в репозитории, например, «dev-master» — приставка dev сигнализирует, что это имя бранча, а сам бранч соответсвенно называется «master». Для mercurial репозитория аналогичная запись будет выглядеть как «dev-default». В качестве номера версии можно указать и более сложные правила, используя операторы сравнения. Кстати, если вы скачиваете код из удалённого репозитория, то Composer сканирует теги и имена веток в этом репозитории на предмет чего-то похожего на номера версий, например тег «v1.2.3» будет использован как указатель на версию 1.2.3.
Подключаем на собственный Compsoer-пакет
Далее, подключим наш собственный пакет SuperLogger, который правильно оформлен, но опубликован не на packagist.org, а на github:
{
"require": {
"php":">=5.3.0",
"silex/silex":"dev-master",
"twig/twig":">=1.8,<2.0-dev",
"mycompany/superlogger":"dev-master"
},
"repositories":[
{
"type":"git",
"url":"http://github.com/pqr/superlogger"
}
]
}
Чтобы Composer занал где искать пакет «mycompany/superlogger», мы добавили массив repositories со ссылкой на соотвествующий github репозиторий. Обратим внимание, что записи в массиве repositories напрямую никак не связаны с блоком require — между пакетами и репозиториями не указано соответствие. На сколько я понял, Composer ищет все требуемые пакеты во всех указанных репозиториях (в т.ч. на сайте packagist.org) и скачивает найденные совпадения по каким-то внутренним приоритетам. Более глубоко я в этом моменте ещё не разбирался, поправьте меня, если кто-то знает детали.
Подключаем произвольный git репозиторий
Теперь подключим нашу легаси-библиотеку superlib, которая лежит на github, но не является оформленным Composer-пакетом, т.к. она очень старая.
{
"require":{
"php":">=5.3.0",
"silex/silex":"dev-master",
"twig/twig":">=1.8,<2.0-dev",
"mycompany/superlogger":"dev-master",
"pqr/superlib":"1.2.3"
},
"repositories":[
{
"type":"git",
"url":"http://github.com/pqr/superlogger"
},
{
"type":"package",
"package":{
"name":"pqr/superlib",
"version":"1.2.3",
"source":{
"type":"git",
"url":"http://github.com/pqr/superlib",
"reference":"master"
},
"autoload":{
"classmap":["timer.php"],
"files":["lib_functions.php"]
}
}
}
]
}
В массив repositories добавился объект, который целиком описывает пакет pqr/superlib. По сути, это то описание, которое должен был бы сделать автор библиотеки и положить его внутри своего репозитория. Но по условиям задачи, superlib не является оформленным Composer-пакетом, поэтому нам пришлось создать его описание в рамках Super Hello World проекта. Аналогичным образом можно подключить любую другую библиотеку, в т.ч. простой zip файл.
Подключаем простой zip файл
Например, вот как могло бы выглядеть описание зависимости от шаблонизатора Smarty, распространяемого в виде zip файла с исходниками в svn:
{
"repositories":[
{
"type":"package",
"package":{
"name":"smarty/smarty",
"version":"3.1.7",
"dist":{
"url":"http://www.smarty.net/files/Smarty-3.1.7.zip",
"type":"zip"
},
"source":{
"url":"http://smarty-php.googlecode.com/svn/",
"type":"svn",
"reference":"tags/Smarty_3_1_7/distribution/"
}
}
}
],
"require":{
"smarty/smarty":"3.1.*"
}
}
Инстукция autoload
Вернёмся к нашему проекту.
Описывая «pqr/superlib», мы добавили инструкцию autoload. В ней указан файл timer.php, в котором будущий автозагрузчик будет искать классы и указали файл с функциями lib_functions.php — он будет принудительно подключаться в начале autoload.php.
Итак, наш проект состоит из:
- в корне лежит файл composer.json;
- в корне находятся директории web и views;
- внутри директории web лежит файл с «бизнес-логикой» нашего приложения: index.php;
- внутри директории views лежит файл шаблона layout.twig;
- дополнительно, в папку web я положил .htaccess (для apache) и web.config (для IIS 7.5) с правилами mod_rewrite/url rewriter — непосредсвенно к настройке Composer они отношения не имеют.
Всё готово к запуску.
Запускаем composer install
php composer.phar install
Composer клонирует репозитории и распаковывает их на нужной версии в директорию vendor, которую он сам создаёт в корне проекта. После распаковки, в директории vendor мы найдём:
- файл autoload.php
- служебные директории .composer и composer
- pimple — пакет, который подтянулся вместе с микрофреймворком Silex
- silex — сам микрофреймворк, его мы явным образом затребовали при описании зависимостей
- symfony — некоторые компоненты из Symfony 2, которые требуются для работы Silex
- twig — шаблонизатор, который мы также явно запросили
- mycompany — внутри этой директории будет находиться репозиторий superlogger скаченный с github
- pqr — внутри этой директории будет находиться репозиторий superlib, также скаченный с github
Остаётся только подключить autoload.php в начале файла web/index.php (require "../vendor/autoload.php") и все библиотеки и функции будут доступны!
Как создать собственный Composer пакет?
В этом проекте мы использовали Composer с точки зрения потребителя библиотек. А как самому создать Composer пакет, чтобы любой другой человек смог им воспользоваться?
На самом деле, один из таких пакетов я создал, когда подготавливал примеры для этой статьи. В корне репозитория superlogger лежит файл composer.json похожей структуры, который описывает сам пакет и его зависимости (в случае с superlogger зависимостей нет). Другие примеры: репозитории silex и twig, которые скачались в папку vendor — все они имеют файл composer.json в корне — смотрите, изучайте!
И, конечно, не забывайте про документацию на официальном сайте getcomposer.org/doc/.
Эту тему я оставлю вам для самостоятельной проработки.
Подведём итоги
В этой статье я рассказал, что такое Composer, его историю и описал основные возможности. Мы с вами попробовали создать проект, который использует Composer для установки пакетов с сайта packagist.org и из наших собственных репозиториев.
Самое время попробовать!
- Скачате Composer (getcomposer.org/download/)
- Скачате superhelloworld (git clone git://github.com/pqr/superhelloworld.git)
- Установте зависимости (cd superhelloworld && php composer.phar install)
- Изучте появившуюся папку vendor и сгенерированный autoload.php
- Используте Composer в своих проектах
… - PROFIT!!!
На добавку пара ссылок по теме:
Composer: Part 1 – What & Why
Composer: Part 2 – Impact
P.S.
В своих рабочих проектах я использую систему контроля версий Mercurial. Этот пример вы также можете скачать и установить через Composer с сайта bitbucket.org: http://bitbucket.org/pqr/superhelloworld
Внимание: к сожалению, при использовании Composer с Mercurial репозиториями на Windows машине я нашел один баг. Если вы устанавливаете зависимости в проекте, который находится на диске отличном от системного диска, то получите ошибку. Например, системный диск C:, а проект вы разворачиваете где-то в папке D:someproject и ваш проект зависит от библиотек опубликованных в виде Mercurial репозиториев — Composer не сможет правильно их прочитать. Собираюсь в ближайшее время пофиксить этот баг и отправить pull request в официальный репозиторий Composer'а.
Автор: PQR
