Поради щодо використання Composer

Composer – це інструмент для управління залежностями в PHP. Він дає змогу вам оголосити бібліотеки, від яких залежить ваш проєкт, і він встановлюватиме та оновлюватиме їх за вас. Ми дізнаємося:

  • як встановити Composer
  • використовувати його в новому або наявному проєкті

Встановлення

Composer – це виконуваний файл .phar, який ви завантажуєте та встановлюєте таким чином.

Windows

Використовуйте офіційну програму встановлення Composer-Setup.exe.

Linux, macOS

Усе, що вам потрібно, це 4 команди, які ви можете скопіювати з цієї сторінки.

Ба більше, під час копіювання в папку, що знаходиться в системному PATH, Composer стає глобально доступним:

$ mv ./composer.phar ~/bin/composer # или /usr/local/bin/composer

Використання в наявному проєкті

Щоб почати використовувати Composer у своєму проєкті, все, що вам потрібно, це файл composer.json. Цей файл описує залежності вашого проекту і може містити інші метадані. Найпростіший composer.json може виглядати наступним чином:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Тут ми говоримо, що наш додаток (або бібліотека) залежить від пакета nette/database (ім'я пакета складається з імені постачальника та імені проєкту), і йому потрібна версія, що відповідає обмеженню ^3.0.

Отже, коли у нас є файл composer.json у корені проєкту і ми запускаємо:

composer update

Composer завантажить вихідні файли Nette в каталог vendor. Він також створює файл composer.lock, який містить інформацію про те, які саме версії бібліотек встановлені.

Composer генерує файл vendor/autoload.php. Ви можете просто включити цей файл і почати використовувати класи, які надають ці бібліотеки, без зайвої роботи:

require __DIR__ . '/vendor/autoload.php';

$db = new Nette\Database\Connection('sqlite::memory:');

Оновлення пакетів до останніх версій

Для оновлення всіх використовуваних пакетів до останньої версії відповідно до обмежень версій, визначених у файлі composer.json, використовуйте команду composer update. Наприклад, для залежності "nette/database": "^3.0" буде встановлено останню версію 3.x.x, але не версію 4.

Щоб оновити обмеження версії у файлі composer.json на, наприклад, “nette/database”: “^4.1”, для установки последней версии, используйте команду `composer require nette/database.

Щоб оновити всі використовувані пакети Nette, необхідно перерахувати їх усі в командному рядку, наприклад:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Що непрактично. Тому використовуйте простий сценарій Composer Frontline, який зробить це за вас:

php composer-frontline.php

Створення нового проєкту

Новий проект Nette можна створити, виконавши просту команду:

composer create-project nette/web-project name-of-the-project

Замість name-of-the-project вкажіть ім'я каталогу для вашого проєкту і виконайте команду. Composer отримає репозиторій nette/web-project з GitHub, який вже містить файл composer.json, і відразу після цього встановить сам фреймворк Nette. Залишилося тільки перевірити права на запис для директорій temp/ і log/, і ви готові до роботи.

Якщо ви знаєте, на якій версії PHP буде розміщено проект, обов'язково встановіть її.

Версія PHP

Composer завжди встановлює версії пакунків, сумісні з версією PHP, яку ви зараз використовуєте (точніше, з версією PHP, яка використовується у командному рядку під час запуску Composer). А це, ймовірно, не та версія, яку використовує ваш веб-хостинг. Ось чому дуже важливо додати інформацію про версію PHP на вашому хостингу до файлу composer.json. Після цього будуть встановлені лише версії пакунків, сумісні з хостом.

Наприклад, щоб налаштувати роботу проекту на PHP 8.2.3, скористайтеся командою:

composer config platform.php 8.2.3

Таким чином версія буде записана у файл composer.json:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

Однак, номер версії PHP також вказано в іншому місці файлу, в розділі require. У той час як перше число вказує на версію, для якої будуть встановлені пакунки, друге число вказує на версію, для якої написано саму програму. (Звичайно, немає сенсу, щоб ці версії відрізнялися, тому подвійний запис є надмірністю). Ви встановлюєте цю версію за допомогою команди:

composer require php 8.2.3 --no-update

Або безпосередньо у файлі composer.json:

{
	"require": {
		"php": "8.2.3"
	}
}

Ігнорування версії PHP

Пакунки зазвичай вказують як найнижчу версію PHP, з якою вони сумісні, так і найвищу версію, з якою вони були протестовані. Якщо ви плануєте використовувати ще новішу версію PHP, можливо, з метою тестування, Composer відмовиться встановлювати такий пакунок. Вирішенням проблеми є використання параметра --ignore-platform-req=php+, який змушує Composer ігнорувати верхні межі необхідної версії PHP.

Неправдиві повідомлення

При оновленні пакунків або зміні номерів версій виникають конфлікти. Один пакунок має вимоги, які конфліктують з іншим і так далі. Утім, іноді Composer видає хибні повідомлення. Він повідомляє про конфлікт, якого насправді не існує. У цьому випадку рекомендується видалити файл composer.lock і спробувати ще раз.

Якщо повідомлення про помилку не зникає, це означає, що проблема серйозна, і вам потрібно прочитати, що і як потрібно змінити.

Packagist.org – глобальний репозиторій

Packagist – це основне сховище пакетів, в якому Composer намагається шукати пакети, якщо не сказано інакше. Ви також можете опублікувати тут свої власні пакети.

Що якщо нам не потрібен центральний репозиторій

Якщо в нашій компанії є внутрішні додатки або бібліотеки, які не можуть бути розміщені публічно на Packagist, ми можемо створити власні репозиторії для цих проєктів.

Детальніше про репозиторії в офіційній документації.

Автозавантаження

Ключовою особливістю Composer є те, що він забезпечує автозавантаження для всіх класів, що встановлюються, яке ви запускаєте, увімкнувши файл vendor/autoload.php.

Однак можна також використовувати Composer для завантаження інших класів поза папкою vendor. Перший варіант – дозволити Composer просканувати певні папки та підпапки, знайти всі класи та включити їх в автозавантаження. Для цього встановіть autoload > classmap у файлі composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  включает папку src/ со всеми вложенными директориями
		]
	}
}

Згодом необхідно виконувати команду composer dumpautoload при кожній зміні та дозволяти таблицям автозавантаження регенеруватися. Це вкрай незручно, і набагато краще довірити цю задачу RobotLoader, який виконує ту ж саму роботу автоматично у фоновому режимі і набагато швидше.

Другий варіант – слідувати PSR-4. Простіше кажучи, це система, в якій простори імен та імена класів відповідають структурі каталогів та іменам файлів, тобто App\Router\RouterFactory знаходиться у файлі /path/to/App/Router/RouterFactory.php. Приклад конфігурації:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # пространство имён App\ указывает на директорию app/
		}
	}
}

Як саме налаштувати цю поведінку, дивіться в документації Composer.

Тестування нових версій

Ви хочете протестувати нову версію пакета. Як це зробити? По-перше, додайте цю пару опцій до файлу composer.json, яка дозволить вам встановлювати версії пакетів для розробки, але зробить це тільки в тому випадку, якщо немає стабільної версії, що відповідає вимогам:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Ми також рекомендуємо видалити файл composer.lock, оскільки іноді Composer незрозумілим чином відмовляється встановлюватися, і це вирішить проблему.

Припустимо, пакет – nette/utils і нова версія – 4.0. Ви встановлюєте його за допомогою команди:

composer require nette/utils:4.0.x-dev

Або ви можете встановити конкретну версію, наприклад, 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Якщо інший пакет залежить від бібліотеки і заблокований на старішу версію (наприклад, ^3.1), ідеально буде оновити пакет для роботи з новою версією. Однак якщо ви просто хочете обійти обмеження і змусити Composer встановити версію розробки і прикинутися, що це стара версія (наприклад, 3.1.6), ви можете використовувати ключове слово as:

composer require nette/utils "4.0.x-dev as 3.1.6"

Команди виклику

Ви можете викликати свої власні користувацькі команди і сценарії через Composer, як якщо б це були рідні команди Composer. Скриптам, розташованим у папці vendor/bin, не потрібно вказувати цю папку.

Як приклад ми визначаємо сценарій у файлі composer.json, який використовує Nette Tester для запуску тестів:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

Потім ми запускаємо тести за допомогою composer tester. Ми можемо викликати команду, навіть якщо перебуваємо не в кореневій папці проєкту, а в підкаталозі.

Надішліть подяку

Ми покажемо вам трюк, який порадує авторів відкритих вихідних кодів. Ви можете легко присвоїти зірку на GitHub бібліотекам, які використовує ваш проект. Просто встановіть бібліотеку symfony/thanks:

composer global require symfony/thanks

А потім наберіть:

composer thanks

Спробуйте!

Конфігурація

Composer тісно інтегрований з інструментом контролю версій Git. Якщо ви не використовуєте Git, необхідно повідомити про це Composer:

composer -g config preferred-install dist