2012-02-29 14:57:16 +00:00
|
|
|
<!--
|
|
|
|
tagline: Script are callbacks that are called before/after installing packages
|
|
|
|
-->
|
2012-08-29 20:30:47 +00:00
|
|
|
|
2012-02-05 15:27:55 +00:00
|
|
|
# Scripts
|
|
|
|
|
|
|
|
## What is a script?
|
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
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
|
2013-12-18 21:59:10 +00:00
|
|
|
the Composer execution process.
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
**NOTE: Only scripts defined in the root package's `composer.json` are
|
|
|
|
executed. If a dependency of the root package specifies its own scripts,
|
|
|
|
Composer does not execute those additional scripts.**
|
2012-02-05 15:27:55 +00:00
|
|
|
|
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
## Event names
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
Composer fires the following named events during its execution process:
|
|
|
|
|
2012-10-21 19:05:32 +00:00
|
|
|
- **pre-install-cmd**: occurs before the `install` command is executed.
|
2012-10-01 02:53:26 +00:00
|
|
|
- **post-install-cmd**: occurs after the `install` command is executed.
|
|
|
|
- **pre-update-cmd**: occurs before the `update` command is executed.
|
|
|
|
- **post-update-cmd**: occurs after the `update` command is executed.
|
2013-08-01 06:44:07 +00:00
|
|
|
- **pre-status-cmd**: occurs before the `status` command is executed.
|
|
|
|
- **post-status-cmd**: occurs after the `status` command is executed.
|
2012-02-05 15:27:55 +00:00
|
|
|
- **pre-package-install**: occurs before a package is installed.
|
|
|
|
- **post-package-install**: occurs after a package is installed.
|
|
|
|
- **pre-package-update**: occurs before a package is updated.
|
|
|
|
- **post-package-update**: occurs after a package is updated.
|
|
|
|
- **pre-package-uninstall**: occurs before a package has been uninstalled.
|
|
|
|
- **post-package-uninstall**: occurs after a package has been uninstalled.
|
2013-05-06 14:37:21 +00:00
|
|
|
- **pre-autoload-dump**: occurs before the autoloader is dumped, either
|
|
|
|
during `install`/`update`, or via the `dump-autoload` command.
|
2013-02-22 17:44:50 +00:00
|
|
|
- **post-autoload-dump**: occurs after the autoloader is dumped, either
|
|
|
|
during `install`/`update`, or via the `dump-autoload` command.
|
2013-05-31 09:39:14 +00:00
|
|
|
- **post-root-package-install**: occurs after the root package has been
|
|
|
|
installed, during the `create-project` command.
|
|
|
|
- **post-create-project-cmd**: occurs after the `create-project` command is
|
|
|
|
executed.
|
2014-01-28 00:45:20 +00:00
|
|
|
- **pre-archive-cmd**: occurs before the `archive` command is executed.
|
|
|
|
- **post-archive-cmd**: occurs after the `archive` command is executed.
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2013-10-12 13:32:57 +00:00
|
|
|
**NOTE: Composer makes no assumptions about the state of your dependencies
|
|
|
|
prior to `install` or `update`. Therefore, you should not specify scripts that
|
|
|
|
require Composer-managed dependencies in the `pre-update-cmd` or
|
|
|
|
`pre-install-cmd` event hooks. If you need to execute scripts prior to
|
|
|
|
`install` or `update` please make sure they are self-contained within your
|
|
|
|
root package.**
|
2013-10-12 03:58:43 +00:00
|
|
|
|
2012-02-05 15:27:55 +00:00
|
|
|
## Defining scripts
|
|
|
|
|
2012-10-22 18:24:05 +00:00
|
|
|
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 as a string
|
|
|
|
(only for a single script) or an array (for single or multiple scripts.)
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
For any given event:
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
- Scripts execute in the order defined when their corresponding event is fired.
|
|
|
|
- An array of scripts wired to a single event can contain both PHP callbacks
|
|
|
|
and command-line executables commands.
|
|
|
|
- PHP classes containing defined callbacks must be autoloadable via Composer's
|
|
|
|
autoload functionality.
|
2012-02-05 15:27:55 +00:00
|
|
|
|
|
|
|
Script definition example:
|
|
|
|
|
2012-02-29 14:56:53 +00:00
|
|
|
{
|
|
|
|
"scripts": {
|
|
|
|
"post-update-cmd": "MyVendor\\MyClass::postUpdate",
|
2012-03-26 22:59:08 +00:00
|
|
|
"post-package-install": [
|
|
|
|
"MyVendor\\MyClass::postPackageInstall"
|
2013-01-23 17:55:57 +00:00
|
|
|
],
|
2012-10-01 02:53:26 +00:00
|
|
|
"post-install-cmd": [
|
|
|
|
"MyVendor\\MyClass::warmCache",
|
|
|
|
"phpunit -c app/"
|
|
|
|
]
|
2012-02-29 14:56:53 +00:00
|
|
|
}
|
2012-02-05 15:27:55 +00:00
|
|
|
}
|
|
|
|
|
2012-10-01 02:53:26 +00:00
|
|
|
Using the previous definition example, here's the class `MyVendor\MyClass`
|
|
|
|
that might be used to execute the PHP callbacks:
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-02-29 14:56:53 +00:00
|
|
|
<?php
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-02-29 14:56:53 +00:00
|
|
|
namespace MyVendor;
|
2012-02-05 15:27:55 +00:00
|
|
|
|
2012-03-26 22:59:08 +00:00
|
|
|
use Composer\Script\Event;
|
|
|
|
|
2012-02-29 14:56:53 +00:00
|
|
|
class MyClass
|
2012-02-05 15:27:55 +00:00
|
|
|
{
|
2012-03-26 22:59:08 +00:00
|
|
|
public static function postUpdate(Event $event)
|
2012-02-29 14:56:53 +00:00
|
|
|
{
|
2012-03-26 22:59:08 +00:00
|
|
|
$composer = $event->getComposer();
|
2012-02-29 14:56:53 +00:00
|
|
|
// do stuff
|
|
|
|
}
|
|
|
|
|
2012-03-26 22:59:08 +00:00
|
|
|
public static function postPackageInstall(Event $event)
|
2012-02-29 14:56:53 +00:00
|
|
|
{
|
|
|
|
$installedPackage = $event->getOperation()->getPackage();
|
|
|
|
// do stuff
|
|
|
|
}
|
2012-10-01 02:53:26 +00:00
|
|
|
|
|
|
|
public static function warmCache(Event $event)
|
|
|
|
{
|
|
|
|
// make cache toasty
|
|
|
|
}
|
2012-02-05 15:27:55 +00:00
|
|
|
}
|
2012-10-01 02:53:26 +00:00
|
|
|
|
|
|
|
When an event is fired, Composer's internal event handler receives a
|
|
|
|
`Composer\Script\Event` object, which is passed as the first argument to your
|
|
|
|
PHP callback. This `Event` object has getters for other contextual objects:
|
|
|
|
|
|
|
|
- `getComposer()`: returns the current instance of `Composer\Composer`
|
|
|
|
- `getName()`: returns the name of the event being fired as a string
|
|
|
|
- `getIO()`: returns the current input/output stream which implements
|
|
|
|
`Composer\IO\IOInterface` for writing to the console
|
2013-12-18 21:58:20 +00:00
|
|
|
|
|
|
|
## Running scripts manually
|
|
|
|
|
|
|
|
If you would like to run the scripts for an event manually, the syntax is:
|
|
|
|
|
|
|
|
$ composer run-script [--dev] [--no-dev] script
|
|
|
|
|
|
|
|
For example `composer run-script post-install-cmd` will run any **post-install-cmd** scripts that have been defined.
|