Советы по использованию 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\Core\RouterFactory находится в файле /path/to/App/Core/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