What is a script?#A script, in Composer's terms, can either be a PHP callback (defined as a static method) or any command-line executable command. Scripts are useful for executing a package's custom code or package-specific commands during the Composer execution process. Show
Event names#Composer fires the following named events during its execution process: Command Events#
Installer Events#
Package Events#
Plugin Events#
Defining scripts#The root JSON object in composer.json should have a property called "scripts", which contains pairs of named events and each event's corresponding scripts. An event's scripts can be defined as either a string (only for a single script) or an array (for single or multiple scripts.) For any given event:
Script definition example: Using the previous definition example, here's the class MyVendor\MyClass that might be used to execute the PHP callbacks: <?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 } }Note: During a Composer install or update command run, a variable named COMPOSER_DEV_MODE will be added to the environment. If the command was run with the --no-dev flag, this variable will be set to 0, otherwise it will be set to 1. The variable is also available while dump-autoload runs, and it will be set to the same as the last install or update was run in. Event classes#When an event is fired, your PHP callback receives as first argument a Composer\EventDispatcher\Event object. This object has a getName() method that lets you retrieve the event name. Depending on the script types you will get various event subclasses containing various getters with relevant data and associated objects:
Running scripts manually#If you would like to run the scripts for an event manually, the syntax is: php composer.phar run-script [--dev] [--no-dev] scriptFor example composer run-script post-install-cmd will run any post-install-cmd scripts and plugins that have been defined. You can also give additional arguments to the script handler by appending -- followed by the handler arguments. e.g. composer run-script post-install-cmd -- --check will pass--check along to the script handler. Those arguments are received as CLI arg by CLI handlers, and can be retrieved as an array via $event->getArguments() by PHP handlers. Writing custom commands#If you add custom scripts that do not fit one of the predefined event name above, you can either run them with run-script or also run them as native Composer commands. For example the handler defined below is executable by running composer test: { "scripts": { "test": "phpunit" } }Similar to the run-script command you can give additional arguments to scripts, e.g. composer test -- --filter <pattern> will pass --filter <pattern> along to the phpunit script.
Although Composer is not intended to manage long-running processes and other such aspects of PHP projects, it can sometimes be handy to disable the process timeout on custom commands. This timeout defaults to 300 seconds and can be overridden in a variety of ways depending on the desired effect:
To disable the timeout for specific scripts with the static helper directly in composer.json: { "scripts": { "test": [ "Composer\\Config::disableProcessTimeout", "phpunit" ] } }To disable the timeout for every script on a given project, you can use the composer.json configuration: { "config": { "process-timeout": 0 } }It's also possible to set the global environment variable to disable the timeout of all following scripts in the current terminal environment: To disable the timeout of a single script call, you must use the run-script composer command and specify the --timeout parameter: php composer.phar run-script --timeout=0 testReferencing scripts#To enable script re-use and avoid duplicates, you can call a script from another one by prefixing the command name with @: { "scripts": { "test": [ "@clearCache", "phpunit" ], "clearCache": "rm -rf cache/*" } }You can also refer a script and pass it new arguments: { "scripts": { "tests": "phpunit", "testsVerbose": "@tests -vvv" } }Calling Composer commands#To call Composer commands, you can use @composer which will automatically resolve to whatever composer.phar is currently being used: { "scripts": { "test": [ "@composer install", "phpunit" ] } }One limitation of this is that you can not call multiple composer commands in a row like @composer install && @composer foo. You must split them up in a JSON array of commands. Executing PHP scripts#To execute PHP scripts, you can use @php which will automatically resolve to whatever php process is currently being used: { "scripts": { "test": [ "@php script.php", "phpunit" ] } }One limitation of this is that you can not call multiple commands in a row like @php install && @php foo. You must split them up in a JSON array of commands. You can also call a shell/bash script, which will have the path to the PHP executable available in it as a PHP_BINARY env var. Setting environment variables#To set an environment variable in a cross-platform way, you can use @putenv: { "scripts": { "install-phpstan": [ "@putenv COMPOSER=phpstan-composer.json", "composer install --prefer-dist" ] } }Custom descriptions.#You can set custom script descriptions with the following in your composer.json: { "scripts-descriptions": { "test": "Run all tests!" } }The descriptions are used in composer list or composer run -l commands to describe what the scripts do when the command is run.
Found a typo? Something is wrong in this documentation? Fork and edit it! |