Бинарные файлы поставщика и каталог vendor/bin

Что такое бинарный файл поставщика?

Любой командный скрипт, который пакет Composer хочет передать пользователю, устанавливающему пакет, должен быть указан как бинарный файл поставщика.

Если пакет содержит другие скрипты, которые не нужны пользователям пакета (например, скрипты сборки или компиляции), то этот код не следует указывать как бинарный файл поставщика.

Как это определяется?

Это определяется добавлением ключа bin в composer.json проекта. Он задаётся как массив файлов, поэтому для любого проекта можно добавить несколько бинарных файлов.

{
    "bin": ["bin/my-script", "bin/my-other-script"]
}

Что происходит при определении бинарного файла поставщика в composer.json?

Это указывает Composer на установку бинарных файлов пакета в vendor/bin для любого проекта, который зависит от этого проекта.

Это удобный способ экспонировать полезные скрипты, которые в противном случае были бы скрыты глубоко в каталоге vendor/.

Что происходит при запуске Composer на composer.json, определяющем бинарные файлы поставщика?

Для бинарных файлов, непосредственно определённых пакетом, ничего не происходит.

Что происходит при запуске Composer на composer.json, содержащем зависимости с указанными бинарными файлами поставщика?

Composer ищет бинарные файлы, определённые во всех зависимостях. Прокси-файл (или два в Windows/WSL) создаётся для каждого бинарного файла зависимости, помещая их в vendor/bin.

Предположим, пакет my-vendor/project-a настроен следующим образом:

{
    "name": "my-vendor/project-a",
    "bin": ["bin/project-a-bin"]
}

Запуск composer install для этого composer.json не повлияет на bin/project-a-bin.

Предположим, проект my-vendor/project-b имеет зависимости, заданные так:

{
    "name": "my-vendor/project-b",
    "require": {
        "my-vendor/project-a": "*"
    }
}

Запуск composer install для этого composer.json найдёт все бинарные файлы проекта-а и установит их в vendor/bin.

В этом случае Composer сделает vendor/my-vendor/project-a/bin/project-a-bin доступным как vendor/bin/project-a-bin.

Поиск автозагрузчика Composer из бинарного файла

Начиная с Composer 2.2, новая глобальная переменная $_composer_autoload_path определяется прокси-файлом bin, позволяя вашему бинарному файлу легко найти автозагрузчик проекта.

Однако эта глобальная переменная недоступна при запуске бинарных файлов, определённых самим корневым пакетом, поэтому вам необходима резервная копия.

Пример выглядит следующим образом:

<?php

include $_composer_autoload_path ?? __DIR__ . '/../vendor/autoload.php';

Если вы хотите использовать это в своём пакете, убедитесь, что также указана зависимость "composer-runtime-api": "^2.2", чтобы пакет был установлен с версией Composer, поддерживающей эту функцию.

Поиск каталога Composer bin из бинарного файла

Начиная с Composer 2.2.2, новая глобальная переменная $_composer_bin_dir определяется прокси-файлом bin, позволяя вашему бинарному файлу легко найти каталог bin проекта Composer.

Для бинарных файлов, не являющихся PHP, начиная с Composer 2.2.6, прокси-файл bin устанавливает переменную окружения COMPOSER_RUNTIME_BIN_DIR.

Эта глобальная переменная недоступна при запуске бинарных файлов, определённых самим корневым пакетом, поэтому вам необходима резервная копия.

Пример выглядит следующим образом:

<?php

$binDir = $_composer_bin_dir ?? __DIR__ . '/../vendor/bin';

#!/bin/bash

if [[ -z "$COMPOSER_RUNTIME_BIN_DIR" ]]; then
  BIN_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
else
  BIN_DIR="$COMPOSER_RUNTIME_BIN_DIR"
fi

Если вы хотите использовать это в своём пакете, убедитесь, что также указана зависимость "composer-runtime-api": "^2.2.2", чтобы пакет был установлен с версией Composer, поддерживающей эту функцию.

Что насчёт Windows и файлов .bat?

Пакеты, полностью управляемые Composer, не нуждаются в файлах .bat для совместимости с Windows. Composer обрабатывает установку бинарных файлов особым образом при запуске в среде Windows:

• Файл .bat генерируется автоматически для ссылки на бинарный файл.
• Также генерируется прокси-файл в стиле Unix с тем же именем, что и бинарный файл, который полезен для WSL, виртуальных машин Linux и т. д.

Пакеты, которым требуется поддержка сценариев, не включающих Composer, могут сохранить пользовательские файлы .bat. В этом случае пакет не должен указывать файл .bat как бинарный, так как он не нужен.

Можно ли установить бинарные файлы поставщика в другое место, кроме vendor/bin?

Да, есть два способа указать альтернативное расположение бинарных файлов поставщика:

1. Установите параметр конфигурации bin-dir в composer.json.
2. Установите переменную среды COMPOSER_BIN_DIR.

Пример первого способа выглядит так:

{
    "config": {
        "bin-dir": "scripts"
    }
}

Запуск composer install для этого composer.json приведёт к установке всех бинарных файлов поставщика в scripts/ вместо vendor/bin/.

Вы можете установить bin-dir в ./, чтобы поместить бинарные файлы в корневой каталог проекта.