|
| 1 | +..index:: |
| 2 | + single: Console; Events |
| 3 | + |
| 4 | +..versionadded::2.3 |
| 5 | + The feature described in this chapter was added in 2.3. |
| 6 | + |
| 7 | +Using Events |
| 8 | +============ |
| 9 | + |
| 10 | +The Application class of the Console component allows you to optionally hook |
| 11 | +into the lifecycle of a console application via events. Instead of reinventing |
| 12 | +the wheel, it uses the Symfony EventDispatcher component to do the work:: |
| 13 | + |
| 14 | + use Symfony\Component\Console\Application; |
| 15 | + use Symfony\Component\EventDispatcher\EventDispatcher; |
| 16 | + |
| 17 | + $application = new Application(); |
| 18 | + $application->setDispatcher($dispatcher); |
| 19 | + $application->run(); |
| 20 | + |
| 21 | +The ``ConsoleEvents::COMMAND`` event |
| 22 | +------------------------------------ |
| 23 | + |
| 24 | +**Typical Purposes**: Doing something before any command is run (like logging |
| 25 | +which command is going to be executed), or displaying something about the event |
| 26 | +to be executed. |
| 27 | + |
| 28 | +Just before executing any command, the ``ConsoleEvents::COMMAND`` event is |
| 29 | +dispatched. Listeners receive a |
| 30 | +:class:`Symfony\\Component\\Console\\Event\\ConsoleCommandEvent` event:: |
| 31 | + |
| 32 | + use Symfony\Component\Console\Event\ConsoleCommandEvent; |
| 33 | + use Symfony\Component\Console\ConsoleEvents; |
| 34 | + |
| 35 | + $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) { |
| 36 | + // get the input instance |
| 37 | + $input = $event->getInput(); |
| 38 | + |
| 39 | + // get the output instance |
| 40 | + $output = $event->getOutput(); |
| 41 | + |
| 42 | + // get the command to be executed |
| 43 | + $command = $event->getCommand(); |
| 44 | + |
| 45 | + // write something about the command |
| 46 | + $output->writeln(sprintf('Before running command <info>%s</info>', $command->getName())); |
| 47 | + |
| 48 | + // get the application |
| 49 | + $application = $command->getApplication(); |
| 50 | + }); |
| 51 | + |
| 52 | +The ``ConsoleEvents::TERMINATE`` event |
| 53 | +-------------------------------------- |
| 54 | + |
| 55 | +**Typical Purposes**: To perform some cleanup actions after the command has |
| 56 | +been executed. |
| 57 | + |
| 58 | +After the command has been executed, the ``ConsoleEvents::TERMINATE`` event is |
| 59 | +dispatched. It can be used to do any actions that need to be executed for all |
| 60 | +commands or to cleanup what you initiated in the ``ConsoleEvents::COMMAND`` |
| 61 | +command (like sending logs, closing a database connection, sending emails, |
| 62 | +...). A listener might also change the exit code. |
| 63 | + |
| 64 | +Listeners receive a |
| 65 | +:class:`Symfony\\Component\\Console\\Event\\ConsoleTerminateEvent` event:: |
| 66 | + |
| 67 | + use Symfony\Component\Console\Event\ConsoleTerminateEvent; |
| 68 | + use Symfony\Component\Console\ConsoleEvents; |
| 69 | + |
| 70 | + $dispatcher->addListener(ConsoleEvents::TERMINATE, function (ConsoleTerminateEvent $event) { |
| 71 | + // get the output |
| 72 | + $output = $event->getOutput(); |
| 73 | + |
| 74 | + // get the command that has been executed |
| 75 | + $command = $event->getCommand(); |
| 76 | + |
| 77 | + // display something |
| 78 | + $output->writeln(sprintf('After running command <info>%s</info>', $command->getName())); |
| 79 | + |
| 80 | + // change the exit code |
| 81 | + $event->setExitCode(128); |
| 82 | + }); |
| 83 | + |
| 84 | +..tip:: |
| 85 | + |
| 86 | + This event is also dispatched when an exception is thrown by the command. |
| 87 | + It is then dispatched just before the ``ConsoleEvents::EXCEPTION`` event. |
| 88 | + The exit code received in this case is the exception code. |
| 89 | + |
| 90 | +The ``ConsoleEvents::EXCEPTION`` event |
| 91 | +-------------------------------------- |
| 92 | + |
| 93 | +**Typical Purposes**: Handle exceptions thrown during the execution of a |
| 94 | +command. |
| 95 | + |
| 96 | +Whenever an exception is thrown by a command, the ``ConsoleEvents::EXCEPTION`` |
| 97 | +command is dispatched. A listener can wrap or change the exception or do |
| 98 | +anything useful before the exception is thrown by the application. |
| 99 | + |
| 100 | +Listeners receive a |
| 101 | +:class:`Symfony\\Component\\Console\\Event\\ConsoleForExceptionEvent` event:: |
| 102 | + |
| 103 | + use Symfony\Component\Console\Event\ConsoleForExceptionEvent; |
| 104 | + use Symfony\Component\Console\ConsoleEvents; |
| 105 | + |
| 106 | + $dispatcher->addListener(ConsoleEvents::EXCEPTION, function (ConsoleForExceptionEvent $event) { |
| 107 | + $output = $event->getOutput(); |
| 108 | + |
| 109 | + $output->writeln(sprintf('Oops, exception thrown while running command <info>%s</info>', $command->getName())); |
| 110 | + |
| 111 | + // get the current exit code (the exception code or the exit code set by a ConsoleEvents::TERMINATE event) |
| 112 | + $exitCode = $event->getExitCode(); |
| 113 | + |
| 114 | + // change the exception to another one |
| 115 | + $event->setException(new \LogicException('Caught exception', $exitCode, $event->getException())); |
| 116 | + }); |