= 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&#039;s native support for [http://propel.phpdb.org/trac/wiki/Users/Documentation/1.2/Schema#columnelement single table inheritance] when using `schema.xml`.

== Discussion ==

Please post to [http://www.symfony-project.com/forum/index.php/m/35522/ this forum thread] or ping me in the IRC channel (kriswallsmith) if you have any thoughts.

== Installation ==

 * Install the plugin

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

 * If you haven&#039;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
&lt;?php

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

$hasOneKeys  = array(&#039;author&#039;   =&gt; array(&#039;foreign_model&#039; =&gt; PostPeer::AUTHOR_TYPE,
                                         &#039;foreign_id&#039;    =&gt; PostPeer::AUTHOR_ID));
$hasManyKeys = array(&#039;tags&#039;     =&gt; array(&#039;foreign_model&#039; =&gt; TagPeer::SUBJECT_TYPE,
                                         &#039;foreign_id&#039;    =&gt; TagPeer::SUBJECT_ID),
                     &#039;comments&#039; =&gt; array(&#039;foreign_model&#039; =&gt; CommentPeer::SUBJECT_TYPE,
                                         &#039;foreign_id&#039;    =&gt; CommentPeer::SUBJECT_ID));
sfPropelBehavior::add(&#039;Post&#039;, array(&#039;sfPropelActAsPolymorphic&#039; =&gt; array(&#039;has_one&#039;  =&gt; $hasOneKeys,
                                                                        &#039;has_many&#039; =&gt; $hasManyKeys)));
sfPropelActAsPolymorphicBehavior::mixinCustomMethods(&#039;Post&#039;);
  }}}

== Usage ==

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

 * `getPolymorphicHasOneReference(string $keyName[, Connection $con])`
 * `setPolymorphicHasOneReference(string $keyName, mixed $foreignObject[, Connection $con])`
 * `clearPolymorphicHasOneReference(string $keyName[, Connection $con])`
 * `getPolymorphicHasManyReferences(string $keyName[, Criteria $c[, Connection $con]])`
 * `addPolymorphicHasManyReference(string $keyName, BaseObject $foreignObject[, Connection $con])`
 * `clearPolymorphicHasManyReferences(string $keyName[, Criteria $c[, bool $doDelete[, Connection $con]]])`
 * `deletePolymorphicHasManyReferences(string $keyName[, Criteria $c[, Connection $con]])`
 * `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[, Connection $con])`
 * `clearAuthor([Connection $con])`

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

 * `getTags([Criteria $c[, Connection $con]])`
 * `addTags(BaseObject $foreignObject[, Connection $con])` (this could become `addTag()` later ... we&#039;ll see)
 * `clearTags([Criteria $c[, bool $doDelete[, Connection $con]]])`
 * `deleteTags([Criteria $c[, Connection $con]])`
 * `countTags([Criteria $c[, bool $distinct[, Connection $con]]])`

== Limitations ==

 * When adding to a `has_many` key or setting a `has_one` key, the foreign object must already be saved. This should be resolved in the next alpha release.
 * Plugin does not support multicolumn primary keys. If someone wants to tackle this, please be my guest.

== Roadmap ==

 * Delayed inserts
 * Request-scope caching
 * Complete test suite

== Changelog ==

=== 2007-09-25 | 0.0.3-alpha ===

Plugin now supports has_many relationships and mixes 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