Download the PHP package paulohps/laravel-timeline without Composer

Laravel Timeline

A causer-agnostic activity timeline for Laravel. It gives you:

• A polymorphic causer instead of a hardcoded user_id, so any model — a User, a Team, an Order — can own a timeline.
• A base TimelineEvent class: your app defines the concrete events (what they're called, how they look, what they link to); the package handles storage, context capture and rendering.
• A Livewire component (<livewire:timeline />) with per-type filter chips, day grouping and pagination.
• Framework-agnostic styling: every element carries a stable lt-* CSS class. Use the shipped stylesheet (all CSS custom properties), override its variables, or style everything from scratch — no Tailwind/Bootstrap required.

Requires PHP 8.3+, Laravel 12+/13+ and Livewire 3.6+/4.

Installation

Publish and run the migration:

This creates the timeline_entries table:

To rename the table, publish the config first and change timeline.table before migrating.

Defining events

The package ships only the abstract base class — your application defines the actual events. Generate one:

This creates app/Timeline/OrderShipped.php and reminds you to register it. The generated stub is minimal because the single required method is label():

Everything else is an optional override:

Registering events

Stored entries hold the event key, so the package needs a key → class map. Register your events in config/timeline.php:

…or at runtime (e.g. in a service provider), with the facade:

Entries whose type is no longer registered don't break the page: they render through a fallback that humanizes the raw key (legacy_thing → "Legacy Thing").

Recording entries

Add the HasTimeline trait to any model that should own a timeline:

Then record from wherever fits your app (listeners, jobs, controllers):

The trait also gives you the relation, newest first:

Because causer is a morph, the same works on any model — $team->recordTimelineEvent(...), $order->recordTimelineEvent(...) — with no schema changes.

Metadata & request context

Every entry stores a metadata JSON column. By default the current request's ip, user_agent and url are captured automatically; anything you pass when recording is merged on top:

Storing a title snapshot keeps entries meaningful even if the subject is later renamed or deleted.

To capture richer context (e.g. parsed browser/OS via a package like matomo/device-detector), replace the resolver:

The default detail() line renders browser · os · ip from whatever of those keys exist, so a resolver that adds browser/os upgrades the display automatically.

Enabling/disabling events

Every event has an on/off switch, read from config on each write — wire it to your own settings UI if you need runtime control:

Disabled events make record() return null instead of an entry. For different logic (per-tenant flags, feature flags), override enabled() on the event class.

Displaying the timeline

Drop the Livewire component anywhere, passing the model whose timeline should show:

Props:

The active filters sync to the URL (?event[]=login), so filtered views are shareable. Invalid keys in the URL are ignored.

Rendering entries yourself

The Livewire component is optional. Each entry renders through its event handler, so you can build your own listing:

Or skip the shipped item view entirely and use the handler's data:

Querying

Visual customization

The markup is intentionally plain HTML with stable, prefixed CSS classes. Three levers, from lightest to heaviest:

1. Use the shipped stylesheet and override variables

Everything funnels through CSS custom properties on .lt-timeline, so most branding is a few variable overrides in your own CSS:

Available variables: --lt-text, --lt-text-muted, --lt-surface, --lt-surface-hover, --lt-line, --lt-accent, --lt-accent-contrast, --lt-marker-{default|primary|success|info|warning|danger}-{bg|fg}, --lt-marker-size, --lt-font-size, --lt-font-size-sm.

2. Style the classes yourself

Skip the stylesheet and target the classes directly (they're part of the package's public API):

Custom color() tokens work the same way: return 'purple' from an event and style .lt-item__marker--purple.

3. Publish the views

For structural changes (different markup, Tailwind classes, your design system's components):

• resources/views/vendor/timeline/livewire/timeline.blade.php — the component: chips, day groups, pagination.
• resources/views/vendor/timeline/item.blade.php — a single row; receives $entry, $icon, $color, $title, $detail, $time, $navigation.

A single event can also bypass the shared item view by overriding render():

Translations & formats

Ships en and pt_BR strings ("Today", "No activity yet", …). Date/time display comes from config:

Artisan commands

make:timeline-event

To change the generated code, publish the stub — a stubs/timeline-event.stub in your app root takes precedence:

timeline:prune

Timelines grow forever by default. Prune old entries ad hoc or on a schedule:

Without --days, the cutoff comes from config('timeline.prune_days'); if both are missing the command fails instead of guessing.

Configuration reference

Extending the entry model

The trait relation, the recorder and the Livewire component all resolve the model from config.

Testing your integration

A model factory ships with the package:

Package development

License

MIT.