Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

added documentation for the dispatchable console application #2352

Merged
merged 1 commit into from

5 participants

@fabpot
Owner
Q A
Doc fix? yes
New docs? yes (symfony/symfony#7466)
Applies to master
Fixed tickets n/a
@fabpot fabpot referenced this pull request in symfony/symfony
Merged

Console dispatcher #7466

components/console/events.rst
((11 lines not shown))
+to do the work::
+
+ use Symfony\Component\Console\DispatchableApplication;
+ use Symfony\Component\EventDispatcher\EventDispatcher;
+
+ $application = new DispatchableApplication();
+ $application->setDispatcher($dispatcher);
+ $application->run();
+
+.. note::
+
+ If no event dispatcher is attached to a ``DispatchableApplication``
+ instance, it behaves in the exact same way as a regular ``Application``
+ instance.
+
+The ``console.command`` event
@vicb
vicb added a note

should it be ConsoleEvents::COMMAND rather than the value ? (same goes for the code)

@fabpot Owner
fabpot added a note

fixed in the code

@vicb
vicb added a note

Should it be only in the code ? console.code is an implementation detail that should not be exposed to end user I think.

@fabpot Owner
fabpot added a note

If it were just me, I would remove the constants altogether. I've followed what was done in the docs for HttpKernel.

@vicb
vicb added a note

I think they're nice because:

  • they allow autocompletion,
  • magic values are bad (as seen on several other PRs)

Anyway, the current documentation is a bad compromise. If I were you I would pick one or the other way, not a weird mix.

@vicb
vicb added a note

And of course a typo in a constant name would produce an error while a typo in a magic value would cause a sometime hard to debug issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/console/events.rst
@@ -0,0 +1,121 @@
+.. index::
+ single: Console; Events
+
+Using Events
+============
+
+The Console component comes with a special
+:class:`Symfony\\Component\\Console\\DispatchableApplication` class that
+allows you to hook into the lifecycle of a console application. Instead of
+reinventing the wheel, this class uses the Symfony EventDispatcher component
@WouterJ Collaborator
WouterJ added a note

I like to have some interlinking to the component docs here

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/console/events.rst
@@ -0,0 +1,121 @@
+.. index::
+ single: Console; Events
+
+Using Events
+============
+
@stof
stof added a note

you should add the versionadded directive

@fabpot Owner
fabpot added a note

fixed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/console/events.rst
@@ -0,0 +1,121 @@
+.. index::
+ single: Console; Events
+
+Using Events
+============
+
+The Console component comes with a special
+:class:`Symfony\\Component\\Console\\DispatchableApplication` class that
@stof
stof added a note

it is not a separate class anymore

@fabpot Owner
fabpot added a note

fixed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
components/console/events.rst
((78 lines not shown))
+ $output = $event->getOutput();
+
+ // get the command that has been executed
+ $command = $event->getCommand();
+
+ // display something
+ $output->writeln(sprintf('After running command <info>%s</info>', $command->getName()));
+
+ // change the exit code
+ $event->setExitCode(128);
+ });
+
+.. tip::
+
+ This event is also dispatched when an exception is thrown by the command.
+ If is then dispatched just before the ``console.exception`` event. The
@stof
stof added a note

typo: It

@fabpot Owner
fabpot added a note

