Сценарии

Что такое сценарий?

Сценарий, в терминах Composer, может быть как обратным вызовом PHP (определённым как статический метод), так и любой командой исполняемой из командной строки. Сценарии полезны для выполнения пользовательского кода пакета или пакетно-специфичных команд во время процесса выполнения Composer.

Примечание: Выполняются только сценарии, определённые в корневом пакете в composer.json. Если зависимость корневого пакета определяет свои сценарии, Composer не выполняет эти дополнительные сценарии.

Имена событий

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

События команд

• pre-install-cmd: происходит перед выполнением команды install при наличии файла блокировки.
• post-install-cmd: происходит после выполнения команды install при наличии файла блокировки.
• pre-update-cmd: происходит перед выполнением команды update или перед выполнением команды install без файла блокировки.
• post-update-cmd: происходит после выполнения команды update или после выполнения команды install без файла блокировки.
• pre-status-cmd: происходит перед выполнением команды status.
• post-status-cmd: происходит после выполнения команды status.
• pre-archive-cmd: происходит перед выполнением команды archive.
• post-archive-cmd: происходит после выполнения команды archive.
• pre-autoload-dump: происходит перед выгрузкой автозагрузчика, как во время install/update, так и с помощью команды dump-autoload.
• post-autoload-dump: происходит после выгрузки автозагрузчика, как во время install/update, так и с помощью команды dump-autoload.
• post-root-package-install: происходит после установки корневого пакета во время команды create-project (но перед установкой его зависимостей).
• post-create-project-cmd: происходит после выполнения команды create-project.

События установщика

• pre-operations-exec: происходит перед выполнением операций установки/обновления/.. при установке файла блокировки. Плагины, которым необходимо подключиться к этому событию, должны быть установлены глобально, чтобы быть доступными, так как в противном случае они не будут загружены при первой установке проекта.

События пакета

• pre-package-install: происходит перед установкой пакета.
• post-package-install: происходит после установки пакета.
• pre-package-update: происходит перед обновлением пакета.
• post-package-update: происходит после обновления пакета.
• pre-package-uninstall: происходит перед удалением пакета.
• post-package-uninstall: происходит после удаления пакета.

События плагина

• init: происходит после завершения инициализации экземпляра Composer.
• command: происходит перед выполнением любой команды Composer в командной строке. Он предоставляет доступ к объектам ввода и вывода программы.
• pre-file-download: происходит перед загрузкой файлов и позволяет манипулировать объектом HttpDownloader перед загрузкой файлов на основе URL, который нужно загрузить.
• post-file-download: происходит после загрузки файлов распределения пакета и позволяет выполнять дополнительные проверки файла при необходимости.
• pre-command-run: происходит перед выполнением команды и позволяет манипулировать параметрами объекта InputInterface и аргументами, чтобы настроить поведение команды.
• pre-pool-create: происходит перед созданием пула пакетов и позволяет фильтровать список пакетов, которые войдут в решатель.

Примечание: Composer не делает никаких предположений о состоянии ваших зависимостей до install или update. Поэтому вы не должны указывать сценарии, которые требуют зависимостей, управляемых Composer, в событиях хуков pre-update-cmd или pre-install-cmd. Если вам нужно выполнить сценарии до install или update, убедитесь, что они самодостаточны в вашем корневом пакете.

Определение сценариев

Корневой JSON-объект в composer.json должен иметь свойство "scripts", которое содержит пары именованных событий и соответствующих сценариев каждого события. Сценарии события могут быть определены как строка (только для одного сценария) или массив (для одного или нескольких сценариев).

Для любого данного события:

• Сценарии выполняются в порядке их определения при срабатывании соответствующего события.
• Массив сценариев, связанных с одним событием, может содержать как обратные вызовы PHP, так и команды, исполняемые из командной строки.
• Классы PHP, содержащие определённые обратные вызовы, должны быть загружаемы через механизм автозагрузки Composer.
• Обратные вызовы могут загружать классы только из определений psr-0, psr-4 и classmap. Если определённый обратный вызов полагается на функции, определённые вне класса, то сам обратный вызов отвечает за загрузку файла, содержащего эти функции.

