sfPropelVersionableBehaviorPlugin - 0.2.0

Propel versionable behavior

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source | Show as Markdown

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 :

    
    <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

$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

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
   */

Conditional versioning

You may not want to have a new version of resource created each time it is saved.

Just add a versionConditionMet() method to your stub class. It is called each time object's save(). No version is created if it returns false.

Example :

// lib/model/Article.php
 
  public function versionConditionMet()
  {
    return $this->getTitle() != 'do not version me';
  }
 
 
 
 
[php]
 
  $article = new Article();
  $article->setTitle('New article');
  $article->save(); // article is saved and a new version is created
 
  $article->setTitle('do not version me');
  $article->save(); // article is saved, no new version is created

It is possible to specify a different versionConditionMet() method name by defining it when registring behavior :

sfPropelBehavior::add('Article', array('versionable' => array('columns' => $columns_map, 'conditional' => 'myMethod')));

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
  • ResourceVersion getLastVersion() : Returns resource's last 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.2.0

  • made version number management more reliable
  • new getLastVersion() method
  • implemented conditional versioning
  • updated docs and unit tests accordingly

2007-02-17 | 0.1.0

Initial public release.