manage model revisions with ease
Clone or download
Latest commit 0d28c9e Oct 19, 2018
Permalink
Failed to load latest commit information.
logs v1.6.0 Sep 5, 2018
php-diff styleing Jan 29, 2018
src Oct 19, 2018
.gitignore add gitignore Mar 19, 2018
LICENSE Initial commit Nov 4, 2017
README.md Oct 19, 2018
composer.json v2.0.0 Sep 10, 2018

README.md

Odin
Latest Stable Version Total Downloads

Manage model revisions with ease.

If you are also looking to preview the form data before submitting to the db, you may want to give OverSeer a try.

  • package requires Laravel v5.4+

Installation

  • composer require ctf0/odin

  • (Laravel < 5.5) add the service provider & facade

    'providers' => [
        ctf0\Odin\OdinServiceProvider::class,
    ];
  • publish the package assets with

    php artisan vendor:publish --provider="ctf0\Odin\OdinServiceProvider"

  • after installation, package will auto-add

    • package routes to routes/web.php
    • package assets compiling to webpack.mix.js
  • check http://www.laravel-auditing.com/docs/7.0/general-configuration for configuration

  • install dependencies

    yarn add vue vue-awesome@v2 vue-notif axios keycode
    # or
    npm install vue vue-awesome@v2 vue-notif axios keycode --save
  • add this one liner to your main js file and run npm run watch to compile your js/css files.

    • if you are having issues Check.
    // app.js
    
    window.Vue = require('vue')
    
    require('../vendor/Odin/js/manager')
    
    new Vue({
        el: '#app'
    })

Features

  • support single & nested values.

  • delete & restore revisions.

  • support soft deletes.

  • revision preview.

  • clear audits for permanently deleted models.

    php artisan odin:gc
    • which can be scheduled as well
      $schedule->command('odin:gc')->sundays();
  • shortcuts

    navigation keyboard mouse (click)
    go to next revision right/down * (revision date)
    go to prev revision left/up * (revision date)
    go to first revision home * (revision date)
    go to last revision end * (revision date)
    hide revision window esc * (x)
  • events "JS"

    event-name description
    odin-show when revision is showen
    odin-hide when revision is hidden

Usage

  • run php artisan migrate

  • add Revisions trait & AuditableContract contract to your model

    
    use ctf0\Odin\Traits\Revisions;
    use Illuminate\Database\Eloquent\Model;
    use OwenIt\Auditing\Contracts\Auditable as AuditableContract;
    
    class Post extends Model implements AuditableContract
    {
        use Revisions;
    
        /**
         * resolve model title/name for the revision relation
         * this is needed so we can render
         * the model relation attach/detach changes
         */
        public function getMiscTitleAttribute()
        {
            return $this->name;
        }
    
        // ...
    }
  • you can disable creating ghost audits where both old/new values are empty by using

    • remember that without the parent model audit log we cant show the relation changes
    // app/Providers/EventServiceProvider
    
    use OwenIt\Auditing\Models\Audit;
    
    public function boot()
    {
        parent::boot();
    
        Audit::creating(function (Audit $model) {
            if (empty($model->old_values) && empty($model->new_values)) {
                return false;
            }
        });
    }
  • inside the model view ex.post edit view add

    @if (count($post->revisionsWithRelation))
        @include('Odin::list', ['revisions' => $post->revisionsWithRelation])
    @endif

Notes

  • model user_id & id are excluded from the audit log by default.

  • data:uri

    • if you use data:uri in your revisionable content, change audits_table columns type to either mediumText or longText before migrating to avoid future errors of long data.

    • because data:uri is a render blocking & isn't readable by humans, we truncate it to 75 char max (the smallest stable data:uri is 78 char),
      note that this ONLY effects the displaying of the revision diff, we never touch the data that gets saved to the db.

  • model-relation

    • atm the relation revision is limited, it means we can only show the attach/detach changes but we cant undo/redo any of them through the package it self.
    • also if you use mass update like Model::update() make sure to call $model->touch(); afterwards to make sure an audit is created ex.
      $model = Model::update([...]);
      $model->touch();