Download the PHP package aaronfrancis/eventable without Composer

Eventable

A Laravel package for tracking events on Eloquent models with polymorphic relationships, backed enums, and query helpers for both individual event records and parent models.

Eventable stores both a registered enum alias in type_class and the enum backing value in type. That keeps overlapping enum values safe across multiple event enums and lets you rename enum classes without breaking historical data.

Highlights:

• Works with int-backed and string-backed enums
• Stores array payloads and exact scalar JSON values
• Lets you query models by event history
• Supports pruning by age, count, or both
• Tested in CI on SQLite, MySQL 8, PostgreSQL 17, and PostgreSQL 18

Installation

Publish the config and migration:

Quick Start

1. Add the trait to your models

2. Create a backed enum for your event types

The published migration uses a string column for type, so int-backed and string-backed enums both work out of the box. If you customize the migration to use an integer column, string-backed enums will no longer fit.

3. Register your enum in config/eventable.php

This registration is required. It enables:

• Multiple enums without value collisions, such as UserEvent::Created = 1 and OrderEvent::Created = 1
• Alias-aware queries when you pass a BackedEnum to ofType()
• Refactoring enum class names without breaking stored records

4. Review morph key and morph map setup

The published migration uses morphs('eventable'), so it follows Laravel's default morph key type. If your app uses UUIDs or ULIDs for polymorphic keys, call Schema::morphUsingUuids() or Schema::morphUsingUlids() before running the migration.

Since Eventable uses polymorphic relationships, it is also a good idea to use Laravel's enforced morph map for your own models:

Eventable separately registers its own Event model in Laravel's morph map when eventable.register_morph_map is enabled.

Recording Events

The second argument can be an array or any JSON-serializable scalar value. Exact scalar matching works for values like false, 0, '0', and ''.

Helper Methods

latestEvent() and whereLatestEventIs() use the same definition of "latest": newest created_at, with id as the tie-breaker. Those latest-event queries also resolve through your configured Event model, so custom global scopes stay in effect.

Querying a Model's Events

Raw values only filter the type column. If multiple enums can share the same backing values, pair raw values with ofTypeClass() or use an enum case directly.

Querying Models by Event Criteria

Querying Models by Events

Pruning Old Events

Implement PruneableEvent on your registered enums to configure retention policies:

If you prefer, you can still return new PruneConfig(...) directly.

Run the prune command:

Schedule it in your routes/console.php or kernel:

PruneConfig must define at least one retention rule: before, keep, or both. Prune is a fluent builder for producing that config. When pruning by keep, Eventable keeps the newest rows by created_at desc, id desc. If varyOnData is enabled, rows are partitioned by model and canonicalized JSON payload before the keep limit is applied, so equivalent JSON objects are grouped together across supported drivers.

Custom Event Models

You can extend the default Event model:

Then update the config:

Relationships, direct Event queries, and the prune command all resolve through the configured model class.

Docs

• Introduction
• Installation
• Configuration
• Usage
• Querying Events
• Pruning Events
• API Reference
• Troubleshooting

License

MIT