fixed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@fabpot fabpot referenced this pull request from a commit in symfony/symfony
@fabpot fabpot merged branch fabpot/console-dispatcher (PR #7466)
This PR was merged into the master branch.

Discussion
----------

Console dispatcher

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #3889, #6124
| License       | MIT
| Doc PR        | symfony/symfony-docs#2352

refs #1884, #1929

This is an alternative implementation for adding events to console applications.

This implementation has the following features:

* Available for anyone using the Console component and it is not tied to
  FrameworkBundle (this is important as one thing we are trying to solve is
  email sending from a command, and frameworks like Silex using the Console
  component needs a solution too);

* Non-intrusive as the current code has not been changed (except for renaming
  an internal variable that was wrongly named -- so that's not strictly needed
  for this PR)

* The new DispatchableApplication class also works without a dispatcher,
  falling back to the regular behavior. That makes easy to create applications
  that can benefit from a dispatcher when available, but can still work
  otherwise.

* Besides the *before* and *after* events, there is also an *exception* event
  that is dispatched whenever an exception is thrown.

* Each event is quite powerful and can manipulate the input, the output, but
  also the command to be executed.

Commits
-------

4f9a55a refactored the implementation of how a console application can handle events
4edf29d added helperSet to console event objects
f224102 Added events for CLI commands
c1bd3b5
@fabpot fabpot referenced this pull request from a commit in symfony/Console
@fabpot fabpot merged branch fabpot/console-dispatcher (PR #7466)
This PR was merged into the master branch.

Discussion
----------

Console dispatcher

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | #3889, #6124
| License       | MIT
| Doc PR        | symfony/symfony-docs#2352

refs #1884, #1929

This is an alternative implementation for adding events to console applications.

This implementation has the following features:

* Available for anyone using the Console component and it is not tied to
  FrameworkBundle (this is important as one thing we are trying to solve is
  email sending from a command, and frameworks like Silex using the Console
  component needs a solution too);

* Non-intrusive as the current code has not been changed (except for renaming
  an internal variable that was wrongly named -- so that's not strictly needed
  for this PR)

* The new DispatchableApplication class also works without a dispatcher,
  falling back to the regular behavior. That makes easy to create applications
  that can benefit from a dispatcher when available, but can still work
  otherwise.

* Besides the *before* and *after* events, there is also an *exception* event
  that is dispatched whenever an exception is thrown.

* Each event is quite powerful and can manipulate the input, the output, but
  also the command to be executed.

Commits
-------

4f9a55a refactored the implementation of how a console application can handle events
4edf29d added helperSet to console event objects
f224102 Added events for CLI commands
adbc260
@WouterJ
Collaborator

@weaverryan this is ready for merging as the code is merged

@fabpot
Owner

I've just changed all event name to use constants. Mergeable now.

@weaverryan weaverryan merged commit c7c215f into symfony:master
@weaverryan
Collaborator

Great new feature and well-explained!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 117 additions and 1 deletion.
  1. +116 −0 components/console/events.rst
  2. +1 −1  components/console/index.rst
View
116 components/console/events.rst
@@ -0,0 +1,116 @@
+.. index::
+ single: Console; Events
+
+.. versionadded:: 2.3
+ The feature described in this chapter was added in 2.3.
+
+Using Events
+============
+
+The Application class of the Console component allows you to optionally hook
+into the lifecycle of a console application via events. Instead of reinventing
+the wheel, it uses the Symfony EventDispatcher component to do the work::
+
+ use Symfony\Component\Console\Application;
+ use Symfony\Component\EventDispatcher\EventDispatcher;
+
+ $application = new Application();
+ $application->setDispatcher($dispatcher);
+ $application->run();
+
+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.
+
+Just before executing any command, the ``ConsoleEvents::COMMAND`` event is
+dispatched. Listeners receive a
+:class:`Symfony\\Component\\Console\\Event\\ConsoleCommandEvent` event::
+
+ use Symfony\Component\Console\Event\ConsoleCommandEvent;
+ use Symfony\Component\Console\ConsoleEvents;
+
+ $dispatcher->addListener(ConsoleEvents::COMMAND, function (ConsoleCommandEvent $event) {
+ // get the input instance
+ $input = $event->getInput();
+
+ // get the output instance
+ $output = $event->getOutput();
+
+ // get the command to be executed
+ $command = $event->getCommand();
+
+ // write something about the command
+ $output->writeln(sprintf('Before running command <info>%s</info>', $command->getName()));
+
+ // get the application
+ $application = $command->getApplication();
+ });
+
+The ``ConsoleEvents::TERMINATE`` event
+--------------------------------------
+
+**Typical Purposes**: To perform some cleanup actions after the command has
+been executed.
+
+After the command has been executed, the ``ConsoleEvents::TERMINATE`` event is
+dispatched. It can be used to do any actions that need to be executed for all
+commands or to cleanup what you initiated in the ``ConsoleEvents::COMMAND``
+command (like sending logs, closing a database connection, sending emails,
+...). A listener might also change the exit code.
+
+Listeners receive a
+:class:`Symfony\\Component\\Console\\Event\\ConsoleTerminateEvent` event::
+
+ use Symfony\Component\Console\Event\ConsoleTerminateEvent;
+ use Symfony\Component\Console\ConsoleEvents;
+
+ $dispatcher->addListener(ConsoleEvents::TERMINATE, function (ConsoleTerminateEvent $event) {
+ // get the output
+ $output = $event->getOutput();
+
+ // get the command that has been executed
+ $command = $event->getCommand();
+
+ // display something
+ $output->writeln(sprintf('After running command <info>%s</info>', $command->getName()));
+
+ // change the exit code
+ $event->setExitCode(128);
+ });
+
+.. tip::
+
+ This event is also dispatched when an exception is thrown by the command.
+ It is then dispatched just before the ``ConsoleEvents::EXCEPTION`` event.
+ The exit code received in this case is the exception code.
+
+The ``ConsoleEvents::EXCEPTION`` event
+--------------------------------------
+
+**Typical Purposes**: Handle exceptions thrown during the execution of a
+command.
+
+Whenever an exception is thrown by a command, the ``ConsoleEvents::EXCEPTION``
+command is dispatched. A listener can wrap or change the exception or do
+anything useful before the exception is thrown by the application.
+
+Listeners receive a
+:class:`Symfony\\Component\\Console\\Event\\ConsoleForExceptionEvent` event::
+
+ use Symfony\Component\Console\Event\ConsoleForExceptionEvent;
+ use Symfony\Component\Console\ConsoleEvents;
+
+ $dispatcher->addListener(ConsoleEvents::EXCEPTION, function (ConsoleForExceptionEvent $event) {
+ $output = $event->getOutput();
+
+ $output->writeln(sprintf('Oops, exception thrown while running command <info>%s</info>', $command->getName()));
+
+ // get the current exit code (the exception code or the exit code set by a ConsoleEvents::TERMINATE event)
+ $exitCode = $event->getExitCode();
+
+ // change the exception to another one
+ $event->setException(new \LogicException('Caught exception', $exitCode, $event->getException()));
+ });
2  components/console/index.rst
@@ -7,5 +7,5 @@ Console
introduction
usage
single_command_tool
-
helpers/index
+ events
Something went wrong with that request. Please try again.