Пример определения сценария:

{
    "scripts": {
        "post-update-cmd": "MyVendor\\MyClass::postUpdate",
        "post-package-install": [
            "MyVendor\\MyClass::postPackageInstall"
        ],
        "post-install-cmd": [
            "MyVendor\\MyClass::warmCache",
            "phpunit -c app/"
        ],
        "post-autoload-dump": [
            "MyVendor\\MyClass::postAutoloadDump"
        ],
        "post-create-project-cmd": [
            "php -r \"copy('config/local-example.php', 'config/local.php');\""
        ]
    }
}

Используя предыдущий пример определения, вот класс MyVendor\MyClass, который может использоваться для выполнения обратных вызовов PHP:

<?php

namespace MyVendor;

use Composer\Script\Event;
use Composer\Installer\PackageEvent;

class MyClass
{
    public static function postUpdate(Event $event)
    {
        $composer = $event->getComposer();
        // do stuff
    }

    public static function postAutoloadDump(Event $event)
    {
        $vendorDir = $event->getComposer()->getConfig()->get('vendor-dir');
        require $vendorDir . '/autoload.php';

        some_function_from_an_autoloaded_file();
    }

    public static function postPackageInstall(PackageEvent $event)
    {
        $installedPackage = $event->getOperation()->getPackage();
        // do stuff
    }

    public static function warmCache(Event $event)
    {
        // make cache toasty
    }
}

Примечание: Во время выполнения Composer install или update команды в среде будет добавлен переменная COMPOSER_DEV_MODE. Если команда была запущена с флагом --no-dev, эта переменная будет установлена в 0, в противном случае — в 1. Переменная также доступна во время выполнения dump-autoload, и она будет установлена так же, как и последняя install или update.

Классы событий

При срабатывании события ваш обратный вызов PHP получает в качестве первого аргумента объект Composer\EventDispatcher\Event. Этот объект имеет метод getName(), который позволяет получить имя события.

В зависимости от типов сценариев, вы получите различные подклассы событий, содержащие различные геттеры с соответствующими данными и связанными объектами:

• Базовый класс: Composer\EventDispatcher\Event
• События команд: Composer\Script\Event
• События установщика: Composer\Installer\InstallerEvent
• События пакета: Composer\Installer\PackageEvent
• События плагина:
  • init: Composer\EventDispatcher\Event
  • command: Composer\Plugin\CommandEvent
  • pre-file-download: Composer\Plugin\PreFileDownloadEvent
  • post-file-download: Composer\Plugin\PostFileDownloadEvent

Запуск сценариев вручную

Если вы хотите запустить сценарии для события вручную, синтаксис следующий:

php composer.phar run-script [--dev] [--no-dev] script

Например composer run-script post-install-cmd запустит все сценарии post-install-cmd и плагины, которые были определены.

Вы также можете передать дополнительные аргументы обработчику сценария, добавив -- за которым следуют аргументы обработчика. Например, composer run-script post-install-cmd -- --check передаст--check обработчику сценария. Эти аргументы получают как аргументы командной строки обработчиками командной строки, и могут быть получены как массив с помощью $event->getArguments() обработчиками PHP.

Создание пользовательских команд

Если вы добавляете пользовательские сценарии, которые не соответствуют одному из предопределённых имен событий выше, вы можете запустить их с помощью run-script, или также запустить их как родные команды Composer. Например, обработчик, определённый ниже, может быть запущен выполнением composer test:

{
    "scripts": {
        "test": "phpunit"
    }
}

Аналогично команде run-script вы можете передавать дополнительные аргументы сценариям, например, composer test -- --filter <pattern> передаст --filter <pattern> сценарию phpunit.

