Composer — менеджер зависимостей для PHP

php
Composer

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:\path\to\composer.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'а.