sofa/revisionable

Nice and easy way to handle revisions of your db.

Sunday, March 4, 2018
by jarektkaczyk
Repository
13 Watchers
240 Stars
59,779 Installations

PHP
2 Dependents
0 Suggesters
42 Forks
1 Open issues
46 Versions
8 % Grown

The README.md

Sofa/Revisionable

, _(*1)

Nice and easy way to handle revisions of your db., _(*2)

Handles the revisions in bulk - one entry covers all the created/updated fields, what makes it really easy to eg. compare 2 given versions or get all the data changed during single action.

Requirements

This package requires PHP 5.4+
Currently it works out of the box with Laravel5 + generic Illuminate Guard, tymon/jwt-auth OR cartalyst/sentry 2/sentinel 2

Usage (Laravel5 basic example - see Customization below as well)

1. Download the package or require in your `composer.json`:

composer require sofa/revisionable

2. Add the service provider to your `app/config/app.php`:

    'providers' => array(

        ...

        'Sofa\Revisionable\Laravel\ServiceProvider',
    ),

3. Publish the package config file:

~$ php artisan vendor:publish [--provider="Sofa\Revisionable\Laravel\ServiceProvider"]

this will create config/sofa_revisionable.php file, where you can adjust a few settings:, _(*3)

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | User model (for executor relation on Revision model).
    |--------------------------------------------------------------------------
    |
    | By default App\User.
    */
    'usermodel' => 'App\User',

    /*
    |--------------------------------------------------------------------------
    | User provider (auth) implementation.
    |--------------------------------------------------------------------------
    |
    | By default Laravel generic Illuminate\Auth\Guard.
    |
    | Supported options:
    |  - illuminate
    |  - sentry
    |  - sentinel
    |  - jwt-auth
    |  - session 
    */
    'userprovider' => 'illuminate',


    /*
    |--------------------------------------------------------------------------
    | User field to be saved as the author of tracked action.
    |--------------------------------------------------------------------------
    |
    | By default:
    |
    |  - id for illuminate
    |  - login field (email) for sentry/sentinel
    */
    'userfield' => 'id',


    /*
    |--------------------------------------------------------------------------
    | Table used for the revisions.
    |--------------------------------------------------------------------------
    */
    'table' => 'revisions',


    /*
    |--------------------------------------------------------------------------
    | Database connection used for the revisions.
    |--------------------------------------------------------------------------
    */
    'connection' => null,

];

4. Run the migration in order to create the revisions table:

~$ php artisan revisions:table
~$ php artisan revisions:upgrade-5.3
~$ php artisan migrate [--database=custom_connection]

You can provide additional --database param if you want the migration to be run using non-default db connection., _(*4)

5. Add revisionable trait to the models you wish to keep track of:

<?php namespace App;

use Illuminate\Database\Eloquent\Model;
use Sofa\Revisionable\Laravel\Revisionable; // trait

class User extends Model
{
    use Revisionable;

    /*
     * Set revisionable whitelist - only changes to any
     * of these fields will be tracked during updates.
     */
    protected $revisionable = [
        'email',
        'name',
    ];

And that's all to get your started!, _(*5)

Customization in L5

Default behaviour:, _(*6)

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Sofa\Revisionable\Laravel\Revisionable;

class Ticket extends Model
{
    use Revisionable;
}

$ php artisan tinker

>>> $ticket = App\Models\Ticket::first();
=> <App\Models\Ticket>

>>> $revision->getDiff();
=> [
       "customer_id"    => [
           "old" => "1",
           "new" => "101"
       ],
       "item_id"        => [
           "old" => "2",
           "new" => "1"
       ],
       "responsible_id" => [
           "old" => "8",
           "new" => "2"
       ]
   ]

>>> $revision->old('item_id');
=> "2"

>>> $revision->new('item_id');
=> "1"

>>> $revision->isUpdated('item_id');
=> true

>>> $revision->isUpdated('note');
=> false

>>> $revision->label('item_id');
=> "item_id"

>>> $revision->old;
=> [
       "defect"         => "nie dziala",
       "note"           => "wrocilo na gwarancji",
       "customer_id"    => "1",
       "item_id"        => "2",
       "responsible_id" => "8",
       "status_id"      => "6"
   ]

>>> $revision->action;
=> "updated"

But here's where you can leverage bundled Presenter in order to make useful adjustments:, _(*7)

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Sofa\Revisionable\Laravel\Revisionable;

class Ticket extends Model
{
    use Revisionable;

