README

A simple yet powerful Laravel package to track every change in your Eloquent models. This package automatically manages history tables and tracks who made the changes and from which URL.

Features

• Automatic Change Tracking: Log created, updated, and deleted events.
• Dynamic History Tables: Generate and synchronize history tables based on your original models.
• User Auditing: Track which user performed the action (recorded_by).
• Contextual Tracking: Store the URL where the action occurred (recorded_url).
• Automated Metadata: Manage created_by, updated_by, and deleted_by fields automatically.
• Bulk Injection: Commands to inject traits into all your models at once.
• Easy Cleanup: Built-in command to prune old history records.

Requirements

• PHP: ^8.2
• Laravel: ^10.0 or ^11.0

Installation

You can install the package via composer:

composer require lara-pack/model-history

Local Installation (Development)

If you are developing locally and haven't published the package yet, you can add it to your composer.json using a path repository:

"repositories": [
    {
        "type": "path",
        "url": "../path/to/lara-pack-model-history"
    }
],
"require": {
    "lara-pack/model-history": "dev-main"
}

Then run:

composer update

Setup

Commands

The package provides several artisan commands to simplify the setup:

1. Sync History Tables

This command scans your models and generates migrations for your history tables. History tables are prefixed with _history_.

php artisan lara-pack:sync-history

Then run the migration command to apply the changes:

php artisan migrate

Migrations will be created in database/migrations/histories/Y_m_d/ and are automatically loaded by the package.

2. Bulk Inject Traits

Inject the HasHistory or HasCompleteHistory traits into all models within a directory (default: app/Models).

# To track changes (creates _history_ tables data)
php artisan lara-pack:inject-has-history

# To add metadata (created_by, updated_by, deleted_by)
php artisan lara-pack:inject-has-complete-history

Manual Usage

Tracking Changes

Add the HasHistory trait to any model you want to track:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LaraPack\ModelHistory\Traits\HasHistory;

class Post extends Model
{
    use HasHistory;
}

Tracking Metadata (Created By, etc.)

Add the HasCompleteHistory trait to manage auditing fields:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use LaraPack\ModelHistory\Traits\HasCompleteHistory;

class Post extends Model
{
    use HasCompleteHistory;
}

Note: For HasCompleteHistory, your migration should include the necessary columns. You can use the provided Blueprint macro:

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    // ...
    $table->completeHistory(); // Adds timestamps, softDeletes, and audit columns
});

Management

Cleaning History

If your history tables grow too large, you can clean them up by date:

# Clean records older than 2025-01-01
php artisan lara-pack:clean-history 2025-01-01

# Clean a specific table
php artisan lara-pack:clean-history 2025-01-01 --table=posts

# Force deletion without confirmation
php artisan lara-pack:clean-history 2025-01-01 --force

Database Schema

The history tables (_history_tablename) will contain all columns from the original table plus:

• recorded_at: Timestamp of the action.
• recorded_by: ID of the user who performed the action.
• recorded_action: The action performed (created, updated, deleted).
• recorded_url: The URL context of the action.

License

The MIT License (MIT).