[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,29 @@ dispatched. Listeners receive a
         $application = $command->getApplication();
     });
 
+.. versionadded:: 2.6
+    From Symfony 2.6 you can disable commands inside the listeners. The application
+    will the return the code `113` (defined in ``ConsoleCommandEvent::RETURN_CODE_DISABLED``)::
+
+    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 +141,4 @@ Listeners receive a
         // change the exception to another one
         $event->setException(new \LogicException('Caught exception', $exitCode, $event->getException()));
     });
+