Update and refine Scripts docs with CLI-based commands

doc/articles/scripts.md

@@ -6,19 +6,24 @@
 
 ## What is a script?
 
-A script is a callback (defined as a static method) that will be called
+A script, in Composer's terms, can either be a PHP callback (defined as a
-when the event it listens on is triggered.
+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.
 
-**Scripts are only executed on the root package, not on the dependencies
+**NOTE: Only scripts defined in the root package's `composer.json` are
-that are installed.**
+executed. If a dependency of the root package specifies its own scripts,
+Composer does not execute those additional scripts.**
 
 
-## Event types
+## Event names
 
-- **pre-install-cmd**: occurs before the install command is executed.
+Composer fires the following named events during its execution process:
-- **post-install-cmd**: occurs after the install command is executed.
+
-- **pre-update-cmd**: occurs before the update command is executed.
+- **pre-install-cmd*: occurs before the `install` command is executed.
-- **post-update-cmd**: occurs after the update command is executed.
+- **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.
 - **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.
@@ -29,12 +34,18 @@ that are installed.**
 
 ## Defining scripts
 
-Scripts are defined by adding the `scripts` key to a project's `composer.json`.
+The root JSON object in `composer.json` should have a member 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.)
 
-They are specified as an array of classes and static method names.
+For any given event:
 
-The classes used as scripts must be autoloadable via Composer's autoload
+- Scripts execute in the order defined when their corresponding event is fired.
-functionality.
+- 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.
 
 Script definition example:
 
@@ -44,14 +55,15 @@ Script definition example:
             "post-package-install": [
                 "MyVendor\\MyClass::postPackageInstall"
             ]
+            "post-install-cmd": [
+                "MyVendor\\MyClass::warmCache",
+                "phpunit -c app/"
+            ]
         }
     }
 
-The event handler receives a `Composer\Script\Event` object as an argument,
+Using the previous definition example, here's the class `MyVendor\MyClass`
-which gives you access to the `Composer\Composer` instance through the
+that might be used to execute the PHP callbacks:
-`getComposer` method.
-
-Using the previous example, here's an event listener example :
 
     <?php
 
@@ -72,4 +84,18 @@ Using the previous example, here's an event listener example :
             $installedPackage = $event->getOperation()->getPackage();
             // do stuff
         }
+
+        public static function warmCache(Event $event)
+        {
+            // make cache toasty
+        }
     }
+
+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