sfPropelEventsPlugin
Adds a number of symfony 1.1 events to your Propel objects (compatible with both symfony 1.0 and 1.1).
Installation
To 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
Propel events
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_join
Creating event-based Propel behaviors
All 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()sfPropelEvents::registerListeners()
Use of the third method would look something like this, in your plugin's config.php file:
<?php
sfPropelEvents::registerListeners('my_behavior', array(
'method_not_found' => array(
array('myBehavior', 'listenForMethodNotFound'),
),
'pre_save' => array(
array('myBehavior', 'listenForPreSave'),
),
));
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 behaviors in 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
Adding behaviors in symfony 1.0
In symfony 1.0, users will need to call sfPropelEvents::addBehaviors() in place of sfPropelBehavior::add(). For example:
<?php
class Item extends BaseItem
{
}
sfPropelEvents::addBehaviors('Item', array(
'my_behavior' => array('param1' => 'foobar'),
));
Note: This plugin has not been tested alongside sfPropelAlternativeSchemaPlugin in symfony 1.0.
Testing the dependency
If your plugin depends on Propel events, include the following code in config/config.php:
<?php
if (!class_exists('sfPropelEvents'))
{
throw new sfException('sfFoobarPlugin requires that sfPropelEventsPlugin be installed.');
}
Maintainers
Kris Wallsmith
Roadmap
Changelog
Version 0.2.0-alpha
- Added symfony 1.0 support
Version 0.1.0-alpha
Event reference
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_delete
This notifyUntil event includes the following parameters:
connectionmodified_columns
If 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_delete
This notify event includes the following parameters:
connectionmodified_columns
pre_save
This notifyUntil event includes the following parameters:
connectionmodified_columns
If 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_save
This notify event includes the following parameters:
connectionwas_new whether the object was new before being savedaffected_rowsmodified_columns those columns marked as modifed before the object was saved
method_not_found
This notifyUntil event includes the following parameters:
set_fk
This notifyUntil event includes the following parameters:
columnrelated_classold_valuenew_valuemodified_columns
If 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_fk
This notifyUntil event includes the following parameters:
connectioncolumnrelated_classin_object The instance of related_class or null currently stored in the objectmodified_columns
If 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_coll
This notifyUntil event includes the following parameters:
related_classin_object The current value of the internal FK collectionlast_criteria The last Criteria used to query this FKmodified_columns
If your listener gives the event an array return value, the object's internal collection will be initalized with that value.
add_fk
This notifyUntil event includes the following parameters:
related_classadded_valuein_object The internal FK collectionlast_criteria The last Criteria used to query this FKmodified_columns
If your listener sets a return value for the event that evaluates as true, the standard Propel add routine will not run.
count_fks
This notifyUntil event includes the following parameters:
criteriadistinctconnectionrelated_classin_object The internal FK collectionlast_criteria The last Criteria used to query this FKmodified_columns
If 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_fks
This notifyUntil event includes the following parameters:
criteriaconnectionrelated_classin_object The internal FK collectionlast_criteria The last Criteria used to query this FKmodified_columns
If 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_join
This notifyUntil event includes the following parameters:
criteriaconnectionmiddle_classrelated_classin_objectlast_criteriamodified_columns
If 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.
Kris Wallsmith 