Примечание: Перед выполнением сценариев Composer временно добавляет bin-dir в переменную среды PATH, чтобы двоичные файлы зависимостей были непосредственно доступны. В данном примере, независимо от того, находится ли двоичный файл phpunit в vendor/bin/phpunit или bin/phpunit, он будет найден и запущен.

Хотя Composer не предназначен для управления долгоживущими процессами и другими аспектами проектов PHP, иногда бывает удобно отключать тайм-аут процесса для пользовательских команд. Этот тайм-аут по умолчанию равен 300 секундам и может быть переопределён различными способами в зависимости от желаемого эффекта:

• отключить его для всех команд, используя ключ конфигурации process-timeout,
• отключить его для текущих или будущих вызовов composer, используя переменную среды COMPOSER_PROCESS_TIMEOUT,
• для конкретного вызова, используя флаг --timeout команды run-script,
• используя статический помощник для конкретных сценариев.

Чтобы отключить тайм-аут для определённых сценариев с помощью статического помощника непосредственно в composer.json:

{
    "scripts": {
        "test": [
            "Composer\\Config::disableProcessTimeout",
            "phpunit"
        ]
    }
}

Чтобы отключить тайм-аут для каждого сценария в данном проекте, вы можете использовать конфигурацию composer.json:

{
    "config": {
        "process-timeout": 0
    }
}

Также возможно установить глобальную переменную среды, чтобы отключить тайм-аут всех последующих сценариев в текущей среде терминала:

export COMPOSER_PROCESS_TIMEOUT=0

Чтобы отключить тайм-аут для одного вызова сценария, вы должны использовать команду composer run-script и указать параметр --timeout.

php composer.phar run-script --timeout=0 test

Ссылка на сценарии

Для повышения повторного использования сценариев и избежания дублирования, вы можете вызвать сценарий из другого, добавив префикс @ к имени команды:

{
    "scripts": {
        "test": [
            "@clearCache",
            "phpunit"
        ],
        "clearCache": "rm -rf cache/*"
    }
}

Вы также можете обратиться к сценарию и передать ему новые аргументы:

{
    "scripts": {
        "tests": "phpunit",
        "testsVerbose": "@tests -vvv"
    }
}

Вызов команд Composer

Для вызова команд Composer вы можете использовать @composer, который будет автоматически резолвиться к текущему используемому composer.phar:

{
    "scripts": {
        "test": [
            "@composer install",
            "phpunit"
        ]
    }
}

Один из ограничений этого заключается в том, что вы не можете вызвать несколько команд composer подряд, например, @composer install && @composer foo. Вы должны разделить их в JSON-массиве команд.

Выполнение скриптов PHP

Для выполнения скриптов PHP вы можете использовать @php, который будет автоматически резолвиться к текущему используемому процессу PHP:

{
    "scripts": {
        "test": [
            "@php script.php",
            "phpunit"
        ]
    }
}

Одним из ограничений является то, что вы не можете вызвать несколько команд подряд, например, @php install && @php foo. Необходимо разделить их в JSON-массиве команд.

Вы также можете вызвать скрипт оболочки/bash, в котором будет доступен путь к исполняемому файлу PHP в виде PHP_BINARY переменной окружения.

Настройка переменных окружения

Для настройки переменной окружения в кроссплатформенном режиме можно использовать @putenv:

{
    "scripts": {
        "install-phpstan": [
            "@putenv COMPOSER=phpstan-composer.json",
            "composer install --prefer-dist"
        ]
    }
}

Пользовательские описания.

Вы можете задать пользовательские описания скриптов следующим образом в вашем composer.json:

{
    "scripts-descriptions": {
        "test": "Run all tests!"
    }
}

Эти описания используются в командах composer list или composer run -l для описания действий скрипта при его выполнении.

Примечание: Вы можете задавать пользовательские описания только для пользовательских команд.