1. Requirements
2. Usage

EActsAsVersioned provides versioning for ActiveRecord models.

Requirements ¶

This extension requires a column for versioning and one to reference the parent/original record. Each new version is a new record but they all share the same parent_id, which is the primary key value of the initial record. Below is an example table definition:

   $this->createTable('email', array(
            'id'           	=> 'int(11) NOT NULL AUTO_INCREMENT',
            'parent_id'     => 'int(11),
            'version'     	=> 'int(11) DEFAULT 1',
            'title'     	=> 'string NOT NULL',
            'body'	        => 'string NOT NULL',
            'created_time' 	=> 'timestamp DEFAULT \'0000-00-00 00:00:00\'',
        ));

This extension is built/tested with Yii 1.1.6

Usage ¶

To use this extension, just copy this file to your extensions/ directory, add 'import' => 'application.extensions.EActsAsVersioned', [...] to your config/main.php and add this behavior to each model you would like to inherit the new functionalities:

public function behaviors(){
      return array( 'EActsAsVersioned' => array(
            'class' => 'application.extensions.EActsAsVersioned'));
}

If you decide to use different column names you can define them as follows (Note that the values shown here are default!)

public function behaviors(){
      return array( 'EActsAsVersioned' => array(
            'class'              => 'application.extensions.EActsAsVersioned')
            'parentIdColumnName' => 'parent_id' ;
            'versionColumnName'  => 'version' ;

The examples below assume the versioning behavior is added to an Email model

getCurrent($parent_id=null) ¶

Load all current models or just one:

$emails = Email::model()->getCurrent() ;   // all current models
$email  = Email::model()->getCurrent(10) ; // load current model with parent_id = 10

it returns an array of Emails or one Email object

getVersions( $criteria=array(), $params=null ) ; ¶

This method is called on an Email instance and loads all related versions or a subset depending on the $criteria

$versionList = $email->getVersions() ; // returns an array with version numbers
/* output:
     Array
     (
        [0] => 1
        [1] => 2
        [2] => 3
     )
*/
$emails = $email->getVersions(
    array(   // criteria
       'toModels'  => true,
       'condition' =>'created_time >:created'
    ),array( // params
       ':created'=>$someTime
    )
));

With the toModels criteria set to TRUE the returned array contains Email objects instead of version numbers

getVersion($version) ¶

Load a specific version: ~~~ $email = Email::model()->getCurrent(1)->getVersion(8) ; $email = $email->getVersion(21) ; $current = $email->getCurrent() ; // load current version of $email ~~~

reuse() ¶

If you plan to use the same instance multiple times to create different versions, like:

$email->title = 'barfoo' ;
$email->save() ;
$email->title = 'foobar' ;
$email->save(false) ;

without validation, it will not work. To fix this call reuse() before save(), like:

$email->reuse() ;
$email->save(false) ;

Other functionalities ¶

$nextEmail = $someEmail->getNextVersion() ; // returns null if not exist
$prevEmail = $someEmail->getPreviousVersion() ; 
if ( $someEmail->isCurrent() ) { ... }