2017 © Pedro Peláez
 

library eloquent-versioning

An extension for the Eloquent ORM to support versioning.

image

proai/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  • Saturday, May 26, 2018
  • by markusjwetzel
  • Repository
  • 4 Watchers
  • 40 Stars
  • 1,497 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 12 Forks
  • 7 Open issues
  • 10 Versions
  • 94 % Grown

The README.md

Eloquent Versioning

Latest Stable Version Total Downloads Latest Unstable Version License, (*1)

This is an extension for the Eloquent ORM to support versioning. You can specify attributes as versioned. If an attribute is specified as versioned the value will be saved in a separate version table on each update. It is possible to use timestamps and soft deletes with this feature., (*2)

Installation

Eloquent Versioning is distributed as a composer package. So you first have to add the package to your composer.json file:, (*3)

"proai/eloquent-versioning": "~1.0"

Then you have to run composer update to install the package., (*4)

Example

We assume that we want a simple user model. While the username should be fixed, the email and city should be versionable. Also timestamps and soft deletes should be versioned. The migrations would look like the following:, (*5)

...

Schema::create('users', function(Blueprint $table) {
    $table->increments('id');
    $table->integer('latest_version');
    $table->string('username');
    $table->timestamp('created_at');
});

Schema::create('users_version', function(Blueprint $table) {
    $table->integer('ref_id')->primary();
    $table->integer('version')->primary();
    $table->string('email');
    $table->string('city');
    $table->timestamp('updated_at');
    $table->timestamp('deleted_at');
});

...

The referring Eloquent model should include the code below:, (*6)

<?php

namespace Acme\Models;

use Illuminate\Database\Eloquent\Model;
use ProAI\Versioning\Versionable;
use ProAI\Versioning\SoftDeletes;

class User extends Model
{
    use Versionable, SoftDeletes;

    public $timestamps = true;

    public $versioned = ['email', 'city', 'updated_at', 'deleted_at'];

    ...
}

Usage

Database Tables

You need to add the following columns to your main model table:, (*7)

  • latest_version (integer).

Furthermore you need a version table. The name of the version table is identical with the name of the main model table (e. g. for a model table users the name would be users_version). This table must contain the following columns:, (*8)

  • ref_ followed by the name of the model's primary key (if the primary key is id, the column name will be ref_id)
  • version (integer)

Eloquent Models

You have to define a $versioned array in your model that contains all versioned columns., (*9)

Database Queries

Query the database

By default the query builder will fetch the latest version (e. g. User::find(1); will return the latest version of user #1). If you want a specific version or all versions, you can use the following:, (*10)

  • version(VERSION_NO) returns a specific version
    Example: User::version(2)->find(1) will return version #2 of user #1, (*11)

  • allVersions() returns all versions of the queried items
    Example: User::allVersions()->get() will return all versions of all users, (*12)

  • moment(Carbon) returns a specific version, closest but lower than the input date
    Example: User::moment(Carbon::now()->subWeek()->find(1) will return the version at that point in time., (*13)

Create, update and delete records

All these operations can be performed normally. The package will automatically generate a version 1 on create, the next version on update and will remove all versions on delete., (*14)

Timestamps

You can use timestamps in two ways. For both you have to set $timestamps = true;., (*15)

  • Normal timestamps
    The main table must include a created_at and a updated_at column. The updated_at column will be overriden on every update. So this is the normal use of Eloquent timestamps., (*16)

  • Versioned timestamps
    If you add updated_at to your $versioned array, you need a created_at column in the main table and a updated_at column in the version table (see example). On update the updated_at value of the new version will be set to the current time. The updated_at values of previous versions will not be updated. This way you can track the dates of all updates., (*17)

Soft Deletes

If you use the Versionable trait with soft deletes, you have to use the ProAI\Versioning\SoftDeletes trait from this package instead of the Eloquent soft deletes trait., (*18)

  • Normal soft deletes
    Just use a deleted_at column in the main table. Then on delete or on restore the deleted_at value will be updated., (*19)

  • Versioned soft deletes
    If you create a deleted_at column in the version table and add deleted_at to the $versioned array, then on delete or on restore the deleted_at value of the new version will get updated (see example). The deleted_at values of previous versions will not be updated. This way you can track all soft deletes and restores., (*20)

Custom Query Builder

If you want to use a custom versioning query builder, you will have to build your own versioning trait, but that's pretty easy:, (*21)

<?php

namespace Acme\Versioning;

trait Versionable
{
    use \ProAI\Versioning\BaseVersionable;

    public function newEloquentBuilder($query)
    {
        return new MyVersioningBuilder($query);
    }
}

Obviously you have to replace MyVersioningBuilder by the classname of your custom builder. In addition you have to make sure that your custom builder implements the functionality of the versioning query builder. There are some strategies to do this:, (*22)

  • Extend the versioning query builder ProAI\Versioning\Builder
  • Use the versioning builder trait ProAI\Versioning\BuilderTrait
  • Copy and paste the code from the versioning query builder to your custom builder

Support

Bugs and feature requests are tracked on GitHub., (*23)

License

This package is released under the MIT License., (*24)

The Versions

26/05 2018

dev-development

dev-development http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned audits

24/05 2018

dev-master

9999999-dev http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned audits

24/05 2018

1.0.7

1.0.7.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned audits

23/12 2016

1.0.6

1.0.6.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned

23/12 2016

1.0.5

1.0.5.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned

23/12 2016

1.0.4

1.0.4.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned

09/10 2016

1.0.3

1.0.3.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned

08/10 2016

1.0.2

1.0.2.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned

23/06 2015

1.0.1

1.0.1.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned

21/06 2015

1.0.0

1.0.0.0 http://github.com/ProAI/eloquent-versioning

An extension for the Eloquent ORM to support versioning.

  Sources   Download

MIT

The Requires

 

by Markus J. Wetzel

orm laravel eloquent version revision audit versioning versioned