Composer: советы по использованию
*********************************
<div class=perex>
Composer - инструмент управления зависимостями в PHP. Он позволяет объявить библиотеки, от которых зависит ваш проект, и сам их установит и обновит. Мы узнаем:
- как установить Composer
- как использовать его в новом или существующем проекте
</div>
Установка
=========
Composer - исполняемый файл `.phar`, который вы скачиваете и устанавливаете следующим образом.
Windows
-------
Воспользуйтесь официальным установщиком [Composer-Setup.exe|https://getcomposer.org/Composer-Setup.exe].
Linux, macOS
------------
Вам понадобятся всего 4 команды, которые можно скопировать с [этой страницы |https://getcomposer.org/download/].
Кроме того, скопировав его в папку, входящую в системный `PATH`, вы сделаете Composer доступным глобально:
```shell
$ mv ./composer.phar ~/bin/composer # или /usr/local/bin/composer
```
Использование в проекте
=======================
Чтобы начать использовать Composer в своём проекте, вам нужен только файл `composer.json`. Этот файл описывает зависимости вашего проекта и может содержать другие метаданные. Простейший `composer.json` может выглядеть так:
```js
{
"require": {
"nette/database": "^3.0"
}
}
```
Здесь мы говорим, что нашему приложению (или библиотеке) нужен пакет `nette/database` (имя пакета состоит из имени поставщика и имени проекта) и что нужна версия, отвечающая ограничению `^3.0` (то есть последняя версия 3).
Итак, имея файл `composer.json` в корне проекта, выполните:
```shell
composer update
```
Composer скачает Nette Database в каталог `vendor/`. Он также создаст файл `composer.lock`, в котором записано, какие именно версии библиотек были установлены.
Composer порождает файл `vendor/autoload.php`. Вы можете просто подключить этот файл и начать использовать классы библиотек без каких-либо дополнительных действий:
```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, вам пришлось бы перечислить их все в командной строке, например:
```shell
composer require nette/application nette/forms latte/latte tracy/tracy ...
```
Это непрактично. Поэтому воспользуйтесь простым скриптом "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, который сделает это за вас:
```shell
php composer-frontline.php
```
Создание нового проекта
=======================
Новый проект на Nette можно создать одной командой:
```shell
composer create-project nette/web-project name-of-the-project
```
Замените `name-of-the-project` на имя каталога вашего проекта и выполните команду. Composer скачает с GitHub репозиторий `nette/web-project`, в котором уже есть файл `composer.json`, а затем установит сам Nette Framework. Останется только [настроить права каталогов |nette:troubleshooting#Задание прав на каталоги] `temp/` и `log/`, и проект должен заработать.
Если вы знаете, на какой версии PHP будет размещён ваш проект, обязательно [задайте её |#Версия PHP].
Версия PHP
==========
Composer всегда устанавливает версии пакетов, совместимые с той версией PHP, которую вы сейчас используете (точнее, с версией PHP в командной строке, где запускается Composer). Она может отличаться от версии, которая используется на вашем хостинге. Поэтому принципиально важно добавить в файл `composer.json` сведения о версии PHP на хостинге. Тогда будут устанавливаться только версии пакетов, совместимые с хостингом.
Например, чтобы указать, что проект будет работать на PHP 8.2.3, используйте команду:
```shell
composer config platform.php 8.2.3
```
Версия запишется в файл `composer.json` вот так:
```js
{
"config": {
"platform": {
"php": "8.2.3"
}
}
}
```
Однако номер версии PHP указывается в файле и в другом месте, в секции `require`. Первое число определяет версию, под которую устанавливаются пакеты, а второе - версию, под которую написано само приложение. Например, PhpStorm по нему выставляет *PHP language level*. (Разумеется, различаться этим версиям смысла нет, так что двойная запись - недосмотр.) Задайте эту версию командой:
```shell
composer require php 8.2.3 --no-update
```
Или прямо в файле `composer.json`:
```js
{
"require": {
"php": "8.2.3"
}
}
```
Игнорирование версии PHP
========================
Пакеты обычно указывают и самую низкую версию PHP, с которой они совместимы, и самую высокую, на которой они были протестированы. Если вы собираетесь использовать ещё более новую версию PHP, скажем ради тестирования, Composer откажется устанавливать такой пакет. Решение - параметр `--ignore-platform-req=php+`, который заставляет Composer игнорировать верхние границы требуемой версии PHP.
Ложные сообщения
================
При обновлении пакетов или изменении номеров версий иногда возникают конфликты. У одного пакета требования конфликтуют с другим и так далее. Однако иногда Composer выдаёт ложные сообщения. Он сообщает о конфликте, которого на самом деле нет. В таких случаях может помочь удаление файла `composer.lock` и повторная попытка.
Если сообщение об ошибке не исчезает, значит оно настоящее, и вам нужно его прочитать, чтобы понять, что и как изменить.
Packagist.org - глобальный репозиторий
======================================
[Packagist |https://packagist.org] - главный репозиторий, в котором Composer по умолчанию ищет пакеты. Здесь вы можете публиковать и собственные пакеты.
А если нам не нужен центральный репозиторий
-------------------------------------------
Если внутри компании у нас есть приложения или библиотеки, которые нельзя размещать публично, мы можем создать для них собственные репозитории.
Подробнее о репозиториях читайте в [официальной документации |https://getcomposer.org/doc/05-repositories.md#repositories].
Автозагрузка
============
Ключевая возможность Composer в том, что он обеспечивает автозагрузку всех устанавливаемых им классов. Вы включаете её подключением файла `vendor/autoload.php`.
Однако Composer можно использовать и для загрузки других классов вне каталога `vendor/`. Первый вариант - позволить Composer просмотреть заданные каталоги и подкаталоги, найти все классы и включить их в автозагрузчик. Для этого задайте в `composer.json` секцию `autoload > classmap`:
```js
{
"autoload": {
"classmap": [
"src/", # включает каталог src/ и его подкаталоги
]
}
}
```
После этого вам придётся после каждого изменения выполнять команду `composer dumpautoload`, чтобы перегенерировать таблицы автозагрузки. Это крайне неудобно. Куда лучше поручить эту задачу [RobotLoader|robot-loader:], который делает то же самое автоматически в фоне и намного быстрее.
Второй вариант - придерживаться [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Проще говоря, это система, в которой пространства имён и имена классов соответствуют структуре каталогов и именам файлов, например `App\Core\RouterFactory` будет находиться в файле `/path/to/App/Core/RouterFactory.php`. Пример настройки:
```js
{
"autoload": {
"psr-4": {
"App\\": "app/" # пространство имён App\ находится в каталоге app/
}
}
}
```
Подробности о настройке этого поведения см. в [документации Composer |https://getcomposer.org/doc/04-schema.md#psr-4].
Тестирование новых версий
=========================
Хотите протестировать новую разрабатываемую версию пакета? Вот как это сделать. Сначала добавьте в файл `composer.json` эту пару параметров. Она разрешает установку разрабатываемых версий, но Composer прибегнет к ним только тогда, когда ни одно сочетание стабильных версий не отвечает требованиям:
```js
{
"minimum-stability": "dev",
"prefer-stable": true,
}
```
Мы также рекомендуем удалить файл `composer.lock`, потому что Composer иногда необъяснимо отказывается от установки, а это может решить проблему.
Допустим, пакет - `nette/utils`, а новая версия - 4.0. Установите её командой:
```shell
composer require nette/utils:4.0.x-dev
```
Или вы можете установить конкретную версию, например 4.0.0-RC2:
```shell
composer require nette/utils:4.0.0-RC2
```
Однако если от библиотеки зависит другой пакет и он привязан к более старой версии (например, `^3.1`), идеальным решением будет обновить этот зависимый пакет так, чтобы он работал с новой версией. Но если вы просто хотите обойти ограничение и заставить Composer установить разрабатываемую версию, притворившись, что это более старая версия (например, 3.1.6), вы можете использовать ключевое слово `as`:
```shell
composer require nette/utils "4.0.x-dev as 3.1.6"
```
Вызов команд
============
Вы можете вызывать через Composer собственные заранее заданные команды и скрипты так, будто это его родные команды. Для скриптов, лежащих в каталоге `vendor/bin`, указывать этот путь не нужно.
В качестве примера определим в `composer.json` скрипт, который использует [Nette Tester |tester:] для запуска тестов:
```js
{
"scripts": {
"tester": "tester tests -s"
}
}
```
Затем мы запускаем тесты командой `composer tester`. Команду можно вызвать, даже если вы находитесь не в корневом каталоге проекта, а в одном из его подкаталогов.
Скажите спасибо
===============
Покажем приём, который порадует авторов открытого кода. Вы можете легко поставить на GitHub звёзды библиотекам, которые использует ваш проект. Достаточно установить библиотеку `symfony/thanks`:
```shell
composer global require symfony/thanks
```
А затем выполнить:
```shell
composer thanks
```
Попробуйте!
Настройка
=========
Composer тесно интегрирован с системой контроля версий [Git |https://git-scm.com]. Если Git у вас не установлен, нужно сказать Composer, чтобы он его не использовал:
```shell
composer -g config preferred-install dist
```
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 (то есть последняя
версия 3).
Итак, имея файл composer.json в корне проекта, выполните:
composer update
Composer скачает Nette Database в каталог 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 скачает с GitHub репозиторий nette/web-project, в
котором уже есть файл composer.json, а затем установит сам Nette Framework.
Останется только настроить
права каталогов temp/ и log/, и проект должен заработать.
Если вы знаете, на какой версии PHP будет размещён ваш проект,
обязательно задайте её.
Версия PHP
Composer всегда устанавливает версии пакетов, совместимые с той версией
PHP, которую вы сейчас используете (точнее, с версией PHP в командной
строке, где запускается Composer). Она может отличаться от версии, которая
используется на вашем хостинге. Поэтому принципиально важно добавить
в файл composer.json сведения о версии PHP на хостинге. Тогда будут
устанавливаться только версии пакетов, совместимые с хостингом.
Например, чтобы указать, что проект будет работать на PHP 8.2.3,
используйте команду:
composer config platform.php 8.2.3
Версия запишется в файл composer.json вот так:
{
"config": {
"platform": {
"php": "8.2.3"
}
}
}
Однако номер версии PHP указывается в файле и в другом месте, в секции
require. Первое число определяет версию, под которую
устанавливаются пакеты, а второе – версию, под которую написано само
приложение. Например, PhpStorm по нему выставляет PHP language level.
(Разумеется, различаться этим версиям смысла нет, так что двойная
запись – недосмотр.) Задайте эту версию командой:
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 по
умолчанию ищет пакеты. Здесь вы можете публиковать и собственные
пакеты.
А если нам не нужен центральный
репозиторий
Если внутри компании у нас есть приложения или библиотеки, которые
нельзя размещать публично, мы можем создать для них собственные
репозитории.
Подробнее о репозиториях читайте в официальной документации.
Автозагрузка
Ключевая возможность Composer в том, что он обеспечивает автозагрузку
всех устанавливаемых им классов. Вы включаете её подключением файла
vendor/autoload.php.
Однако Composer можно использовать и для загрузки других классов вне
каталога vendor/. Первый вариант – позволить Composer просмотреть
заданные каталоги и подкаталоги, найти все классы и включить их в
автозагрузчик. Для этого задайте в composer.json секцию
autoload > classmap:
{
"autoload": {
"classmap": [
"src/", # включает каталог src/ и его подкаталоги
]
}
}
После этого вам придётся после каждого изменения выполнять команду
composer dumpautoload, чтобы перегенерировать таблицы автозагрузки. Это
крайне неудобно. Куда лучше поручить эту задачу RobotLoader, который делает то же самое
автоматически в фоне и намного быстрее.
Второй вариант – придерживаться PSR-4.
Проще говоря, это система, в которой пространства имён и имена классов
соответствуют структуре каталогов и именам файлов, например
App\Core\RouterFactory будет находиться в файле
/path/to/App/Core/RouterFactory.php. Пример настройки:
{
"autoload": {
"psr-4": {
"App\\": "app/" # пространство имён App\ находится в каталоге app/
}
}
}
Подробности о настройке этого поведения см. в документации Composer.
Тестирование новых версий
Хотите протестировать новую разрабатываемую версию пакета? Вот как
это сделать. Сначала добавьте в файл composer.json эту пару
параметров. Она разрешает установку разрабатываемых версий, но Composer
прибегнет к ним только тогда, когда ни одно сочетание стабильных
версий не отвечает требованиям:
{
"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 собственные заранее заданные команды и
скрипты так, будто это его родные команды. Для скриптов, лежащих в
каталоге 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