Revisionable

https://github.com/venturecraft/revisionable
Admin
Revisionable is a Laravel package that automatically tracks and displays a revision history for your...
Tokens:2,764
Snippets:33
Trust Score:6.2
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### String Field Formatting Example

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Example format string for displaying a field as bold text, using `%s` as a placeholder for the actual value.

```text
string:<strong>%s</strong>
```

--------------------------------

### DateTime Field Formatting Example

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Example format string for displaying datetime values in a custom `m/d/Y g:i A` format.

```text
datetime:m/d/Y g:i A
```

--------------------------------

### Options Field Formatting Example

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Example format string for mapping specific text or numeric values to custom output strings, similar to an associative array, where keys are separated from values by a dot and elements by a vertical line.

```text
options:search.On the search|network.In networks
```

--------------------------------

### Is Empty Field Formatting Examples

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Examples of format strings for displaying a custom message if a field is null or empty, or the actual value if something exists. The first option is for empty, the second for non-empty.

```text
isEmpty:No|Yes
```

```text
isEmpty:Nothing|%s
```

--------------------------------

### Run Composer Update

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This command executes Composer to download and update the Revisionable package and its dependencies. It ensures that all required packages are installed or updated according to your `composer.json` file.

```bash
php composer.phar update
```

--------------------------------

### Boolean Field Formatting Example

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Example format string for displaying boolean values as 'No' or 'Yes' instead of '0' or '1'.

```text
boolean:No|Yes
```

--------------------------------

### Display Revision History with Creation Event Handling

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Iterate through a model's revision history, specifically handling the 'created_at' field to display a creation event message, otherwise showing standard field changes. This example uses Blade syntax for Laravel views.

```php
@foreach($resource->revisionHistory as $history)
  @if($history->key == 'created_at' && !$history->old_value)
    <li>{{ $history->userResponsible()->first_name }} created this resource at {{ $history->newValue() }}</li>
  @else
    <li>{{ $history->userResponsible()->first_name }} changed {{ $history->fieldName() }} from {{ $history->oldValue() }} to {{ $history->newValue() }}</li>
  @endif
@endforeach
```

--------------------------------

### Display Basic Revision History

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Iterate through a model's revision history to display changes, including the user responsible, field name, old value, and new value. This example uses Blade syntax for Laravel views.

```php
@foreach($account->revisionHistory as $history )
    <li>{{ $history->userResponsible()->first_name }} changed {{ $history->fieldName() }} from {{ $history->oldValue() }} to {{ $history->newValue() }}</li>
@endforeach
```

--------------------------------

### Customize Strings for Null or Unknown Foreign Keys

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Configure these protected properties in your model to control the string output when a foreign key value is null or refers to a non-existent record in revision logs. For example, 'nothing' for null values and 'unknown' for invalid foreign keys.

```php
protected $revisionNullString = 'nothing';
protected $revisionUnknownString = 'unknown';
```

--------------------------------

### Run Database Migrations for Revisionable in Laravel 5.x

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This Artisan command executes all pending database migrations, including those provided by the Revisionable package. It creates the necessary `revisions` table in your database to store revision history.

```bash
php artisan migrate
```

--------------------------------

### Publish Revisionable Assets in Laravel 5.x

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This Artisan command publishes the configuration file and migration files for the Revisionable package to your Laravel application. This allows you to customize the package's settings and run its database migrations.

```bash
php artisan vendor:publish --provider="Venturecraft\Revisionable\RevisionableServiceProvider"
```

--------------------------------

### Run Database Migrations for Revisionable in Laravel 4.x

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

For Laravel 4.x applications, this Artisan command specifically runs the migrations for the Revisionable package. It ensures the `revisions` table is created in your database for revision tracking.

```bash
php artisan migrate --package=venturecraft/revisionable
```

--------------------------------

### Copy Revisionable Migration File Manually

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This command manually copies the Revisionable package's migration file to your application's `database/migrations` directory. This is an alternative to `vendor:publish` for scenarios like frequent `migrate:refresh` operations, allowing you to modify the migration filename to avoid class name conflicts.

```bash
cp vendor/venturecraft/revisionable/src/migrations/2013_04_09_062329_create_revisions_table.php database/migrations/
```

--------------------------------

### Implement Revisionable with Legacy Class Extension

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This PHP snippet shows the older, class-based approach to using Revisionable, where your model extends the `Revisionable` class. While still functional and backwards compatible, the trait-based approach is now recommended for better flexibility and compatibility with other Eloquent extensions.

```php
use Venturecraft\Revisionable\Revisionable;

namespace App;

class Article extends Revisionable { }
```

--------------------------------

### Register Revisionable Service Provider in Laravel 5.x

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This PHP snippet demonstrates how to register the `RevisionableServiceProvider` in your Laravel 5.x `config/app.php` file. Registering the service provider is crucial for Laravel to load the package's services and functionalities.

```php
'providers' => [
	Venturecraft\Revisionable\RevisionableServiceProvider::class,
]
```

--------------------------------

### Implement Revisionable with Trait (Recommended)

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This PHP snippet demonstrates the recommended way to integrate Revisionable into an Eloquent model using the `RevisionableTrait`. By including the trait, your model automatically gains revision tracking capabilities without needing to extend a specific base class, allowing compatibility with other Eloquent extensions like Ardent.

```php
namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    use RevisionableTrait;
}
```

--------------------------------

### Listen for Revisionable Events

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

The Revisionable library fires events (`revisionable.created`, `revisionable.saved`, `revisionable.deleted`) whenever a model revision is created. You can listen to these events in your `EventServiceProvider.php` to perform custom actions, such as logging or notifications.

