refactored the event dispatcher guide

Author: fabpot

cookbook/event_dispatcher/class_extension.rst

@@ -0,0 +1,64 @@
+.. index::
+ single: Event Dispatcher
+
+How to extend a Class without using Inheritance
+===============================================
+
+To allow multiple classes to add methods to another one, you can define the
+magic ``__call()`` method in the class you want to be extended like this::
+
+ class Foo
+ {
+ // ...
+
+ public function __call($method, $arguments)
+ {
+ // create an event named 'foo.method_is_not_found'
+ // and pass the method name and the arguments passed to this method
+ $event = new Event($this, 'foo.method_is_not_found', array('method' => $method, 'arguments' => $arguments));
+
+ // calls all listeners until one is able to implement the $method
+ $this->dispatcher->notifyUntil($event);
+
+ // no listener was able to process the event? The method does not exist
+ if (!$event->isProcessed()) {
+ throw new \Exception(sprintf('Call to undefined method %s::%s.', get_class($this), $method));
+ }
+
+ // return the listener returned value
+ return $event->getReturnValue();
+ }
+ }
+
+Then, create a class that will host the listener::
+
+ class Bar
+ {
+ public function addBarMethodToFoo(Event $event)
+ {
+ // we only want to respond to the calls to the 'bar' method
+ if ('bar' != $event->get('method']) {
+ // allow another listener to take care of this unknown method
+ return false;
+ }
+
+ // the subject object (the foo instance)
+ $foo = $event->getSubject();
+
+ // the bar method arguments
+ $arguments = $event->get('parameters');
+
+ // do something
+ // ...
+
+ // set the return value
+ $event->setReturnValue($someValue);
+
+ // tell the world that you have processed the event
+ return true;
+ }
+ }
+
+Eventually, add the new ``bar`` method to the ``Foo`` class::
+
+ $dispatcher->connect('foo.method_is_not_found', array($bar, 'addBarMethodToFoo'));

cookbook/event_dispatcher/method_behavior.rst

@@ -0,0 +1,68 @@
+.. index::
+ single: Event Dispatcher
+
+How to customize a Method Behavior without using Inheritance
+============================================================
+
+Doing something before or after a Method Call
+---------------------------------------------
+
+If you want to do something just before, or just after a method is called, you
+can notify respectively an event at the beginning or at the end of the
+method::
+
+ class Foo
+ {
+ // ...
+
+ public function send($foo, $bar)
+ {
+ // do something before the method
+ $event = new Event($this, 'foo.do_before_send', array('foo' => $foo, 'bar' => $bar));
+ $this->dispatcher->notify($event);
+
+ // the real method implementation is here
+ // $ret = ...;
+
+ // do something after the method
+ $event = new Event($this, 'foo.do_after_send', array('ret' => $ret));
+ $this->dispatcher->notify($event);
+
+ return $ret;
+ }
+ }
+
+Modifying Method Arguments
+--------------------------
+
+If you want to allow third party classes to modify arguments passed to a method
+just before that method is executed, add a ``filter`` event at the beginning of
+the method::
+
+ class Foo
+ {
+ // ...
+
+ public function render($template, $arguments = array())
+ {
+ // filter the arguments
+ $event = new Event($this, 'foo.filter_arguments');
+ $this->dispatcher->filter($event, $arguments);
+
+ // get the filtered arguments
+ $arguments = $event->getReturnValue();
+ // the method starts here
+ }
+ }
+
+And here is a filter example::
+
+ class Bar
+ {
+ public function filterFooArguments(Event $event, $arguments)
+ {
+ $arguments['processed'] = true;
+
+ return $arguments;
+ }
+ }

cookbook/index.rst

@@ -14,6 +14,8 @@ Dive into Symfony2 cookbook:
  testing/http_authorization
  testing/insulating_clients
  testing/profiling
+ event_dispatcher/class_extension
+ event_dispatcher/method_behavior
  profiler/data_collector
  symfony1
 

cookbook/map.rst.inc

@@ -6,5 +6,7 @@
 * :doc:`/cookbook/testing/http_authorization`
 * :doc:`/cookbook/testing/insulating_clients`
 * :doc:`/cookbook/testing/profiling`
+* :doc:`/cookbook/event_dispatcher/class_extension`
+* :doc:`/cookbook/event_dispatcher/method_behavior`
 * :doc:`/cookbook/profiler/data_collector`
 * :doc:`/cookbook/symfony1`

guides/event/index.rst

@@ -14,7 +14,6 @@ Dive into Symfony2 with the topical guides:
  security/index
  cache/index
  translation
- event/index
  bundles/index
  dependency_injection/index
  internals/index