Нерідкі випадки, коли ми хочемо використовувати композитор для включення Git-репозиторіїв у наш проект PHP. У багатьох випадках репозиторії були створені на packagist.org, і вимагати їх за допомогою композитора дуже просто. Але що робити, коли репозиторій не був створений як пакет на packagist? Відповідь полягає в тому, що ми використовуємо composer, щоб вимагати пакет безпосередньо зі сховища.
Примітка: Деяка термінологія в публікації заплутана, оскільки для опису різних речей використовується кілька слів. Ось короткий список словникового запасу, який допоможе:
- Проект - Спеціальне програмне забезпечення, яке ми створюємо. Це може бути веб-сайт, утиліта командного рядка, додаток або що-небудь ще, що ми вигадуємо.
- Пакет - Будь-яке програмне забезпечення 3rd, яке ми хочемо завантажити та використовувати в нашому проекті. Це може бути бібліотека, тема Drupal, плагін WordPress або будь-яка інша кількість речей.
- Git репозиторій – AKA, Git репозиторій. Хост керування версіями для пакета. Поширеними хостами є: GitHub, GitLab або Bitbucket; але будь-який репозиторій Git, доступний за URL-адресою, підійде для цього підручника.
- Compositories – у файлі composer.json є необов'язкова властивість з назвою "repositories". За допомогою цієї властивості ми можемо визначити нові місця, на які Composer буде звертати увагу під час завантаження пакунків.
При додаванні Git-репозиторію до нашого проекту з композитором є дві ситуації, в яких ми можемо опинитися: репозиторій містить файл composer.json і визначає, як репозиторій повинен оброблятися, коли це потрібно, або ні. Незважаючи на це, в обох випадках ми можемо додати репозиторій Git до нашого проекту.
Почнемо з Git-репозиторію, який визначив файл composer.json.
Git repo з composer.json Коли репозиторій містить файл composer.json
, він визначає самі аспекти, важливі для того, як композитор керує пакунком. Ось приклад простого файлу composer.json, який може містити пакет.
{
"name": "daggerhart/my-custom-library",
"type": "library"
}composer.json
Показано дві важливі властивості, які може визначити файл composer.json:
- name: ім'я пакунка з простором імен. У цьому випадку daggerhart є простором імен для пакета my-custom-library.
- тип: Тип пакета, який представляє репозиторій. Типи пакетів використовуються для логіки установки. З коробки композитор підтримує наступні типи пакунків: бібліотека, проект, метапакет, композитор-плагін.
Переконатися в цьому можна, подивившись файл composer.json будь-якого популярного проекту. Кожен з них визначає ім'я пакета та тип пакета у верхній частині файлу.
Коли репозиторій має цю інформацію, визначену у файлі composer.json, вимагати створення репозиторію в нашому проекті відносно просто.
Потрібен Git-репозиторій, який містить файл
composer.json Тепер, коли ми визначили репозиторій GIt з файлом composer.json, давайте вимагатимемо цей репозиторій як пакет у нашому проекті.
У файлі composer.json нашого проекту нам потрібно визначити нову властивість (за умови, що її ще не існує) з назвою "repositories". Значенням властивості репозиторіїв є масив об'єктів. Кожен об'єкт, що містить інформацію про репозиторій, ми хочемо включити в наш проект. Розглянемо цей файл composer.json для нашого власного проекту.
{
"name": "daggerhart/my-project-that-uses-composer",
"repositories": [
{
"type": "vcs",
"url": "https://github.com/daggerhart/my-custom-library.git"
}
],
"require": {
"daggerhart/my-custom-library": "dev-master"
}
}composer.json
Тут ми робимо дві важливі речі. По-перше, ми визначаємо новий репозиторій, на який композитор може посилатися, коли потрібні пакунки. А по-друге, нам потрібен пакет з нововизначеного репозиторію.
Примітка: Версія пакета є частиною інструкції demand, а не частиною властивості repository. Ми можемо вимагати певну гілку репо, вибравши версію з назвою "dev-<назва філії>".
Якби ми працювали composer install в контексті цього файлу, композитор шукав би проект за визначеною URL-адресою, і якщо ця URL-адреса представляє Git-репозиторій, який містить файл composer.json, який визначає його ім'я та тип, композитор завантажить цей пакунок до нашого проекту та розмістить його у відповідному місці.
Користувацькі типи
пакетів Приклад пакета, показаний вище, має тип "бібліотека", але часто в нашій роботі з WordPress і Drupal ми маємо справу з плагінами, модулями і темами. Якщо в нашому проекті потрібні спеціальні типи пакунків, важливо, щоб вони були встановлені в певних місцях у файловій структурі проекту. Хіба не було б добре, якби ми змогли переконати композитора ставитися до таких типів пакунків як до особливих випадків? Що ж, нам пощастило. Існує офіційний композитор-плагін, який зробить це за нас.
composer/installers – плагін Installers composer містить користувацьку логіку, необхідну для роботи з багатьма різними типами пакунків для великої кількості різноманітних проектів. Це надзвичайно корисно при роботі з проектами, які мають добре відомі та підтримувані етапи встановлення пакетів.
Цей проект дозволяє нам визначати типи пакетів, такі як: drupal-theme, drupal-module, wordpress-plugin, wordpress-theme та багато інших, для різних проектів. У випадку пакета drupal-theme, плагін composer/installers розмістить необхідний репозиторій в папці /themes/contrib нашої установки на Drupal.
Ось приклад файлу composer.json, який може жити в рамках проекту теми Drupal як власний Git-репозиторій:
{
"name": "daggerhart/whatever-i-call-my-theme",
"type": "drupal-theme",
"description": "Drupal 8 theme",
"license": "GPL-2.0+"
}composer.json
Зверніть увагу, що єдина важлива відмінність тут полягає в тому, що "тип" тепер є "drupal-theme". З визначенням типу drupal-theme, будь-який проект, який використовує плагін композитора / інсталяторів, може легко вимагати нашого репозиторію в їх проекті Drupal, і він буде розглядатися як тема внеску.
Вимагати будь-якого Git-репозиторію з Composer Тепер, коли ми знаємо, як вимагати Git-репозиторію, який містить файл composer.json, давайте розглянемо випадок, коли репозиторій, який ми хочемо включити в наш проект, нічого не визначає про себе з файлом composer.json.
Коротше кажучи, коли репо не визначає свою назву або тип, ми повинні визначити цю інформацію для репозиторію у файлі composer.json нашого проекту. Погляньте на цей приклад:
{
"name": "daggerhart/my-project-that-uses-composer",
"repositories": [
{
"type": "package",
"package": {
"name": "daggerhart/my-custom-theme",
"version": "1.2.3",
"type": "drupal-theme",
"source": {
"url": "https://github.com/daggerhart/my-custom-theme.git",
"type": "git",
"reference": "master"
}
}
}
],
"require": {
"daggerhart/my-custom-theme": "^1",
"composer/installers": "^1"
}
}composer.json
Зверніть увагу, що наш тип репозиторію тепер "package". Саме тут ми збираємося визначити все про пакет, який ми хочемо вимагати. Далі ми створюємо новий об'єкт з назвою "package", де визначаємо всю важливу інформацію, яку композитор повинен знати, щоб мати можливість включити цей довільний git repo в наш проект. Включаючи:
- name – ім'я пакета з інтервалом імен. Ймовірно, він повинен відповідати репозиторію, який нам потрібен, але не обов'язково.
- тип – Тип упаковки. Як ми хочемо, щоб композитор ставився до цього сховища.
- version – вигаданий номер версії для репозиторію.
-
source – Об'єкт, що містить наступну інформацію про сховище:
- url – URL-адреса Git (або іншого VCS), де можна знайти репозиторій пакета.
- type – тип VCS для пакета. git, svn, cvs (?) ... Тощо.
- посилання – гілка або тег, який потрібно завантажити.
Я рекомендую переглянути офіційну документацію щодо репозиторіїв композиторних пакетів. Зауважте, що можна також включити zip-файли як пакети компонування.
По суті, тепер ми несемо відповідальність за всі частини того, як композитор ставиться до цього сховища. Оскільки сам репозиторій не надає композитору жодної інформації, ми несемо відповідальність за визначення майже всього, включаючи номер поточної версії пакета.
Такий підхід дозволяє нам включити в наш проект майже все, що завгодно, але він має деякі недоліки. Помітні недоліки:
- Composer не оновлюватиме пакет, якщо ви не зміните
versionполе. - Composer не оновлюватиме посилання на фіксацію, тому, якщо ви використовуєте
masterяк посилання, вам доведеться видалити пакет, щоб примусово оновити, і доведеться мати справу з нестабільним файлом блокування.
Користувацькі версії пакетів Підтримка версії
пакета в нашому файлі composer.json не завжди потрібна. Composer досить розумний, щоб шукати релізи GitHub і використовувати їх як версії пакетів. Але врешті-решт ми виявимо, що захочемо включити простий проект, який має лише кілька філій і не має офіційних релізів.
Якщо репозиторій не має релізів, ми несемо відповідальність за прийняття рішення про те, яку версію гілка репозиторію представляє для нашого проекту. Іншими словами, якщо ми хочемо, щоб композитор оновив пакет, нам потрібно буде збільшити "версію", визначену у файлі composer.json нашого проекту, перш ніж запускати composer update.
Перевизначення файлу compository.json Git-репозиторію Цікавою річчю, яку ми можемо зробити, визначаючи новий композиторний репозиторій пакета типів, є заміна власних визначень пакунка composer.json.
Розглянемо, що Git-репозиторій визначає себе як бібліотеку у своєму composer.json, але ми знаємо, що код насправді є drupal-темою. Ми можемо використати цей вищевказаний підхід для включення репозиторію Git до нашого проекту як drupal-теми, що дозволить композитору належним чином ставитися до коду, коли це необхідно.
Приклад: вимагати Guzzle як drupal-теми тільки для того, щоб довести, що ми можемо.
{
"name": "daggerhart/my-project-that-uses-composer",
"repositories": [
{
"type": "package",
"package": {
"name": "daggerhart/guzzle-theme",
"version": "1.2.3",
"type": "drupal-theme",
"source": {
"url": "https://github.com/guzzle/guzzle.git",
"type": "git",
"reference": "master"
}
}
}
],
"require": {
"daggerhart/guzzle-theme": "^1",
"composer/installers": "^1"
}
}composer.json
Це працює! Це завантажить бібліотеку Guzzle і розмістить її в папці /themes мого проекту на Drupal. Очевидно, що це не дуже практичний приклад, але, сподіваюся, він підкреслює, наскільки контролює підхід типу упаковки.
Summary
Composer пропонує нам безліч варіантів включення довільних пакетів в наш проект. Питання про те, як ці пакети включені в проект, в першу чергу зводиться до «хто визначає інформацію про пакет?». Якщо репозиторій Git містить файл composer.json, який визначає його ім'я та тип, тоді ми можемо попросити композитора покладатися на сам репозиторій для визначення. Але якщо ми хочемо включити репозиторій, який не визначає його назву та тип, то наш проект повинен визначити та підтримувати цю інформацію для нашого власного внутрішнього використання.
Крім того, якщо репозиторій не визначає файл composer.json, розгляньте можливість подання pull-запиту, який додає його. ?
Посилання:
