|
|
sfPropelEventsPlugin - 0.4.0Adds symfony 1.1 events to your Propel objects. |
|
Add a number of symfony 1.1 events to your Propel objects (compatible with both symfony 1.0 and 1.1).
Download the plugin over the symfony PEAR channel:
$ ./symfony plugin-install sfPropelEventsPlugin
Update the following two directive in your project's propel.ini file:
propel.builder.peer.class = plugins.sfPropelEventsPlugin.lib.builder.SfPropelEventsPeerBuilder
propel.builder.object.class = plugins.sfPropelEventsPlugin.lib.builder.SfPropelEventsObjectBuilder
Also in propel.ini, make sure the addBehaviors directive is switched on:
propel.builder.addBehaviors = true
Now rebuild your model classes:
$ ./symfony propel-build-model
Once propel.ini is updated and the model rebuilt, the following events will have been added to your OM classes:
BaseXXX.pre_deleteBaseXXX.post_deleteBaseXXX.pre_saveBaseXXX.post_saveBaseXXX.method_not_foundBaseXXX.set_fkBaseXXX.get_fkBaseXXX.init_fk_collBaseXXX.add_fkBaseXXX.count_fksBaseXXX.get_fksBaseXXX.get_fks_joinAll of these events can be utilized in Propel behaviors. For the purpose of this documentation let's assume you're creating a new symfony plugin. With the addition of Propel events, you can now register your behavior logic in three ways:
sfPropelBehavior::registerHooks()sfPropelBehavior::registerMethods()sfPropelEventsBehavior::registerListeners()Use of the third method would look something like this, in your plugin's config.php file:
<?php sfPropelEventsBehavior::registerListeners('my_behavior', array( 'method_not_found' => array( array('myBehavior', 'listenForMethodNotFound'), ), 'pre_save' => array( array('myBehavior', 'listenForPreSave'), ), ));
If you want to modify a protected member of a Propel object, you can do this by calling the modifyObject() method on the event object (a method of sfPropelEvent).
<?php class myBehavior { static public function listenForMethodNotFound(sfPropelEvent $event) { switch ($event['method']) { // ->setProtectedVar(string $varName, mixed $value) case 'setProtectedVar': $event->modifyObject($event[$event['arguments'][1]('arguments'][0],)); return true; } } }
A user of your plugin can now add this behavior to a model class. This works slightly different in symfony 1.0 and symfony 1.1.
Adding the behavior to schema.yml will also activate these event listeners. In other words, users don't need to do anything special to install your plugin if they're using symfony 1.1.
classes:
Item:
columns:
id: ~
# more columns...
behaviors:
my_behavior:
param1: foobar
In symfony 1.0, users will need to call sfPropelEventsBehavior::add() in place of sfPropelBehavior::add(). For example:
<?php class Item extends BaseItem { } sfPropelEventsBehavior::add('Item', array( 'my_behavior' => array('param1' => 'foobar'), ));
Note: This plugin has not been tested alongside sfPropelAlternativeSchemaPlugin in symfony 1.0.
If your plugin depends on Propel events, include the following code in config/config.php:
<?php if (!class_exists('sfPropelEvent')) { throw new sfException('sfFoobarPlugin requires that sfPropelEventsPlugin be installed.'); }
Kris Wallsmith
arguments event parameter->doSave() logic to address Propel cascading save bugsfPropelEventsToolkit fetches the dispatchermethod_not_found eventsfPropelEvent objects, which can carry modifications to protected BaseXXX membersInitial release
*----
Each event will include a set of parameters specific to that event. Also, each event object will elicit different reactions from the object once it returns, depending on the return value set by your listener.
pre_deleteThis notifyUntil event includes the following parameters:
argumentsmodified_columnsIf your listener sets a return value for the event that evaluates as true, the standard Propel delete routine will not run.
<?php function listen_for_pre_delete(sfEvent $event) { // this will prevent Propel from deleting the object from the database $event->setReturnValue(true); return true; }
post_deleteThis notify event includes the following parameters:
argumentsmodified_columnspre_saveThis notifyUntil event includes the following parameters:
argumentsmodified_columnsIf your listener gives the event an integer return value, the standard Propel save routing will not run.
<?php function listen_for_pre_save(sfEvent $event) { // this will prevent Propel from saving the object to the database $event->setReturnValue(0); return true; }
post_saveThis notify event includes the following parameters:
argumentswas_new whether the object was new before being savedaffected_rowsmodified_columns those columns marked as modifed before the object was savedmethod_not_foundThis notifyUntil event includes the following parameters:
methodargumentsfk_objectscollectionslast_criteriamodified_columns
[php]
function listen_for_method_not_found(sfEvent $event) { $parameters = $event->getParameters(); switch ($parameters['method']) { case 'getModifiedColumns': $event->setReturnValue($parameters['modified_columns']); return true; } }
set_fkThis notifyUntil event includes the following parameters:
methodargumentscolumnrelated_classin_objectin_object_varmodified_columnsIf your listener gives the event a return value of null or an instance of the related_class, the return value will be stored to the object.
<?php function listen_for_set_fk(sfEvent $event) { // this prevents any object from being place in this FK $event->setReturnValue(null); return true; }
get_fkThis notifyUntil event includes the following parameters:
methodargumentscolumnrelated_classin_object The instance of related_class or null currently stored in the objectin_object_varmodified_columnsIf your listener gives the event a return value of null or an instance of the related_class, the event's return value will be returned to the calling script.
<?php function listen_for_get_fk(sfEvent $event) { $parameters = $event->getParameters(); $class = $parameters['related_class']; $event->setReturnValue(new $class); return true; }
init_fk_collThis notifyUntil event includes the following parameters:
methodargumentsrelated_classin_object The current value of the internal FK collectionin_object_varlast_criteria The last Criteria used to query this FKmodified_columnsIf your listener gives the event an array return value, the object's internal collection will be initalized with that value.
add_fkThis notifyUntil event includes the following parameters:
methodargumentsrelated_classadded_valuein_object The internal FK collectionin_object_varlast_criteria The last Criteria used to query this FKmodified_columnsIf your listener sets a return value for the event that evaluates as true, the standard Propel add routine will not run.
count_fksThis notifyUntil event includes the following parameters:
methodargumentsrelated_classin_object The internal FK collectionin_object_varlast_criteria The last Criteria used to query this FKmodified_columnsIf your listener sets an integer return value for the event, this value will be returned to the calling script instead of Propel querying the database.
get_fksThis notifyUntil event includes the following parameters:
methodargumentsrelated_classin_object The internal FK collectionin_object_varlast_criteria The last Criteria used to query this FKmodified_columnsIf your listener sets an array return value for the event, this value will be returned to the calling script in place of Propel's default behavior.
get_fks_joinThis notifyUntil event includes the following parameters:
methodargumentsmiddle_classrelated_classin_objectin_object_varlast_criteriamodified_columnsIf your listener sets an array return value for the event, this value will be returned to the calling script in place of Propel's default behavior.
