Бинарные файлы вендора и каталог vendor/bin в Composer

• Что такое бинарный файл вендора в Composer?
• Как определяется бинарный файл вендора в Composer?
• Что дает определение бинарных файлов поставщика в composer.json?
• Что происходит, когда в Composer запускается сайт composer.json, в котором определены бинарные файлы поставщика?
• Что произойдет, если запустить Composer с composer.json, в котором перечислены зависимости с бинарными файлами поставщиков?
• Поиск автозагрузчика Composer из бинарного файла
• Поиск bin-dir Composer из бинарного файла.
• А как насчет Windows и .bat-файлов?
• Можно ли установить бинарные файлы поставщика куда-то еще, кроме vendor/bin?

Что такое бинарный файл вендора в Composer?

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

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

Как определяется бинарный файл вендора в Composer?

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

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

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

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 просмотрит все двоичные файлы project-a и установит их в 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, поддерживающей эту функцию.

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

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

Для не-PHP бинарных файлов, начиная с Composer 2.2.6, bin proxy устанавливает переменную окружения 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.

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

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

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

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

Перевод с английского официальной документации Composer:
https://getcomposer.org/doc/articles/vendor-binaries.md

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)