# 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](http://propel.phpdb.org/trac/wiki/Users/Documentation/1.2/Schema#columnelement) when using `schema.xml`.

## Discussion

Please post to [this forum thread](http://www.symfony-project.com/forum/index.php/m/35522/) 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'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]
    <?php
    
    // lib/model/Post.php
    class Post extends BasePost
    {
    }
    
    $hasOneKeys  = array('author'   => array('foreign_model' => PostPeer::AUTHOR_TYPE,
                                             'foreign_id'    => PostPeer::AUTHOR_ID));
    $hasManyKeys = array('tags'     => array('foreign_model' => TagPeer::SUBJECT_TYPE,
                                             'foreign_id'    => TagPeer::SUBJECT_ID),
                         'comments' => array('foreign_model' => CommentPeer::SUBJECT_TYPE,
                                             'foreign_id'    => 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[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([$con](Connection))`
  * `setAuthor(mixed $foreignObject[Connection $con](,))`
  * `clearAuthor([$con](Connection))`

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

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

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