sfPropelEventsPlugin - 0.4.0

Adds symfony 1.1 events to your Propel objects.

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

sfPropelEventsPlugin

Add a number of symfony 1.1 events to your Propel objects (compatible with both symfony 1.0 and 1.1).

Installation

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_delete
  • BaseXXX.post_delete
  • BaseXXX.pre_save
  • BaseXXX.post_save
  • BaseXXX.method_not_found
  • BaseXXX.set_fk
  • BaseXXX.get_fk
  • BaseXXX.init_fk_coll
  • BaseXXX.add_fk
  • BaseXXX.count_fks
  • BaseXXX.get_fks
  • BaseXXX.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:

  1. sfPropelBehavior::registerHooks()
  2. sfPropelBehavior::registerMethods()
  3. 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'),
  ),
));

Modifying protected variables

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 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 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.

Testing the dependency

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.');
}

Maintainers

Kris Wallsmith

Roadmap

Changelog

Version 0.4.0-alpha

  • Nested all method arguments in an arguments event parameter
  • Added parameters to FK methods
  • Modified ->doSave() logic to address Propel cascading save bug
  • Addressed bug in how sfPropelEventsToolkit fetches the dispatcher

Version 0.3.0-alpha

  • All internal collections, foreign key objects, and last-used criteria are now exposed to the method_not_found event
  • Propel objects now dispatch sfPropelEvent objects, which can carry modifications to protected BaseXXX members

Version 0.2.0-alpha

  • Added symfony 1.0 support

Version 0.1.0-alpha

  • Initial release

    *----

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:

  • arguments
  • modified_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:

  • arguments
  • modified_columns

pre_save

This notifyUntil event includes the following parameters:

  • arguments
  • modified_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:

  • arguments
  • was_new whether the object was new before being saved
  • affected_rows
  • modified_columns those columns marked as modifed before the object was saved

method_not_found

This notifyUntil event includes the following parameters:

  • method
  • arguments
  • fk_objects
  • collections
  • last_criteria
  • modified_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_fk

This notifyUntil event includes the following parameters:

  • method
  • arguments
  • column
  • related_class
  • in_object
  • in_object_var
  • modified_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:

  • method
  • arguments
  • column
  • related_class
  • in_object The instance of related_class or null currently stored in the object
  • in_object_var
  • modified_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:

  • method
  • arguments
  • related_class
  • in_object The current value of the internal FK collection
  • in_object_var
  • last_criteria The last Criteria used to query this FK
  • modified_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:

  • method
  • arguments
  • related_class
  • added_value
  • in_object The internal FK collection
  • in_object_var
  • last_criteria The last Criteria used to query this FK
  • modified_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:

  • method
  • arguments
  • related_class
  • in_object The internal FK collection
  • in_object_var
  • last_criteria The last Criteria used to query this FK
  • modified_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:

  • method
  • arguments
  • related_class
  • in_object The internal FK collection
  • in_object_var
  • last_criteria The last Criteria used to query this FK
  • modified_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:

  • method
  • arguments
  • middle_class
  • related_class
  • in_object
  • in_object_var
  • last_criteria
  • modified_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.