sfPropelActAsPolymorphicBehaviorPlugin plugin

The sfPropelActAsPolymorphicBehaviorPlugin is a symfony plugin that provides support for polymorphic keys in Propel objects.

This plugin can be used to store data that each reference a record from any number of tables. For example, you could create one comments table that uses a polymorphic key to reference both the table and the primary key of the foreign record. The example below demonstrates this.

Features

• Easily accesses foreign records based on two-column foreign keys.
• Works alongside Propel's native support for single table inheritance when using schema.xml.

Installation

• Install the plugin

./symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsPolymorphicBehaviorPlugin

• If you haven't already, enable behaviors in propel.ini and rebuild your model.

propel.builder.addBehaviors = true

./symfony propel-build-model

• Activate the behavior for one of your Propel models:

<?php

// lib/model/Post.php
class Post extends BasePost
{
}

$hasOneKeys  = array('author'   => array('foreign_model' => PostPeer::AUTHOR_TYPE,
                                         'foreign_pk'    => PostPeer::AUTHOR_ID));
$hasManyKeys = array('comments' => array('foreign_model' => CommentPeer::SUBJECT_TYPE,
                                         'foreign_pk'    => CommentPeer::SUBJECT_ID));
sfPropelBehavior::add('Post', array('sfPropelActAsPolymorphic' => array('has_one'  => $hasOneKeys,
                                                                        'has_many' => $hasManyKeys)));
sfPropelActAsPolymorphicBehavior::mixinCustomMethods('Post');

Usage

The call to sfPropelBehavior::add() adds the following methods to your class:

• getPolymorphicHasOneReference(string $keyName[, Connection $con])
• setPolymorphicHasOneReference(string $keyName, mixed $foreignObject)
• getPolymorphicHasManyReferences(string $keyName[, Criteria $c[, Connection $con]])
• addPolymorphicHasManyReference(string $keyName, BaseObject $foreignObject)
• countPolymorphicHasManyReferences(string $keyName[, Criteria $c[, bool $distinct[, Connection $con]]])

Furthermore, calling sfPropelActAsPolymorphicBehavior::mixinCustomMethods() adds a number of custom-named methods to your class, based on the names of your polymorphic keys.

For example, the has_one key author, above, would be accessible with the following methods:

• getAuthor([Connection $con])
• setAuthor(mixed $foreignObject)

The has_many key comments, above, would be accessible with the following methods:

• getComments([Criteria $c[, Connection $con]])
• addComments(BaseObject $foreignObject)
  This method functions more like an addComment() method, but the plugin does not remove that last "s" from your key's name.
• countComments([Criteria $c[, bool $distinct[, Connection $con]]])

Loading fixture data

The standard pake task for loading data from YML fixtures, propel-load-data, will not create polymorphic relationships. This plugin includes its own pake task, propel-load-pm-data, which will allow you to create polymorphic relationships from YML fixtures in the following way:

Business:
  kwik:
    name: Kwik E Mart

User:
  joe:
    name: Joe Bob

Post:
  post_by_user:
    title: Hello world
    author: User_joe            # <-- class + underscore + label
  post_by_business:
    title: Hello free market
    author: Business_kwik       # <-- class + underscore + label

Notice the polymorphic reference includes the foreign Propel class name first, then an underscore, then the nickname assigned to the foreign object in your fixture file.

Limitations

• Plugin does not support multicolumn primary keys. If someone wants to tackle this, please be my guest.

Roadmap

• Support for onDelete="cascade" and onDelete="set null"
• Better compatibility with sfPropelAlternativeSchemaPlugin
• Complete test suite

Changelog

2008-02-17 | 0.7.0-beta

• Updated plugin to more strictly follow the behavior of Propel's native support of foreign keys in model classes.
  • Implemented sfParameterHolder to reduce the number of queries to the database per request and support passing new objects to setXXX() and addXXX() methods.
  • Breaks BC: Removed clearXXX() and deleteXXX() methods since they don't exist in Propel's native support of foreign keys. Please use the tagged 0.6.0-alpha version of this plugin if you need these methods.
• Updated propel-load-pm-data task to work if custom methods have not been mixed in.
• Upgraded plugin to beta status.

2008-01-21 | 0.0.6-alpha

Bugfix to internal stack of custom mixed-in methods.

2008-01-16 | 0.0.5-alpha

Minor bugfix to propel-load-pm-data.

2008-01-11 | 0.0.4-alpha

Added pake task, propel-load-pm-data for loading data from fixtures in a way that respects polymorphic keys.

2007-09-25 | 0.0.3-alpha

Plugin now supports has_many relationships and can optionally mix-in custom methods based on the names of your keys.

2007-09-13 | 0.0.1-alpha

Initial public release.

• Unit tests not in place.
• PEAR package not in place.
• Supports only m-to-1 relationships.
• Foreign objects must be saved before being passed to setPolymorphicHasOneReference.

Maintainers

Kris Wallsmith