Composer для самых маленьких
Когда я первый раз разбирался с composer, я набросал для себя маленькую шпаргалку и теперь, спустя некоторое время представляю её на суд общественности в несколько доработанном виде.
Данная публикация актуальная для тех, кто в первый раз столкнулся с незаменимым менеджером пакетов для PHP.
Итак, Composer — менеджер пакетов для PHP.
Для чего нужен Composer и простейший пример его использования
Возьмем для примера этот проект
Если в двух словах: то это набор скриптов для работы в VK API
Соответственно, для работы этих скриптов нужно несколько библиотек
Библиотеки перечислены в файле composer.json — ключевой файл при работе с composer
В этом проекте используется 5 библиотек. Соответственно, если разработчик решит опубликовать этот проект на github, то ему достаточно закинуть в репу саму папку со скриптами и составить composer.json, в котором будут описаны библиотеки, необходимые для работы этого проекта. Простота очевидна: в репу не нужно вслед за файлами прицепом тащить все нужные библиотеки. Занимает меньше места, проще распространять проект.
В папке scripts лежат непосредственно скрипты проекта, для работы которых и требуются эти 5 пакетов.
Запускаем установку пакетов:
После установки появляется папка vendor, куда складываются установленные пакеты и формируется файл autoload.php
Этот файл подключаем к проекту и всё — библиотеки подключены, можно спокойно с ними работать.
Простота очевидна: не нужно скачивать и подключать библиотеки и их зависимости самостоятельно, composer всё сделает за Вас. И вся эта пачка подключается одним единственным файлом autoload.php
Все пакеты, которые лежат в vendor, добавляются в автозагрузчик. При этом composer опирается на файлы composer.json, которые должны быть у каждого пакета. Формирование composer.json пакета — это задача разработчика пакета, от потребителя пакета требуется лишь описать в composer.json проекта, какие пакеты нужно подключить.
Это пример composer.json проекта:
Это пример composer.json пакета:
В секции require прописана зависимость этого пакета — библиотека guzzle http, необходимая для работы библиотеки getjump/vk. В данном случае, т.е. с точки зрения потребителя пакетов, всевозможные зависимости пакетов — это не наша «забота», с зависимостями composer разберётся сам.
Пространство имён пакета прописано в секции autoload
getjump\\Vk\\ — наименование пространства имён
src/getjump/Vk/ — директория, в которой лежат файлы с классами пакета
Работа с этой библиотекой в проекте:
Core и Friends — это классы библиотеки, которые разложены и прописаны в папке src в соответствии со стандартом PSR-4. Опять же формирование структуры пакета — это работа создателя пакета.
Нам, как потребителю пакета, достаточно прописать в наш проект
include ‘../vendor/autoload.php’;
и все эти классы и пространства имён будут отлично работать.
При этом нам не нужно заморачиваться и писать автозагрузчик. Composer это сделает сам при выполнении команды install.
Установка
Установка Composer глобально
1) Для начала нужно что бы путь к директории с интерпретатором PHP был прописан в переменной окружения path.
Проверим, так ли это:
php –version
Далее нас будет интересовать переменная path:
Вписываем путь к интерпретатору
*С давних времён у меня на компьютере лежит сборка xampp, сама сборка здесь нафиг не нужна, а вот интерпретатор с неё вполне подойдёт (версия PHP – 5.6).
3) Добавим в переменную окружения path путь к composer.bat, например для D:\bin должно получиться:
Дополнительно можно добавить в path
D:\Users\%userName%\AppData\Roaming\Composer\vendor\bin\
для того, что-бы было удобнее использовать инструменты, глобально установленные через Composer.
(У меня папка Users располагается на диске D, а на C создан симлинк на неё).
Всё, composer установлен и полностью готов к работе.
Ещё: при установке можно словить ошибку
[RuntimeException]
The APPDATA or COMPOSER_HOME environment variable must be set for composer to run correctly
Решение нашлось здесь github.com/composer/composer/issues/2033
Добавляем переменную APPDATA со значением D:\Users\GSU\AppData\Roaming
Установка Composer локально
Отличия глобальной и локальной установки
Команды запускаются по разному при локальной и глобальной установках:
Например:
Локально: php composer.phar require silex/silex
1.1
Глобально: composer require silex/silex
При глобальной установке этот файл не нужен. Composer запускается при любой текущей директории.
Команды
Синтаксис composer.json
Именование пакетов и варианты описания пакетов
Имя пакета состоит из двух частей разделёных косой чертой: названия поставщика (vendor name) и названия библиотеки.
Если пакет оформлен в соответствии со стандартом PSR-4, но опубликован не на packagist.org, а на github, то вместо версии пакета нужно прописать ветку и репозиторий для этого пакета:
Пример подключения библиотеки, которая лежит на github, но при этом не оформлена по стандарту PSR-4, а представляет из себя обыкновенное нагромождение файлов с классами и функциями.
Pqr/superlib — эта та самая «неправильная» библиотека.
В секции repositories для неё пишем такую конструкцию
Ключевой момент — секция autoload, здесь указываем нужные нам файлы с классами и функциями.
Структура библиотеки:
Освоение Composer: советы и приемы использования
Предлагаю читателям «Хабрахабра» перевод статьи «Mastering Composer – Tips and Tricks» за авторством Bruno Skvorc.
Composer произвел революцию в управлении пакетами в PHP и помог разработчикам по всему миру создавать независимый от фреймворков и разделяемый код. Но все же мало кто выходит за рамки основ его функционала, так что данная статья постарается осветить некоторые полезные приемы его использования.
Глобальная установка (Global)
Несмотря на то, что данная опция доступно описана в документации, Composer может (а в большинстве случаев должен) быть установлен глобально. Глобальная установка означает, что вместо:
Вы можете в любом проекте просто ввести:
Это позволяет очень просто создавать новые проекты (например, с помощью команды create-project) в любом месте вашей файловой системы.
Для установки Composer глобально, следуйте этим инструкциям.
Правильная установка зависимостей
Just add the following to your composer.json file:
Но данный подход имеет несколько недостатков. Во-первых, простой копипаст может привести к возникновению ошибок. Во-вторых, для новичка может быть не очевидно, где разместить данный код, если у него и так уже имеется обширный файл composer.json, и это также привести к ошибке. Наконец, некоторые люди будут иметь дело с Composer впервые, а возможно и впервые столкнутся с командной строкой. Поэтому хорошей практикой будет освещение всевозможных случаев, в которых новички могут чувствовать себя неуверенно (есть ли у них графический редактор или они будут использовать командную строку? Если второе, установлен ли в ней текстовый редактор, и если да, то какой? Объясняете ли вы саму процедуру редактирования файла? А что если файла composer.json ещё не существует в проекте? Описываете ли также принцип создания нового файла?).
Наилучший способ добавить новую зависимость в файл composer.json — это воспользоваться командой require:
Это добавит все необходимое в файл зависимостей, минуя ручное вмешательство.
Если вам нужно добавить пакеты в раздел require-dev, добавьте в команду опцию —dev:
Также, команда require поддерживает добавление нескольких пакетов одновременно, для этого просто разделите их пробелом.
Файлы блокировок
Файл composer.lock сохраняет текущий список установленных зависимостей и их версии. Таким образом, на момент, когда версии зависимостей уже будут обновлены, другие люди, которые будут клонировать ваш проект, получат те же самые версии. Это позволяет убедиться в том, что каждый, кто получает ваш проект, имеет “пакетное окружение”, идентичное тому, которое вы использовали при разработке, и помогает избежать ошибок, которые могли бы возникнуть из-за обновления версий.
Файл composer.lock почти всегда должен быть добавлен в систему контроля версий (не всегда).
Версионирование
Репетиции (Dry Runs)
Чтобы просто посмотреть, пройдет ли установка новых зависимостей успешно, вы можете использовать параметр —dry-run для команд install и update. Composer в данном случае выведет все потенциальные проблемы без непосредственного выполнения самой команды. Никаких реальных изменений в проекте не произойдет. Этот прием отлично подходит для тестирования сложных зависимостей и настройки изменений перед реальным их внесением.
Создание проекта
Последнее, но не менее важное, что мы должны упомянуть — это команда create-project.
Команда создания проекта принимает в качестве аргумента имя пакета, который она затем клонирует и выполняет composer install внутри него. Это отлично подходит для инициализации проектов — не нужно больше искать Url нужного пакета на GitHub, клонировать его, самому переходить в папку и выполнять команду install.
Крупные проекты, такие как Symfony и Laravel, уже используют данный подход для инициализации своих «skeleton» приложений, и многие другие также присоединяются.
Например, в Laravel это используется следующим образом:
В команду create-project можно передать еще два параметра: путь, в который нужно установить проект (если не указан, используется имя пакета), и версия (будет использована последняя, если не указать).
Composer 2: Что нового?
Composer, менеджер зависимостей для PHP, был выпущен около 8 лет назад, а сегодня опубликовали новую версию, 2.0. За эти годы Composer получил множество новых функций и не отставал от стандартов PHP. Вторая версия совместима со старыми проектами, но привнесет еще несколько замечательных новых функций. В этой статье расскажу о них подробнее.
Ускорение и оптимизация
В этом релизе была улучшена производительность. Теперь он не учитывает уже установленные пакеты, в результате обновление проходит намного быстрее. Также улучшили работу с памятью и процессором.
Команда установки стала умнее. Теперь она не изменяет папку vendor до тех пор, пока не гарантирует, что все пакеты установлены. Это позволяет избежать потери времени на их удаление в случае ошибок во время процесса.
Одной из лучших функций, для меня, стала параллельная загрузка, которая теперь поддерживается из коробки, и нам не нужно устанавливать дополнительные пакеты, как hirak/prestissimo, чтобы это работало.
Composer v2 почти в 2 раза быстрее, при установке laravel/laravel без кэширования.
Поддержка оффлайн
Composer представил возможность использовать его в оффлайн режиме. Это может быть интересно для бенчмарков или при возникновении проблем с подключением к интернету, поэтому вам не нужно удалять Composer install/update из списка команд.
Чтобы это заработало, нужно добавить COMPOSER_DISABLE_NETWORK=1 при выполнении команд:
или установите его в переменных среды. Он выдаст предупреждение о том, что сеть отключена.:
кроме того, вы увидите сообщение для пакетов, без кэширования:
Composer 2.* дает возможность использовать опцию с composer require и composer remove что делает нашу жизнь проще
Предотвращение проблем при работе от root
При выполнении команд от пользователя root теперь требуется подтверждение, чтобы предотвратить наши ошибки.
В предыдущих версиях, когда вы пытались выполнить команду, она вызывала следующее сообщение:
С Composer 2.* вы должны подтвердить выполнение:
Канонические репозитории
Эта функция решает определенную проблему, с которой сталкиваются несколько разработчиков при использовании одного и того же пакета в разных репозиториях. Composer 1.0 следовал определенному порядку при установке/обновлении своих пакетов. Он начал искать пакеты в своем списке репозиториев до тех пор, пока пакет не будет найден (также последняя версия).
Иногда это было не совсем ожидаемое поведение при работе с различными версиями пакетов в других репозиториях (используемых одним и тем же проектом). Представьте себе, что иногда вы хотите загрузить пакет из своего частного репозитория, а не из packagist, в котором есть пакет с тем же именем.
По умолчанию, в composer 2.x, все репозитории являются каноническими. Composer 1.x рассматривал все репозитории как неканонические, и для того, чтобы поменять поведение вручную, вы можете сделать:
Вы также можете отфильтровать пакеты, которые репозиторий сможет загрузить, либо выбрав те, которые вы хотите, либо исключив те, которые вы не хотите.
Например, здесь мы хотим выбрать только пакет foo/bar и все пакеты из some-vendor/ из определенного composer репозитория.:
А в этом примере мы исключаем toy/package из репозитория, который мы, возможно, не захотим загружать в этот проект.
Игнорировать определенное требование платформы
Другие обновления
Есть множество новых мелких возможностей и исправлений ошибок, которые улучшили удобство его использования и качество. Если вам интересно узнать о них больше, ознакомьтесь с описанием к выпуску в гитхаб.
Composer — менеджер зависимостей для PHP
Composer (getcomposer.org) — это относительно новый и уже достаточно популярный менеджер зависимостей для PHP. Вы можете описать от каких библиотек зависит ваш проект и Composer установит нужные библиотеки за вас! Причём Composer — это не менеджер пакетов в классическом понимании. Да, он оперирует с сущностями, которые мы будем называть «пакетами» или библиотеками, но устанавливаются они внутрь каждого проекта отдельно, а не глобально (это одно из основных отличий от старого-доброго PEAR).
Изначально он был спроектирован и разработан двумя людьми 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?
Рабочий пример: используем Composer в своём проекте
Чтобы разобраться, как пользоваться Composer’ом, напишем маленький проектик на PHP: «Super Hello World». Поскольку мы не хотим изобретать велосипед и писать код «с нуля», возьмём готовые библиотеки и фреймворки.
Как мы это сделаем теперь: используем Composer — он сам скачает все библиотеки и сгенерирует для нас autoload.php. Кроме того, если мы захотим показать «Super Hello World» коллегам, достаточно будет опубликовать код нашего проекта на github (или ещё где-нибудь), не включая всех требуемых библиотек в репозиторий и не готовя длинной инструкции по их установке. Нашим коллегам достаточно будет скачать (склонировать) «Super Hello World» и выполнить команду
Кстати, немного о синтаксисе запуска.
Если вы работаете под Windows, то скорее всего вы будете писать что-то вроде
Можно упростить себе жизнь, создав composer.bat и положив его в %PATH%.
В Linux и OS X можно настроить на исполнение команду типа
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
Здесь я описал зависимость проекта от 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:
Чтобы Composer знал где искать пакет «mycompany/superlogger», мы добавили массив repositories со ссылкой на соотвествующий github репозиторий. Обратим внимание, что записи в массиве repositories напрямую никак не связаны с блоком require — между пакетами и репозиториями не указано соответствие. На сколько я понял, Composer ищет все требуемые пакеты во всех указанных репозиториях (в т.ч. на сайте packagist.org) и скачивает найденные совпадения по каким-то внутренним приоритетам. Более глубоко я в этом моменте ещё не разбирался, поправьте меня, если кто-то знает детали.
Подключаем произвольный git репозиторий
Теперь подключим нашу легаси-библиотеку superlib, которая лежит на github, но не является оформленным Composer-пакетом, т.к. она очень старая.
В массив repositories добавился объект, который целиком описывает пакет pqr/superlib. По сути, это то описание, которое должен был бы сделать автор библиотеки и положить его внутри своего репозитория. Но по условиям задачи, superlib не является оформленным Composer-пакетом, поэтому нам пришлось создать его описание в рамках Super Hello World проекта. Аналогичным образом можно подключить любую другую библиотеку, в т.ч. простой zip файл.
Подключаем простой zip файл
Например, вот как могло бы выглядеть описание зависимости от шаблонизатора Smarty, распространяемого в виде zip файла с исходниками в svn:
Инстукция autoload
Вернёмся к нашему проекту.
Описывая «pqr/superlib», мы добавили инструкцию autoload. В ней указан файл timer.php, в котором будущий автозагрузчик будет искать классы и указали файл с функциями lib_functions.php — он будет принудительно подключаться в начале autoload.php.
Запускаем composer install
Как создать собственный Composer пакет?
В этом проекте мы использовали Composer с точки зрения потребителя библиотек. А как самому создать Composer пакет, чтобы любой другой человек смог им воспользоваться?
На самом деле, один из таких пакетов я создал, когда подготавливал примеры для этой статьи. В корне репозитория superlogger лежит файл composer.json похожей структуры, который описывает сам пакет и его зависимости (в случае с superlogger зависимостей нет). Другие примеры: репозитории silex и twig, которые скачались в папку vendor — все они имеют файл composer.json в корне — смотрите, изучайте!
И, конечно, не забывайте про документацию на официальном сайте getcomposer.org/doc/.
Эту тему я оставлю вам для самостоятельной проработки.
Подведём итоги
В этой статье я рассказал, что такое Composer, его историю и описал основные возможности. Мы с вами попробовали создать проект, который использует Composer для установки пакетов с сайта packagist.org и из наших собственных репозиториев.
В своих рабочих проектах я использую систему контроля версий Mercurial. Этот пример вы также можете скачать и установить через Composer с сайта bitbucket.org: http://bitbucket.org/pqr/superhelloworld
Внимание: к сожалению, при использовании Composer с Mercurial репозиториями на Windows машине я нашел один баг. Если вы устанавливаете зависимости в проекте, который находится на диске отличном от системного диска, то получите ошибку. Например, системный диск C:, а проект вы разворачиваете где-то в папке D:\someproject и ваш проект зависит от библиотек опубликованных в виде Mercurial репозиториев — Composer не сможет правильно их прочитать. Собираюсь в ближайшее время пофиксить этот баг и отправить pull request в официальный репозиторий Composer’а.
PHP Composer: фиксим зависимости без боли
Многие из вас наверняка сталкивались с ситуацией, когда в библиотеке или фреймворке, который вы используете, есть баг или нет необходимой функциональности. Предположим, вы даже не поленились и сформировали pull request. Но примут его далеко не сразу, а следующий релиз продукта вообще может произойти через год.
Что же делать, если исправление вам срочно нужно катить в прод? Напрашивается очевидное решение — использовать форк библиотеки или фреймворка. Однако с форками не всё просто. Использовать наследования для переопределения функциональности, которую нужно изменить, не всегда возможно и часто требует больших изменений. На помощь приходят плагины для Composer, которые умеют патчить зависимости.
В этой статье я расскажу подробнее о том, почему форки — это неудобно, а также рассмотрю два плагина для Composer для патчинга зависимостей: чем они отличаются, как ими пользоваться и в чём их преимущества. Если вы сталкивались подобными проблемами или вам просто интересно, добро пожаловать под кат.
Проблему удобнее всего рассматривать на примере. Давайте предположим, что мы хотим что-то изменить в библиотеке PHP Code Coverage, которая используется во фреймворке тестирования PHPUnit для измерения уровня покрытия кода тестами. Допустим, мы хотим исправить в версии 7.0.8 как-то так (файл myFix.patch ):
Создадим нашу библиотеку-пример. Пусть это будет php-composer-patches-example. Детали здесь не очень важны, но на случай если вы решите посмотреть, что из себя представляет библиотека, я привожу консольный вывод под спойлером.
Что не так с форком зависимости
Давайте посмотрим, как происходит форк зависимости. Попробуем форкнуть PHP Code Coverage.
Что с этим делать? Есть четыре варианта:
Второй и четвертый варианты кажутся меньшим из зол. По количеству действий они примерно одинаковые, в этой статье рассмотрим только один — четвертый. Создадим тег альфа-релиза:
Прошу обратить внимание на то, что php-composer-patches-example подключается как репозиторий, поскольку этот репозиторий является лишь примером и потому не был добавлен в Packagist. В вашем случае этот шаг, скорее всего, можно пропустить.
Подведём итоги использования форков.
Плюсы этого подхода:
Минусы этого подхода:
Я думаю, вы уже поняли, что форк зависимости не является такой уж хорошей идеей.
Использование cweagans/composer-patches
В очередной раз испытывая боль и страдания от использования форков, я наткнулся на cweagans/composer-patches в PHP-Дайджесте № 101 (кстати, у pronskiy полезный блог, рекомендую подписаться). Это плагин для Cоmposer, который позволяет применять патчи к зависимостям. Прочитав описание, я подумал, что это именно то, что нужно.
Как использовать cweagans/composer-patches:
Убеждаемся, что при установке нашей библиотеки в проекте патч тоже применится.
Добавляем в composer.json следущие строки:
Казалось бы, при подключении пакета должна была быть попытка применить патч, но нет.
Обновляем пакеты, чтобы применился патч, но этого не происходит:
Порывшись в баг-трекере, я нашёл баг File based patches aren’t resolved in dependencies. Получается, нужно либо указывать URL до патча (а значит, скачивать его откуда-то), либо указывать путь до патча вручную в каждом проекте, где вы устанавливаете зависимость, требующую патчей.
Плюсы этого подхода:
Последний пункт стал для меня барьером. Сначала я завёл feature request. Мейнтейнер написал, что не хочет добавлять эту фичу в основной код, но во второй версии можно будет написать плагин (да, плагин для плагина для Composer). Перспективы выхода второй версии были туманными, поэтому я решил поискать альтернативы. Среди небольшого списка я не нашёл плагина, который бы поддерживался.
Лезть в код плагина не хотелось, поэтому я решил прошерстить форки — наверняка кто-то уже сталкивался с проблемой и решил её.
Использование Vaimo Composer Patches
Такой хороший форк не должен теряться в куче других бесполезных форков. Поэтому я связался с автором с просьбой включить issues и добавить пакет на Packagist. Спустя почти месяц автор ответил и всё это сделал. 🙂
Использование vaimo/composer-patches не отличается от использования предыдущего плагина, но можно указывать разные патчи для разных версий.
Убеждаемся, что при установке нашей библиотеки в проекте патч тоже применится.
Создаём проект и устанавливаем mougrim/php-composer-patches-example :
На всякий случай можно убедиться, что наши изменения применились:
Плюсы этого плагина почти такие же, как у предыдущего, но ещё включают следующие:
Выводы
Подведём общие итоги:
Также я сделал косвенный вывод: если какая-то зависимость не предоставляет необходимый функционал, то, возможно, есть форки, которые реализовали этот функционал и даже больше.
В Badoo мы используем Vaimo Composer Patches в двух случаях:
Ринат Ахмадеев, Sr. PHP Developer
UPD1: Спасибо BoShurik за ссылку на алиасы. Добавил пункт про алиасы в статью.