```php
// app/Providers/EventServiceProvider.php

public function boot()
{
    parent::boot();

    $events->listen('revisionable.*', function($model, $revisions) {
        // Do something with the revisions or the changed model. 
        dd($model, $revisions);
    });
}
```

--------------------------------

### Add Revisionable to Composer Dependencies

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This snippet shows the entry required in your `composer.json` file's `require` section to include the Revisionable package. This specifies the package name and its version constraint, allowing Composer to manage the dependency.

```json
"venturecraft/revisionable": "1.*"
```

--------------------------------

### Load Model Revision History

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Retrieve the revision history for a specific Eloquent model instance by calling the `revisionHistory` method.

```php
$article = Article::find($id);
$history = $article->revisionHistory;
```

--------------------------------

### Clean Up Old Revisions with History Limit

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

To maintain a fixed number of revisions by removing older entries, set `$revisionCleanup` to `true` in conjunction with `$historyLimit`. This ensures that only the most recent revisions up to the specified limit are kept.

```php
namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    protected $revisionEnabled = true;
    protected $revisionCleanup = true; //Remove old revisions (works only when used with $historyLimit)
    protected $historyLimit = 500; //Maintain a maximum of 500 changes at any point of time, while cleaning up old revisions.
}
```

--------------------------------

### Define Custom Field Output Formats

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Configure how specific fields in a revision history are displayed by setting the `$revisionFormattedFields` array in your Eloquent model. This allows for custom formatting of strings, booleans, datetimes, and handling of empty values.

```php
protected $revisionFormattedFields = [
    'title'      => 'string:<strong>%s</strong>',
    'public'     => 'boolean:No|Yes',
    'modified'   => 'datetime:m/d/Y g:i A',
    'deleted_at' => 'isEmpty:Active|Deleted'
];
```

--------------------------------

### Configure Additional Fields for Revision Metadata

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

To store additional metadata from your models in each revision, add the desired column names to the `additional_fields` array in your `config/revisionable.php` file. These fields will be included in the revision if they exist in the model.

```php
'additional_fields' => ['account_id', 'permissions_id', 'other_id'],
```

--------------------------------

### userResponsible() Method Reference

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Returns the User model responsible for a revision. Returns `false` if no user was recorded. The specific user model loaded depends on the `config/auth.php` settings.

```APIDOC
userResponsible(): User|false
```

--------------------------------

### Enable Storing Model Creations as Revisions

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

The initial creation of a new model is not stored as a revision by default. To include model creations in the revision history, set the `revisionCreationsEnabled` property to `true` in your model.

```php
protected $revisionCreationsEnabled = true;
```

--------------------------------

### Track Specific Fields for Revisioning

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

To track revisions only for a specific set of fields and ignore all others, define an array of field names in the `$keepRevisionOf` property within your model. This setting takes precedence over `$dontKeepRevisionOf`.

```php
protected $keepRevisionOf = ['title'];
```

--------------------------------

### Limit Revision History to a Specific Count

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Control the maximum number of revisions stored for a model by setting the `$historyLimit` property to an integer value. Once this limit is reached, no further revisions will be tracked for the model.

```php
namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    protected $revisionEnabled = true;
    protected $historyLimit = 500; //Stop tracking revisions after 500 changes have been made.
}
```

--------------------------------

### fieldName() Method Reference

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Returns the name of the updated field. For foreign keys (fields ending with `_id`), it returns the part before `_id`. The output can be overridden by the `$revisionFormattedFieldNames` array in the model.

```APIDOC
fieldName(): string
```

--------------------------------

### Enable Storing Force Deletes as Revisions

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

By default, force deletes are not stored as revisions. To track force delete operations, set the `revisionForceDeleteEnabled` property to `true` in your model. This will record the `created_at` field with a `null` new value upon force deletion.

```php
protected $revisionForceDeleteEnabled = true;
```

--------------------------------

### Ignore Specific Fields from Revision Tracking

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

To exclude certain fields from revision tracking while tracking all others, define an array of field names in the `$dontKeepRevisionOf` property within your model. This is useful for fields that change frequently but don't require historical tracking.

```php
protected $dontKeepRevisionOf = ['category_id'];
```

--------------------------------

### Override identifiableName() for Foreign Key Display

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

This method is used when a value (old or new) is the ID of a foreign key relationship. By default, it simply returns the ID. Override this method in your models to return a more meaningful name, such as a title, for better readability in revision logs.

```php
use Venturecraft\Revisionable\Revisionable;

class Article extends Revisionable
{
    public function identifiableName()
    {
        return $this->title;
    }
}
```

--------------------------------

### Override Field Name Display

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Customize the display name of fields in the revision history output by defining the `$revisionFormattedFieldNames` array in your Eloquent model. This is used when calling `$revision->fieldName()`.

```php
protected $revisionFormattedFieldNames = [
    'title'      => 'Title',
    'small_name' => 'Nickname',
    'deleted_at' => 'Deleted At'
];
```

--------------------------------

### Disable Revisioning for a Model

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

To temporarily or permanently disable revision tracking for a specific model, set the `$revisionEnabled` property to `false` within your model class. This is useful for models where revision history is not required.

```php
namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

class Article extends \Illuminate\Database\Eloquent\Model {
    protected $revisionEnabled = false;
}
```

--------------------------------

### Temporarily Disable Revision Tracking for Specific Fields

Source: https://github.com/venturecraft/revisionable/blob/master/readme.md

Use `disableRevisionField()` to temporarily prevent revision tracking for one or more fields during an update. This is useful when you need to save changes but don't require a revision record for certain attributes.

```php
$object->disableRevisionField('title'); // Disables title

or:

$object->disableRevisionField(['title', 'content']); // Disables title and content
```
Tokens:
Raw