EVENTFUL CAKEPHP
==============================
Event System for CakePHP
Installation:
----------------------------------------------------------------------------------------
- Put "events" to APP
- Put "plugins/eventful" to APP.PLUGINS
- Add "Eventful.Event" to AppController::$components <- ControllerEvents, Bootstrap
- Optional: Add "Eventful.Event" to AppModel::$actsAs array <- ModelEvents
- Optional: Copy "/app/events" layout into your plugin to dispatch events to plugins
Current Version:
----------------------------------------------------------------------------------------
- Need to add default triggers for controller (onBeforeFilter, etc.)
How to use:
----------------------------------------------------------------------------------------
Listener classes need to have the same name as the controller file + "_events" at
the end. So if you want to write event handlers for "movies_controller.php" you need
to create a file called "movies_controller_events.php" in the folder /app/events/controllers/.
Same goes for models. The matching "user.php" event class filename is "user_events.php".
Since it all follows the cake conventions event listener classes within plugins need to
prefix the plugin name. If you have a "pizza" plugin the name for a controller event
listener class should be: "pizza_orders_controller_events.php"
Note: Just because you are dispatching events from one controller it is not required
that the listener class file exists.
Withing the listener classes you need to prefix your event handler methods with
the "on" keyword. If you dispatch a event called "userSignUp" like so:
<?php
$this->Event->dispatch('userSignUp')
?>
The method within the class needs to be named "onUserSignUp". More specific:
<?php
// users_controller_events.php
class UsersControllerEvents extends AppControllerEvents {
function onUserSignUp($event) {
// ... do stuff.
}
}
?>
As you can see, we extend the AppControllerEvents class. This class is of same
nature as the app_controller.php. It is the default base class for all events.
We also have AppModelEvents for model events.
You can overwrite the AppControllerEvents class by creating the file
"app_controller_events.php" in the APP folder. Same spot as app_helper.php, etc.
But that's optional... a good place for shared events.
About the "$event" parameter. Passed to all handlers by default. If the event
is a controller event you can access the controller object at $event->Controller.
If the event is a model event you can access the model at $event->Model.
There is also a optional $data parameter in the EventComponent dispatch method.
<?php
$this->Event->dispatch('userSignUp', array('hello' => 'kitty'));
?>
The event handler method can access the value of "hello" at the event object
<?php
class UsersControllerEvents extends AppControllerEvents {
function onUserSignUp($event) {
return $event->hello; //=> kitty
}
}
?>
Trigger all Events
----------------------------------------------------------------------------------------
If you specify the same event listener method in other listener classes the event dispatch
will fire them too.
Fire -> "usersIndex" in any controller
Execs -> *.*ControllerEvents::onUsersIndex()
Be careful about how you name the events.
Check out this output:
Array
(
[MoviesControllerEvents] => I am the MoviesController Event Listener!
[UsersControllerEvents] => I am the UsersController Event Listener!
[PizzaMoviesControllerEvents] => I am the Pizza.MoviesController Event Listener!
)
This array is the default return format from the dispatch method.
That way you can sort the returns from all events as you need them
To get the above in my example application i wrote in my action:
function index() {
$result = $this->Event->dispatch('usersIndex');
pr ($result);
}
Model Events:
--------------------------------------------------------------------------------------
Basicly everything from above applies. Filename for user.php would be user_events.php.
There are default events that are fired from within the behavior.
- onBeforeFind (available infos: 'query')
- onAfterFind (available infos: 'results', 'primary');
- onBeforeValidate (available infos: )
- onBeforeSave (available infos: )
- onAfterSave (available infos: 'created')
- onBeforeDelete (available infos: 'cascade')
- onAfterDelete (available infos: 'created')
- onDatasourceError (available infos: 'error')
The triggering of the default events can be disabled.
var $actsAs = array(
'Eventful.Event' => array(
'triggerDefaults' => false
)
);
Everything else is up to you.
--------------------------------------------------------------------------------------
That should get you started.
More to follow...