konekt/history

Eloquent Model History for Laravel

1.5.0 2024-11-01 10:03 UTC

Requires

• php: ^8.1
• illuminate/database: ^10.10.1|^11.0
• illuminate/support: ^10.10.1|^11.0
• konekt/concord: ^1.13
• konekt/enum: ^3.1|^4.0
• konekt/enum-eloquent: ^1.9
• konekt/laravel-migration-compatibility: ^1.6

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0

MIT

• laravel
• eloquent
• history
• konekt

README

This package provides features to:

1. Log changes, diff and comments to Eloquent models;
2. Track and log the execution history of Laravel background jobs;

Model History

$task = Task::create(['title' => 'Get milk', 'status' => 'todo']);
History::begin($task);

$task->update(['status' => 'done']);
History::logRecentUpdate($task);

Job History

The goal of tracking a job is to be able to show the status and updates of a background job on frontends. It is similar to logging, but is always scoped to a given job execution, and it has a state

class MyJob implements \Konekt\History\Contracts\TrackableJob
{
    use \Konekt\History\Concerns\CanBeTracked;
    
    public function __construct(private array $dataToProcess)
    {        
    }
    
    public function handle()
    {
        $tracker = JobTracker::of($this);
        $tracker->setProgressMax(count($this->dataToProcess));
        $tracker->started();
        try {
            foreach ($this->dataToProcess as $data) {
                do_something_with($data);
                $tracker->advance();
                $tracker->logInfo('An entry was processed');
            }
            $tracker->completed();
        } catch (\Throwable $e) {
            $tracker->failed($e->getMessage());
        }
    }
}

$job = new MyJob();
$job->generateJobTrackingId();

JobTracker::createFor($job);
Bus::dispatch($job);

Features

• Record model creation, update, delete, and retrieval
• Add optional comments to events
• Add comment-only history events
• Automatically record the IP, URL, user agent and user ids when in an HTTP context
• Automatically detect the CLI, the command name when in an artisan command
• Automatically detect the queue and the job when running in a queued job
• Define included/excluded fields on a per-model basis
• Has a diff of the changed fields (old/new values)

Requirements

It requires PHP 8.1+ and Laravel 10 or 11.

It has been tested with:

• PHP 8.1, 8.2, 8.3 & 8.4
• SQLite,
• MySQL 5.7, 8.0, 8.2 & 8.4,
• PostgreSQL 12, 16 & 17.

It is known that this library, Laravel 11.0 and PostgreSQL 11 don't work together, therefore it is recommended to use at least Postgres version 12 or higher in case your DB engine is Postgres.

Documentation

For Installation and usage instruction see the Documentation; https://konekt.dev/history/1.x