Инструмент управления зависимостями Composer предоставляет несколько способов включения репозиториев Git в проект PHP.
Во многих случаях репозитории были созданы на Packagist, поэтому их запрос с помощью Composer очень прост. Но что делать, если репозиторий не был создан как пакет на Packagist? Вы используете Composer, чтобы запросить пакет напрямую из репозитория. В этой статье объясняется, как это сделать.
Примечание: В терминологии можно запутаться, поэтому нужно пояснить. Вот краткий список слов, который поможет:
- Проект: Пользовательское программное обеспечение, которое вы создаете. Это может быть веб-сайт, утилита командной строки, приложение или что-то еще, что вы придумаете.
- Пакет: Любое стороннее программное обеспечение, которое вы хотите загрузить и использовать в своем проекте. Это может быть библиотека, тема Drupal, плагин WordPress или любое другое количество вещей.
- Репозиторий Git: Также называется репозиторием Git, это хост управления версиями для пакета. Обычные хосты включают GitHub, GitLab или Bitbucket, но для этого руководства подойдет любой доступный по URL репозиторий Git.
- Репозитории Composer: В
composer.jsonфайле есть необязательное свойство с именем «репозитории». Это свойство позволяет определить новые места, в которых Composer будет производить поиск при загрузке пакетов.
При добавлении репозитория Git в ваш проект с помощью Composer вы можете оказаться в двух ситуациях: либо репозиторий содержит файл composer.json, который определяет, как репозиторий должен обрабатываться при необходимости, либо нет. Вы можете добавить репозиторий Git в свой проект в обоих случаях, но разными методами.
Git-репозиторий с composer.json
Когда репозиторий включает composer.jsonфайл, он содержит всю необходимую информацию о себе и зависимостях. Вот пример простого composer.jsonфайла, который может включать пакет:
{
"name": "mynamespace/my-custom-library",
"type": "library"
}В этом примере показаны два важных свойства, которые composer.jsonможет определять файл:
- Имя: Имя пространства имен пакета. В этом случае “mynamespace” — это пространство имен для пакета “my-custom-library”.
- Тип: Тип пакета, который представляет репозиторий. Типы пакетов используются для логики установки. Из коробки Composer допускает следующие типы пакетов: library, project, metapackage, and composer-plugin.
Вы можете убедиться в этом, посмотрев на composer.jsonфайл любого популярного проекта GitHub. Каждый из них определяет свое имя пакета и тип пакета в верхней части файла. Когда репозиторий имеет эту информацию, определенную в своем composer.jsonфайле, требование репозитория в вашем проекте довольно просто.
Подключение Git репозитория, с файлом composer.json
После того, как вы создали/нашли репозиторий Git с composer.jsonфайлом, вы можете подключить этот репозиторий, как пакет в своем проекте.
В файле вашего проекта composer.jsonвам нужно определить новое свойство (предполагается, что оно еще не существует) с именем “repositories”. Значение свойства repositories представляет собой массив объектов, каждый из которых содержит информацию о репозитории, который вы хотите включить в свой проект. Рассмотрим composer.json вашего проекта.
{
"name": "mynamespace/my-project-that-uses-composer",
"repositories": [
{
"type": "vcs",
"url": "https://github.com/mynamespace/my-custom-library.git"
}
],
"require": {
"mynamespace/my-custom-library": "dev-master"
}
}
Здесь есть 2 важные вещи. Во-первых, вы определяете новый репозиторий, на который Composer может ссылаться при запросе пакетов. Во-вторых, вы запрашиваете пакет из нового определенного репозитория.
Примечание: версия пакета является частью оператора require , а не частью свойства репозитория . Вы можете подключить определенную ветку репозитория, выбрав версию с именем “dev-<имя ветки>”.
Если бы вы запустили composer installв контексте этого файла, Composer искал бы проект по указанному URL. Если этот URL представляет собой репозиторий Git, содержащий файл, composer.jsonопределяющий его имя и тип, Composer загрузит этот пакет в ваш проект и поместит его в соответствующее место.
Пользовательские типы пакетов
Пример пакета, показанный выше, относится к типу “библиотека”, но с WordPress и Drupal вы имеете дело с плагинами, модулями и темами. Когда требуются специальные типы пакетов в вашем проекте, важно установить их в определенных местах в файловой структуре проекта. Разве не было бы неплохо, если бы вы могли убедить Composer рассматривать эти типы пакетов как особые случаи? Что ж, вам повезло. Существует официальный плагин Composer, который сделает это за вас.
Плагин Installers для Composer содержит пользовательскую логику , необходимую для обработки множества различных типов пакетов для большого количества проектов. Он чрезвычайно полезен при работе с проектами, имеющими известные и поддерживаемые шаги установки пакетов.
Этот проект позволяет вам определять типы пакетов, такие как drupal-theme, drupal-module, wordpress-plugin, wordpress-theme и многие другие, для различных проектов. В случае пакета drupal-theme плагин Installers поместит требуемый репозиторий в папку /themes/contribвашей установки Drupal.
Вот пример файла composer.json, который может находиться в проекте темы Drupal как собственный репозиторий Git:
{
"name": "mynamespace/whatever-i-call-my-theme",
"type": "drupal-theme",
"description": "Drupal 8 theme",
"license": "GPL-2.0+"
}
Обратите внимание, что единственное значимое отличие здесь в том, что тип теперь drupal-theme. С определенным типом drupal-theme любой проект, использующий плагин Installers, может легко потребовать ваш репозиторий в своем проекте Drupal, и он будет рассматриваться как добавленная тема.
Как подключить любой репозиторий Git в Composer
Что происходит, когда репозиторий, который вы хотите включить в свой проект, не определяет ничего о себе с помощью composer.jsonфайла? Когда репозиторий не определяет свое имя или тип, вам нужно определить эту информацию для репозитория в composer.jsonфайле вашего проекта. Взгляните на этот пример:
{
"name": "mynamespace/my-project-that-uses-composer",
"repositories": [
{
"type": "package",
"package": {
"name": "mynamespace/my-custom-theme",
"version": "1.2.3",
"type": "drupal-theme",
"source": {
"url": "https://github.com/mynamespace/my-custom-theme.git",
"type": "git",
"reference": "master"
}
}
}
],
"require": {
"mynamespace/my-custom-theme": "^1",
"composer/installers": "^1"
}
}
Обратите внимание, что тип вашего репозитория теперь «пакет». Именно здесь вы определите все о пакете, который вам нужен.
Создайте новый объект с именем «package», в котором вы определяете всю необходимую информацию, которую Composer должен знать, чтобы иметь возможность включить этот произвольный репозиторий git в ваш проект, включая:
- Имя: Имя пакета в пространстве имен. Вероятно, оно должно совпадать с требуемым вам репозиторием, но это не обязательно.
- Тип: Тип пакета. Это отражает то, как вы хотите, чтобы Composer обрабатывал этот репозиторий.
- Версия: Номер версии репозитория. Вам нужно будет придумать это.
- Источник: объект, содержащий следующую информацию о репозитории:
- URL: URL Git или другой системы контроля версий (VCS), где можно найти репозиторий пакета.
- Тип: Тип VCS для пакета, например git, svn, cvs и т. д.
- Ссылка: Ветвь или тег, который вы хотите загрузить.
Я рекомендую просмотреть официальную документацию по репозиториям пакетов Composer. Обратите внимание, что можно также включать zip-файлы, как пакеты Composer. По сути, теперь вы несете ответственность за все части того, как Composer обрабатывает этот репозиторий. Поскольку сам репозиторий не предоставляет Composer никакой информации, вы несете ответственность за определение почти всего, включая текущий номер версии пакета.
Такой подход позволяет вам включать в свой проект практически все, что угодно, в качестве пакета Composer, но у него есть несколько существенных недостатков:
- Composer не обновит пакет, пока вы не измените
versionполе. - Composer не обновит ссылки на коммиты. Если вы используете
masterв качестве ссылки, вам придется удалить пакет, чтобы принудительно обновиться, и вам придется иметь дело с нестабильным файлом блокировки.
Пользовательские версии пакетов
Поддержание версии пакета в вашем composer.jsonфайле не всегда необходимо. Composer достаточно умен, чтобы искать релизы GitHub и использовать их в качестве версий пакета. Но в конечном итоге вы, вероятно, захотите включить простой проект, который имеет всего несколько веток и не имеет официальных релизов.
Если в репозитории нет релизов, вы будете нести ответственность за решение того, какую версию представляет ветвь репозитория для вашего проекта. Другими словами, если вы хотите, чтобы Composer обновил пакет, вам нужно будет увеличить «версию», определенную в composer.jsonфайле вашего проекта, перед запуском composer update.
Переопределение composer.json репозитория Git
При определении нового репозитория Composer типа package вы можете переопределить собственные composer.jsonопределения пакета. Рассмотрим репозиторий Git, который определяет себя как библиотеку в своем composer.json, но вы знаете, что код на самом деле является темой drupal. Вы можете использовать описанный выше подход для включения репозитория Git в свой проект как темы drupal, что позволит Composer обрабатывать код соответствующим образом, когда это необходимо.
Пример: Потребуйте Guzzle в качестве темы Drupal, просто чтобы доказать, что вы можете это сделать.
{
"name": "mynamespace/my-project-that-uses-composer",
"repositories": [
{
"type": "package",
"package": {
"name": "mynamespace/guzzle-theme",
"version": "1.2.3",
"type": "drupal-theme",
"source": {
"url": "https://github.com/guzzle/guzzle.git",
"type": "git",
"reference": "master"
}
}
}
],
"require": {
"mynamespace/guzzle-theme": "^1",
"composer/installers": "^1"
}
}
Это работает! Вы загрузили библиотеку Guzzle и поместили ее в /themesпапку вашего проекта Drupal. Это не очень практичный пример, но он показывает, насколько гибкой может быть система Composer.