Revisionable Laravel Package

Getting Started

Begin by installing the package via Composer (composer require venturecraft/revisionable) and publishing its config/migrations (php artisan vendor:publish --tag=revisionable). Run the migration to create the revisions table. Then, on any Eloquent model you want to track, use the RevisionableTrait and define which attributes to monitor via $revisionable or $dontKeepRevisionOf properties. The first time a tracked field changes, a revision is automatically created—including optional creation logging if keepCreatedRevisions is enabled in config.

Implementation Patterns

• Trait-based adoption: Add RevisionableTrait to models that need auditing (e.g., Post, User). Keep configuration lean: only specify fields in $revisionable unless excluding sensitive ones.
• Event integration: Hook into revisionable.created, revisionable.saved, and revisionable.deleted events to trigger side effects (e.g., notify users or log to external services).
• Displaying history: Use $model->revisionHistory to get a reverse-chronological list of revisions. Combine with custom blade views to render diff tables (new vs old values) or use helpers like Revision::getFieldName() for label sanitization.
• Custom user attribution: Override getSystemUserId() in your model to assign revisions to authenticated users, queue workers, or CLI commands.

Gotchas and Tips

• Sensitive field exposure: By default, all fillable attributes are tracked—explicitly define $revisionable or $dontKeepRevisionOf to avoid logging passwords, tokens, or sensitive JSON columns.
• Null vs missing fields: When a model is created/deleted, revision records store the full attributes at that time. Ensure your created_at/deleted_at columns are properly cast and nullable-aware.
• Soft deletes: Force deletes are tracked (since v1.36), but soft deletes only create revisions if keepDeletedRevisions is enabled in config—configure carefully to avoid performance bloat.
• Casts & non-scalar types: Since v1.36, array/object casts (e.g., json) are handled more reliably, but complex nested structures may still require manual diffing logic in display.
• Extension point: You can customize revision storage by extending Revision model and overriding resolveRevisionableMorph() if custom morphs or extra fields are needed.