    protected $revisionPresenter = 'App\Presenters\Revisions\Ticket';
}

namespace App\Presenters\Revisions;

use Sofa\Revisionable\Laravel\Presenter;

class Ticket extends Presenter
{
    protected $labels = [
        'item_id'        => 'Przedmiot',
        'customer_id'    => 'Klient',
        'status_id'      => 'Status',
        'responsible_id' => 'Serwisant',
        'defect'         => 'Usterka',
        'note'           => 'Uwagi',
    ];

    protected $passThrough = [
        'item_id'        => 'item.name',
        'customer_id'    => 'customer.name',
        'responsible_id' => 'serviceman.name',
        'status_id'      => 'status.name',
    ];

    protected $actions = [
        'created'  => 'utworzony',
        'updated'  => 'edytowany',
        'deleted'  => 'usunięty',
        'restored' => 'przywrócony',
    ];

}

then, _(*8)

$ php artisan tinker

>>> $ticket = App\Models\Ticket::first();
=> <App\Models\Ticket>

>>> $revision->old('item_id'); // value fetched from the relationship
=> "komputer pc"

>>> $revision->new('item_id'); // value fetched from the relationship
=> "laptop acer"

>>> $revision->label('item_id'); // custom label defined in the presenter
=> "Przedmiot"

>>> $revision->action; // custom action name defined in the presenter
=> "edytowany"

The Versions

04/03 2018

dev-master

9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=7.0.0
illuminate/database ^5.5

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

04/03 2018

5.6.1

5.6.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=7.0.0
illuminate/database ^5.5

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

02/01 2018

5.5.x-dev

5.5.9999999.9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=7.0

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

02/01 2018

v5.5.1

5.5.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=7.0

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

02/01 2018

v5.5

5.5.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=7.0

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

27/02 2017

5.4.x-dev

5.4.9999999.9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

27/02 2017

v5.4

5.4.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

17/01 2017

5.3.x-dev

5.3.9999999.9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

17/01 2017

v5.3.4

5.3.4.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

23/11 2016

v5.3.3

5.3.3.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

12/11 2016

2.0.x-dev

2.0.9999999.9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

12/11 2016

v2.0.5

2.0.5.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

09/11 2016

v5.3.2

5.3.2.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

05/11 2016

v5.3.1

5.3.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

01/11 2016

v2.1

2.1.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

25/10 2016

5.2.x-dev

5.2.9999999.9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

12/09 2016

v5.3

5.3.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.6.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

29/07 2016

v2.0.4

2.0.4.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

29/07 2016

v2.0.3

2.0.3.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

29/07 2016

v2.0.2

2.0.2.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

29/07 2016

v2.0.1

2.0.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

26/07 2016

v5.2.1

5.2.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

26/07 2016

v2.0

2.0.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4
nesbot/carbon ~1.19

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

14/04 2016

5.2

5.2.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

14/04 2016

1.0.x-dev

1.0.9999999.9999999-dev

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

29/05 2015

v0.2.6

0.2.6.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

29/05 2015

v1.0.8

1.0.8.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

laravel eloquent revision history revisionable

17/05 2015

v1.0.7

1.0.7.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

15/05 2015

v1.0.6

1.0.6.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

14/05 2015

v0.2.5

0.2.5.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

14/05 2015

v1.0.5

1.0.5.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

08/05 2015

v1.0.4

1.0.4.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

08/05 2015

v1.0.3

1.0.3.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

08/05 2015

v0.2.4

0.2.4.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

05/05 2015

v0.2.3

0.2.3.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

05/05 2015

v1.0.2

1.0.2.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

23/03 2015

v1.0.1

1.0.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

09/03 2015

v1.0

1.0.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

04/03 2015

v0.2.2

0.2.2.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

27/02 2015

v0.2.1

0.2.1.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

09/02 2015

v0.2.0

0.2.0.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

09/02 2015

v0.1.7

0.1.7.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

19/12 2014

v0.1.6

0.1.6.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

16/12 2014

v0.1.5

0.1.5.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

15/12 2014

v0.1.4

0.1.4.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

The Development Requires

by Jarek Tkaczyk

11/12 2014

v0.1.3

0.1.3.0

Nice and easy way to handle revisions of your db.

Sources Download

MIT

The Requires

php >=5.4

library revisionable

Nice and easy way to handle revisions of your db.