= sfPropelVersionableBehaviorPlugin plugin =

[[PageOutline]]

The `sfPropelVersionableBehaviorPlugin` is a symfony plugin that provides versioning capabilities to any Propel object.

== Features ==

 * Fully unit tested
 * Revert objects to previous versions easily

== Installation ==

  * Install the plugin
  
    {{{
      symfony plugin-install http://plugins.symfony-project.com/sfPropelVersionableBehaviorPlugin
    }}}

  * Enable Propel behavior support in `propel.ini`:

    {{{
      propel.builder.AddBehaviors = true
    }}}
  
  * Add necessary fields to your model :
  
  {{{
    <!-- schema.xml -->
    <column name="uuid" type="CHAR" size="36" required="true" />
    <column name="version" type="INTEGER" size="11" required="true" />
  }}}

  * Add foreign key between resource and version history. Edit plugin's schema.xml and enter valid values for `foreignTable` and `foreign` attributes
  
  {{{
    <foreign-key foreignTable="Article" name="has_versions" onDelete="cascade">
      <reference local="resource_uuid" foreign="uuid"/>
    </foreign-key>
  }}}

  * Rebuild your database and model (the plugin uses to tables to store object version history)
  
  {{{
    symfony propel-build-all
  }}}
  
  * Enable the behavior for one of your Propel model:

    {{{
      // lib/model/Article.php
      class Article
      {
      }

      $columns_map = array('uuid'     => ArticlePeer::UUID
                           'version'  => ArticlePeer::VERSION);
 
      sfPropelBehavior::add('Article', array('versionable' => array('columns' => $columns_map)));
    }}}

   Column map values signification : 
     * uuid : Model column holding resource's universally unique identifier (behavior takes care of generating these)
     * version : Model column holding resource's current version number

== Usage ==

=== Reverting to a previous version ===

{{{
#!php

  $article = new Article();
  $article->setTitle('First version of article');
  $article->save(); // $article->getVersion() == 1

  $article->setTitle('Second version of article');
  $article->save(); //$article->getVersion() == 2
  
  $article->toVersion(1); // $article->getTitle() == 'First version of article'
  $article->save(); // $article->getVersion() == 3

}}}

=== Retrieving a resource version history ===

{{{
#!php

  foreach ($article->getAllVersions() as $version)
  {
     $history_article = $version->getResourceInstance();
     echo sprintf("Version %d title : %s\n", 
                  $history_article->getVersion(), 
                  $history_article->getTitle());
  }

  /* 
   * Outputs :
   *
   * Version 1 title : First version of article
   * Version 2 title : Second version of article
   * Version 3 title : First version of article
   */

}}}

== Public API ==

Enabling the behaviors adds / modifies the following method to the Propel objects :

 * `void save()` : Adds a new version to resource's version history
 * `void delete()` : Deletes resource's version history
 * `void toVersion(integer $version_number)` : Populates resource properties with values from the requested version
 * `array getAllVersions()`  : Returns each resource version in an array
 
!ResourceVersion class API :

 * `BaseObject getResourceInstance()` : returns resource instance populated with attributes from the version

== Changelog ==

=== 2007-02-17 | 0.1.0 ===

Initial public release.