# sfPropelVersionableBehaviorPlugin plugin



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.