PHPackages                             egough/holocron - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. egough/holocron

ActiveLibrary[Utility & Helpers](/categories/utility)

egough/holocron
===============

A Laravel package for recording and querying historical events across your application.

v1.0.1(3mo ago)0148↓90.9%[1 issues](https://github.com/realedwardgough/holocron/issues)MITPHPPHP ^8.2CI passing

Since Mar 19Pushed 3mo agoCompare

[ Source](https://github.com/realedwardgough/holocron)[ Packagist](https://packagist.org/packages/egough/holocron)[ Docs](https://github.com/realedwardgough/holocron)[ RSS](/packages/egough-holocron/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (5)Versions (4)Used By (0)

[![Holocron](https://camo.githubusercontent.com/06213bc9560ad36268023ce673e6023c667263bbcb4a20d95ebd333544864a0e/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f486f6c6f63726f6e2e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d65676f756768253246686f6c6f63726f6e267061747465726e3d617263686974656374267374796c653d7374796c655f32266465736372697074696f6e3d506f6c796d6f72706869632b686973746f72792b2532362b61637469766974792b74696d656c696e652b666f722b4c61726176656c266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)](https://camo.githubusercontent.com/06213bc9560ad36268023ce673e6023c667263bbcb4a20d95ebd333544864a0e/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f486f6c6f63726f6e2e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d65676f756768253246686f6c6f63726f6e267061747465726e3d617263686974656374267374796c653d7374796c655f32266465736372697074696f6e3d506f6c796d6f72706869632b686973746f72792b2532362b61637469766974792b74696d656c696e652b666f722b4c61726176656c266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313030707826696d616765733d68747470732533412532462532466c61726176656c2e636f6d253246696d672532466c6f676f6d61726b2e6d696e2e737667)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9e6f945f77ca680fb0e4cc8afc06c3a46d403244f78489714a13e818463aa1b8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f65676f7567682f686f6c6f63726f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/egough/holocron)[![Total Downloads](https://camo.githubusercontent.com/c9fce14eba1249f8d44c272970f28b715eb10df47d59bd9ececc5486e4841d71/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f65676f7567682f686f6c6f63726f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/egough/holocron)[![License](https://camo.githubusercontent.com/2fa1d222c76cc0d3450973dc5703ada0da156defaa253a9d76c8b2201c0059b3/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f65676f7567682f686f6c6f63726f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/egough/holocron)[![Tests](https://github.com/realedwardgough/holocron/actions/workflows/tests.yml/badge.svg)](https://github.com/realedwardgough/holocron/actions/workflows/tests.yml)

Polymorphic history recording and activity timeline for Laravel.

Combines audit-style field diffing with human-readable event logging — so you can track both low-level attribute changes and meaningful business events in a single, consistent history record.

---

Quick Example
-------------

[](#quick-example)

```
// Record a manual event
Holocron::record('status_changed')
    ->on($order)
    ->by(auth()->user())
    ->message('Order marked as paid')
    ->withMeta(['from' => 'pending', 'to' => 'paid'])
    ->save();

// Automatic tracking via model trait
class Order extends Model
{
    use HasHistory;

    protected array $holocronTrack = ['status', 'total'];
}

// Query the timeline
$order->history()->latest('recorded_at')->get();
$order->holocronTimeline();
```

---

When Should I Use This Package?
-------------------------------

[](#when-should-i-use-this-package)

Use Holocron when your application needs a persistent, queryable record of what happened, who did it, and what changed.

**Typical use cases:**

- Order or payment lifecycle tracking
- Content moderation and editorial history
- Support ticket and case notes
- User account activity logs
- Audit trails for compliance

---

### When Not to Use It

[](#when-not-to-use-it)

Holocron is not a debugging or error-tracking tool. For application exceptions and performance monitoring, consider something like Flare or Sentry.

If you only need simple model diffing without human-readable events, a lightweight audit package may be a better fit. Holocron is designed for applications where both matter.

---

Installation
------------

[](#installation)

```
composer require egough/holocron
```

Publish the config and migrations:

```
php artisan vendor:publish --tag=holocron-config
php artisan vendor:publish --tag=holocron-migrations
php artisan migrate
```

---

Manual Recording
----------------

[](#manual-recording)

Use the `Holocron` facade or helper to record events anywhere in your application.

```
use Egough\Holocron\Facades\Holocron;

Holocron::record('note_added')
    ->on($ticket)
    ->by(auth()->user())
    ->message('Support note added by agent')
    ->category('communication')
    ->save();
```

Record explicit attribute diffs:

```
Holocron::record('updated')
    ->on($post)
    ->by($user)
    ->withChanges([
        'title' => ['old' => 'Old Title', 'new' => 'New Title'],
    ])
    ->message('Post title updated')
    ->save();
```

Attach arbitrary metadata:

```
Holocron::record('invoice_resent')
    ->on($invoice)
    ->by($user)
    ->withMeta(['recipient' => 'billing@example.com'])
    ->save();
```

---

Model Integration
-----------------

[](#model-integration)

Add the `HasHistory` trait to any Eloquent model to enable automatic and on-demand history recording.

```
use Egough\Holocron\Concerns\HasHistory;
use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    use HasHistory;

    protected array $holocronTrack = ['status', 'total'];
}
```

### Automatic Events

[](#automatic-events)

The trait automatically records `created`, `updated`, `deleted`, and `restored` events. For updates, tracked field diffs are stored as:

```
{
  "status": {
    "old": "draft",
    "new": "active"
  }
}
```

Control which events are recorded per model:

```
protected array $holocronEvents = ['created', 'deleted'];
```

### Querying History

[](#querying-history)

```
$order->history;

$order->history()->latest('recorded_at')->get();

$order->latestHistory()->get();

$order->holocronTimeline();
```

### Recording from the Model

[](#recording-from-the-model)

```
$project->recordHistory(
    event: 'archived',
    message: 'Project archived by admin',
    actor: auth()->user(),
);
```

---

Querying
--------

[](#querying)

The `HolocronEntry` model includes helpful query scopes.

```
use Egough\Holocron\Models\HolocronEntry;

// Filter by subject and event type
HolocronEntry::query()
    ->forSubject($order)
    ->event('status_changed')
    ->latest('recorded_at')
    ->get();

// Filter by actor and category
HolocronEntry::query()
    ->causedBy($user)
    ->category('communication')
    ->get();
```

---

Configuration
-------------

[](#configuration)

The published config file gives you control over table naming, automatic event recording, excluded attributes, and actor resolution.

```
return [
    'table_name' => 'holocron_entries',

    'auto_record' => [
        'created'  => true,
        'updated'  => true,
        'deleted'  => true,
        'restored' => true,
    ],

    'exclude' => [
        'created_at',
        'updated_at',
    ],

    'actor_resolver' => static fn () => auth()->user(),
];
```

---

Testing
-------

[](#testing)

Install development dependencies:

```
composer install
```

Run the test suite:

```
composer test
```

Or run PHPUnit directly:

```
vendor/bin/phpunit
```

Tests use an in-memory SQLite setup — no external database required.

---

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11, 12, or 13

---

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance82

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

97d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/489ff16431bccb55fa9e5d7544f0d0d6a3b3fb32d80fb6a75ee1805036b5f589?d=identicon)[egough](/maintainers/egough)

---

Top Contributors

[![realedwardgough](https://avatars.githubusercontent.com/u/5840148?v=4)](https://github.com/realedwardgough "realedwardgough (3 commits)")

---

Tags

laravelactivityAudithistorymodelstimeline

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/egough-holocron/health.svg)

```
[![Health](https://phpackages.com/badges/egough-holocron/health.svg)](https://phpackages.com/packages/egough-holocron)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[wearepixel/laravel-cart

A cart implementation for Laravel

1355.6k](/packages/wearepixel-laravel-cart)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)