DOCSEARCHbyAlgolia
Submit Docs

Revisionable

repository·master·Indexed 25 days ago

https://github.com/venturecraft/revisionable

A Laravel package for maintaining revision history for Eloquent models. It tracks changes to model attributes, including who made the change and when, to provide accountability and audit trails. Features include the RevisionableTrait for easy implementation, configurable history limits, field-level tracking control, and a FieldFormatter for human-readable output of boolean, datetime, and option values.

Tokens
3.1K
Snippets
10
Records
32
Agent score
83%

What's inside venturecraft-revisionable

  4. Implement Revisionable using the recommended Trait

    master

    To enable revision history for a model, use the RevisionableTrait within your model class. This works with standard Eloquent models or any class extending Eloquent.

    namespace App;

use \Venturecraft\Revisionable\RevisionableTrait;

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

  5. Format revision output values

    master

    You can control how field values are formatted in the revision history by defining the $revisionFormattedFields array in your model. This is useful for converting booleans to text, formatting dates, or wrapping strings in HTML.

    Supported formatters:

    • string:<format>: Uses %s as a placeholder for the value (e.g., string:<strong>%s</strong>).
    • boolean:false_value|true_value: Maps 0/1 to custom text (e.g., boolean:No|Yes).
    • options:key.value|key.value: Maps specific values to custom text (e.g., options:search.On|network.In).
    • datetime:format: Uses standard PHP datetime formatting (e.g., datetime:m/d/Y g:i A).
    • isEmpty:empty_value|non_empty_value: Checks if a value is null or an empty string. Supports %s for the non-empty value (e.g., isEmpty:Nothing|%s).
    protected $revisionFormattedFields = [
    'title'      => 'string:<strong>%s</strong>',
    'public'     => 'boolean:No|Yes',
    'modified'   => 'datetime:m/d/Y g:i A',
    'deleted_at' => 'isEmpty:Active|Deleted'
];

  6. Store additional metadata in revisions

    master
    To include extra model fields (like account_id) in your revisions, first add the columns to your revision table via a custom migration. Then, register the field names in config/revisionable.php under the additional_fields key. Ensure these columns are nullable() in your migrations if they aren't present in every model.

  7. Configure strings for null or unknown foreign keys

    master

    If a revision contains a foreign key that no longer exists or was previously null, you can customize the text displayed in the history by setting these properties in your model:

    • $revisionNullString: String used when the value was null.
    • $revisionUnknownString: String used when the foreign key is no longer found in the database.
    protected $revisionNullString = 'nothing';
protected $revisionUnknownString = 'unknown';

  8. Override revision field names

    master

    To change the display name of a field when calling $revision->fieldName(), use the $revisionFormattedFieldNames array in your model. This is particularly useful for making database column names (like small_name) more human-readable (like Nickname).

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

  9. Implement identifiableName() for foreign keys

    master

    By default, oldValue() and newValue() return the ID when dealing with foreign keys. To display a meaningful name (like a title or name) instead of an ID in your revision history, override the identifiableName() method in your model.

    use Venturecraft\
Revisionable\nRevisionable;

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

  11. Display revision history details

    master

    When iterating through $model->revisionHistory, use the following methods to build human-readable change logs:

    • $history->userResponsible(): Returns the User model responsible for the change, or false if no user is recorded. The user model is determined by your config/auth.php settings.
    • $history->fieldName(): Returns the name of the field updated. For foreign keys (ending in _id), it returns the name without the suffix (e.g., plan_id returns plan).
    • $history->oldValue(): Returns the value before the update. If the value is a foreign key, it uses identifiableName() to return a meaningful string.
    • $history->newValue(): Returns the value after the update. If the value is a foreign key, it uses identifiableName() to return a meaningful string.

  12. Listen to Revisionable events

    master

    Revisionable fires events whenever a revision is created, saved, or deleted. You can listen for these in your EventServiceProvider using the revisionable.* pattern.

    // 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);
    });
}