[WCM] Skip console commands from event listeners

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#9235)
| Applies to    | master
| Fixed tickets | none

Author: Thomas Ploch

components/console/events.rst

@@ -24,8 +24,8 @@ The ``ConsoleEvents::COMMAND`` Event
 ------------------------------------
 
 **Typical Purposes**: Doing something before any command is run (like logging
-which command is going to be executed), or displaying something about the event
-to be executed.
+which command is going to be executed), or displaying something about the event to be
+executed.
 
 Just before executing any command, the ``ConsoleEvents::COMMAND`` event is
 dispatched. Listeners receive a
@@ -51,6 +51,39 @@ dispatched. Listeners receive a
         $application = $command->getApplication();
     });
 
+Disable Commands inside Listeners
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.6
+    Disabling commands inside listeners was introduced in Symfony 2.6.
+
+Using the
+:method:`Symfony\\Component\\Console\\Event\\ConsoleCommandEvent::disableCommand`
+method, you can disable a command inside a listener. The application
+will then not execute the command but return the code `113` (defined in
+``ConsoleCommandEvent::RETURN_CODE_DISABLED``), which is one of the codes reserved
+for the console commands to conform with the C/C++ standard (see
+http://www.tldp.org/LDP/abs/html/exitcodes.html for more information).::
+
+    use Symfony\Component\Console\Event\ConsoleCommandEvent;
+    use Symfony\Component\Console\ConsoleEvents;
+
+    $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) {
+        // get the command to be executed
+        $command = $event->getCommand();
+
+        // ... check if the command can be executed
+
+        // disable the command, this will result in the command being skipped
+        // and code 113 being returned from the Application
+        $event->disableCommand();
+
+        // it is possible to enable the command in a later listener
+        if (!$event->commandShouldRun()) {
+            $event->enableCommand();
+        }
+    });
+
 The ``ConsoleEvents::TERMINATE`` Event
 --------------------------------------
 
@@ -118,3 +151,4 @@ Listeners receive a
         // change the exception to another one
         $event->setException(new \LogicException('Caught exception', $exitCode, $event->getException()));
     });
+