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