Relaticle Activity Log

https://github.com/relaticle/activity-log
Admin
A unified chronological timeline for any Eloquent model that aggregates activity logs, related model...
Tokens:25,822
Snippets:210
Trust Score:6.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install relaticle/activity-log via Composer

Source: https://github.com/relaticle/activity-log/blob/1.x/README.md

Install the package via Composer. Requires PHP 8.4+, Laravel 12, Filament 5, and spatie/laravel-activitylog ^5.

```bash
composer require relaticle/activity-log
```

--------------------------------

### Execute timeline queries

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Examples of retrieving timeline entries using get(), paginate(), or count().

```php
$entries = $record->timeline()->fromActivityLog()->get();

$page = $record->timeline()->fromActivityLog()->paginate(perPage: 25, page: 2);

$total = $record->timeline()->fromActivityLog()->count();
```

--------------------------------

### Example URL with filter query parameters

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/2.filament-ui.md

Shows a URL with the filter query parameters: type, from, and to. This URL is shareable and bookmarkable because state syncs to the URL on every change.

```text
/admin/people/42?type=activity_log&from=2026-01-01&to=2026-04-30
```

--------------------------------

### Registering timeline sources

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/2.concepts/1.how-it-works.md

Examples of registering different types of timeline sources using the TimelineBuilder fluent interface.

```php
$record->timeline()
    ->fromActivityLog()                                    // ActivityLogSource
    ->fromActivityLogOf(['comments'])                      // RelatedActivityLogSource
    ->fromRelation('invoices', fn ($s) => $s->title(...))  // RelatedModelSource
    ->fromCustom(fn ($subject, $window) => yield ...);     // CustomEventSource
```

--------------------------------

### timeline()->get()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Executes the timeline query and returns a collection of TimelineEntry objects, capped at 10000 entries internally.

```APIDOC
## timeline()->get()

### Description
Executes the timeline query and returns a collection of TimelineEntry objects.

### Usage
```php
$entries = $record->timeline()->fromActivityLog()->get();
```

### Returns
- `Collection<int, TimelineEntry>` - The collection of timeline entries.

### Notes
Caps at 10000 entries internally.
```

--------------------------------

### Base Pest test case setup in tests/Pest.php

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Standard Laravel test scaffold using Pest 4 with RefreshDatabase. Place in tests/Pest.php to apply the TestCase and RefreshDatabase traits to all Feature tests.

```php
// tests/Pest.php
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

uses(TestCase::class, RefreshDatabase::class)->in('Feature');
```

--------------------------------

### timeline()->count()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Returns the total count of timeline entries. Note that it runs get() internally, so it does not use a separate COUNT query.

```APIDOC
## timeline()->count()

### Description
Returns the total count of timeline entries.

### Usage
```php
$total = $record->timeline()->fromActivityLog()->count();
```

### Returns
- `int` - The total count of entries.

### Notes
Runs `get()` internally — no separate `COUNT` query. Use sparingly on large datasets.
```

--------------------------------

### fromRelation() - Register related model source with events

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Registers RelatedModelSource for synthetic events from timestamp columns on related rows. The first block is the method signature; the second shows a full configuration example for an invoices relation. Use when you don't log the related model with spatie but still want its lifecycle on the timeline. Note: event(when: ...) filters post-fetch in PHP; use using() for SQL-level filtering.

```php
public function fromRelation(string $relation, Closure $configure, ?int $priority = null): self
```

```php
use Filament\Support\Icons\Heroicon;
use Relaticle\ActivityLog\Timeline\Sources\RelatedModelSource;

$record->timeline()
    ->fromRelation('invoices', function (RelatedModelSource $source): void {
        $source
            ->event('issued_at', 'invoice.issued', icon: Heroicon::DocumentText->value, color: 'info')
            ->event('paid_at', 'invoice.paid', icon: Heroicon::CheckCircle->value, color: 'success')
            ->event('voided_at', 'invoice.voided', color: 'danger', when: fn ($invoice): bool => $invoice->total > 0)
            ->with(['customer'])
            ->using(fn ($query) => $query->where('archived', false))
            ->title(fn ($invoice): string => "Invoice #{$invoice->number}")
            ->description(fn ($invoice): string => "{$invoice->total} {$invoice->currency}")
            ->causer('createdBy');
    });
```

--------------------------------

### Testing the infolist via livewire() with assertSeeHtml

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Mounts the ViewPerson page, updates the record to trigger spatie activity logging, and asserts the rendered output contains the new value. The built-in ActivityLogRenderer emits the diff sentence, so assert against the new value.

```php
use App\Filament\Resources\People\Pages\ViewPerson;

use function Pest\Livewire\livewire;

it('renders an entry on the person view page after an update', function (): void {
    $this->record->update(['name' => 'Updated name']);

    livewire(ViewPerson::class, ['record' => $this->record->getKey()])
        ->assertSeeHtml('Updated name');
});
```

--------------------------------

### Run tests and format code with Composer

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/7.community/1.contributing.md

Use `composer test` to run the test suite and `composer pint` to format the code. These commands are part of the development workflow for the Activity Log project.

```bash
# Run tests
composer test

# Format code
composer pint
```

--------------------------------

### Publish the configuration file

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/1.installation.md

Use this command to publish the package configuration file if you need to override default settings.

```bash
php artisan vendor:publish --tag=activity-log-config
```

--------------------------------

### Using ActivityFactory with for()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Shows how to instantiate the factory and create an Activity for a given subject. Requires wiring the factory into Laravel's resolver via `Factory::guessFactoryNamesUsing()`.

```php
use Database\Factories\Spatie\ActivityFactory;

ActivityFactory::new()->for($this->record)->create();
```

--------------------------------

### Typical beforeEach for timeline UI tests

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Logs in an admin user and creates the record under test. Use this in any test that touches the timeline UI.

```php
use App\Models\Person;
use App\Models\User;

beforeEach(function (): void {
    $this->actingAs(User::factory()->admin()->create());
    $this->record = Person::factory()->create();
});
```

--------------------------------

### Render ActivityLog component in Filament infolist

Source: https://github.com/relaticle/activity-log/blob/1.x/README.md

Render the activity log in a Filament resource infolist by adding the ActivityLog component with a column span of full.

```php
use Filament\Schemas\Schema;
use Relaticle\ActivityLog\Filament\Infolists\Components\ActivityLog;

public static function infolist(Schema $schema): Schema
{
    return $schema->components([
        ActivityLog::make('activity')->columnSpanFull(),
    ]);
}
```

--------------------------------

### Implement and register a reusable TimelineSource with addSource()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Implements the TimelineSource contract to register a reusable custom source. The class yields TimelineEntry objects for each payment, and the second block shows how to attach it to a timeline. Prefer this over fromCustom() when the source is reusable, has constructor dependencies, or needs isolated testing.

```php
namespace App\Timeline\Sources;

use Carbon\CarbonImmutable;
use Illuminate\Database\Eloquent\Model;
use Relaticle\ActivityLog\Contracts\TimelineSource;
use Relaticle\ActivityLog\Timeline\TimelineEntry;
use Relaticle\ActivityLog\Timeline\Window;

final class StripePaymentSource implements TimelineSource
{
    public function __construct(private readonly int $priority = 30) {}

    public function priority(): int
    {
        return $this->priority;
    }

    public function resolve(Model $subject, Window $window): iterable
    {
        $query = $subject->stripePayments()
            ->orderByDesc('created_at')
            ->limit($window->cap);

        if ($window->from instanceof CarbonImmutable) {
            $query->where('created_at', '>=', $window->from);
        }

        foreach ($query->cursor() as $payment) {
            yield new TimelineEntry(
                id: "stripe:payment:{$payment->id}",
                type: 'custom',
                event: "payment.{$payment->status}",
                occurredAt: CarbonImmutable::parse($payment->created_at),
                dedupKey: "stripe:payment:{$payment->id}",
                sourcePriority: $this->priority,
                subject: $subject,
                title: "Payment {$payment->amount_formatted}",
            );
        }
    }
}
```

```php
$record->timeline()
    ->fromActivityLog()
    ->addSource(new StripePaymentSource());
```

--------------------------------

### Make a model timeline-capable with InteractsWithTimeline

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/2.quick-start.md

Make a model timeline-capable by implementing HasTimeline, using InteractsWithTimeline and LogsActivity, and defining getActivitylogOptions and a timeline() method that uses fromActivityLog().

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Relaticle\ActivityLog\Concerns\InteractsWithTimeline;
use Relaticle\ActivityLog\Contracts\HasTimeline;
use Relaticle\ActivityLog\Timeline\TimelineBuilder;
use Spatie\Activitylog\LogOptions;
use Spatie\Activitylog\Traits\LogsActivity;

final class Person extends Model implements HasTimeline
{
    use InteractsWithTimeline;
    use LogsActivity;

    protected $fillable = ['name', 'email'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()->logFillable();
    }

    public function timeline(): TimelineBuilder
    {
        return TimelineBuilder::make($this)->fromActivityLog();
    }
}

```

--------------------------------

### Register custom timeline source with fromCustom

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Registers a custom timeline source via `fromCustom(Closure $resolver, ?int $priority = null)`. The closure receives the subject and the active `Window`; it must respect `cap`, `from`, and `to` to keep memory bounded and honor `->between(...)` filters. Yielding anything other than a `TimelineEntry` instance throws a `TypeError` with the offending type name.

```php
public function fromCustom(Closure $resolver, ?int $priority = null): self
```

```php
use Carbon\CarbonImmutable;
use Relaticle\ActivityLog\Timeline\TimelineEntry;
use Relaticle\ActivityLog\Timeline\Window;

$record->timeline()
    ->fromCustom(function ($subject, Window $window) {
        $query = $subject->stripeCharges()
            ->orderByDesc('created_at')
            ->limit($window->cap);

        if ($window->from instanceof CarbonImmutable) {
            $query->where('created_at', '>=', $window->from);
        }

        if ($window->to instanceof CarbonImmutable) {
            $query->where('created_at', '<=', $window->to);
        }

        foreach ($query->cursor() as $charge) {
            yield new TimelineEntry(
                id: "stripe:charge:{$charge->id}",
                type: 'custom',
                event: 'charge.succeeded',
                occurredAt: CarbonImmutable::parse($charge->created_at),
                dedupKey: "stripe:charge:{$charge->id}",
                sourcePriority: 30,
                subject: $subject,
                title: "Charge {$charge->amount_formatted}",
            );
        }
    });
```

--------------------------------

### Render timeline with ActivityLog infolist component

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/2.quick-start.md

Render the timeline on a Filament resource view page by adding ActivityLog::make('activity')->columnSpanFull() to the infolist. The component must be on a page that renders the model record, such as ViewRecord or EditRecord.

```php
namespace App\Filament\Resources;

use Filament\Schemas\Schema;
use Relaticle\ActivityLog\Filament\Infolists\Components\ActivityLog;

public function infolist(Schema $schema): Schema
{
    return $schema->components([
        // ... your existing entries
        ActivityLog::make('activity')->columnSpanFull(),
    ]);
}

```

--------------------------------

### Add ActivityLog infolist component to Person view page

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/1.crm-person-feed.md

Use the ActivityLog infolist component to display the full activity feed on the Person view page. Configure heading, group by date, set per page, and span full column.

```php
use Relaticle\ActivityLog\Filament\Infolists\Components\ActivityLog;

public function infolist(Schema $schema): Schema
{
    return $schema->components([
        // ... your existing entries
        ActivityLog::make('feed')
            ->heading('Activity')
            ->groupByDate()
            ->perPage(20)
            ->columnSpanFull(),
    ]);
}
```

--------------------------------

### Register renderer with closure

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Registers a renderer using a closure with signature fn (TimelineEntry $entry): View|HtmlString. Best for tiny per-entry markup or quick prototyping.

```php
use Illuminate\Support\HtmlString;
use Relaticle\ActivityLog\Facades\Timeline;
use Relaticle\ActivityLog\Timeline\TimelineEntry;

Timeline::registerRenderer('task_done', fn (TimelineEntry $entry) => new HtmlString(
    "<strong>{$entry->title}</strong> finished",
));
```

--------------------------------

### ActivityFactory class definition

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Defines a factory for Spatie's Activity model with default attributes and a `for()` method to set the subject. Place this in `database/factories/`.

```php
namespace Database\Factories\Spatie;

use Illuminate\Database\Eloquent\Factories\Factory;
use Illuminate\Database\Eloquent\Model;
use Spatie\Activitylog\Models\Activity;

/** @extends Factory<Activity> */
final class ActivityFactory extends Factory
{
    protected $model = Activity::class;

    public function definition(): array
    {
        return [
            'log_name' => 'default',
            'description' => $this->faker->word(),
            'event' => $this->faker->randomElement(['created', 'updated', 'deleted']),
            'subject_type' => null,
            'subject_id' => null,
            'causer_type' => null,
            'causer_id' => null,
            'properties' => [],
        ];
    }

    public function for(Model $subject): static
    {
        return $this->state([
            'subject_type' => $subject->getMorphClass(),
            'subject_id' => $subject->getKey(),
        ]);
    }
}
```

--------------------------------

### Make a model timeline-capable with InteractsWithTimeline

Source: https://github.com/relaticle/activity-log/blob/1.x/README.md

Make an Eloquent model timeline-capable by implementing HasTimeline, using InteractsWithTimeline and LogsActivity, and defining a timeline() method that returns a TimelineBuilder configured with fromActivityLog().

```php
use Relaticle\ActivityLog\Concerns\InteractsWithTimeline;
use Relaticle\ActivityLog\Contracts\HasTimeline;
use Relaticle\ActivityLog\Timeline\TimelineBuilder;
use Spatie\Activitylog\Traits\LogsActivity;

class Person extends Model implements HasTimeline
{
    use InteractsWithTimeline;
    use LogsActivity;

    public function timeline(): TimelineBuilder
    {
        return TimelineBuilder::make($this)->fromActivityLog();
    }
}
```

--------------------------------

### Configure renderers in config file

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Defines static default renderers in the config/activity-log.php file. These are used for defaults that don't depend on runtime state.

```php
// config/activity-log.php
'renderers' => [
    'email_sent' => \App\Timeline\Renderers\EmailSentRenderer::class,
],
```

--------------------------------

### Register and unregister renderer via facade

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Shows how to register and unregister a renderer using the Timeline facade. Useful for global, panel-agnostic overrides or runtime/conditional registration. unregisterRenderer drops a binding, handy in tests or when a feature flag flips off.

```php
use Relaticle\ActivityLog\Facades\Timeline;

Timeline::registerRenderer('email_sent', \App\Timeline\Renderers\EmailSentRenderer::class);

Timeline::unregisterRenderer('email_sent');
```

--------------------------------

### Call paginateTimeline() with named arguments

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Use this method on a model implementing the HasTimeline interface to paginate timeline entries without directly using the builder. It accepts optional perPage and page parameters, defaulting to null and 1 respectively. This is the entry point used internally by the Livewire timeline component.

```php
$page = $opportunity->paginateTimeline(perPage: 20, page: 1);
```

--------------------------------

### Register renderers via plugin

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Registers multiple renderers directly on the ActivityLogPlugin for panel-scoped overrides. Preferred for panel-specific customization.

```php
use Illuminate\Support\HtmlString;
use Relaticle\ActivityLog\Filament\ActivityLogPlugin;

$panel->plugin(
    ActivityLogPlugin::make()->renderers([
        'email_sent' => \App\Timeline\Renderers\EmailSentRenderer::class,
        'note_added' => 'app::timeline.note-added',
        'task_done'  => fn ($entry) => new HtmlString('...'),
    ]),
);
```

--------------------------------

### Livewire #[Url] attributes for filters

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/2.filament-ui.md

Declares three public properties with #[Url] attributes to bind filters to URL query parameters: typeFilter, fromDate, and toDate. The 'as' parameter sets the query parameter names.

```php
#[Url(as: 'type')]  public ?string $typeFilter = null;
#[Url(as: 'from')]  public ?string $fromDate = null;
#[Url(as: 'to')]    public ?string $toDate = null;
```

--------------------------------

### Configure ActivityLogRelationManager Defaults

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/2.filament-ui.md

Override default properties like infinite scroll, grouping, and pagination globally from a service provider's boot method.

```php
use Relaticle\ActivityLog\Filament\RelationManagers\ActivityLogRelationManager;

public function boot(): void
{
    ActivityLogRelationManager::$infiniteScroll = false;
    ActivityLogRelationManager::$groupByDate = false;
    ActivityLogRelationManager::$perPage = 50;
}
```

--------------------------------

### fromActivityLog() method signature

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Signature of the fromActivityLog() method. Registers the subject's own spatie activity log source. $priority overrides the default of 10 (see source_priorities.activity_log).

```php
public function fromActivityLog(?int $priority = null, ?string $mergedRenderer = null): self
```

--------------------------------

### fromActivityLog()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Registers the ActivityLogSource to read the subject's spatie activity log. Optionally accepts a priority and a mergedRenderer string to enable same-save merging.

```APIDOC
## fromActivityLog()

### Description
Registers `Relaticle\ActivityLog\Timeline\Sources\ActivityLogSource` — the subject's own spatie activity log. Reads from the `activity_log` table where `subject_type` and `subject_id` match the subject. Each row becomes a `TimelineEntry` with `type='activity_log'`.

### Method
fromActivityLog

### Signature
```php
public function fromActivityLog(?int $priority = null, ?string $mergedRenderer = null): self
```

### Parameters
- **priority** (?int) - Optional - Overrides the default priority of `10` (see `source_priorities.activity_log`).
- **mergedRenderer** (?string) - Optional - When provided, enables same-save merge: rows sharing a non-empty `batch_uuid` are collapsed into one `TimelineEntry` with the given renderer key.

### Usage Example
```php
$entries = $record->timeline()
    ->fromActivityLog()
    ->get();
```

### Merge Usage Example
```php
$entries = $record->timeline()
    ->fromActivityLog(mergedRenderer: 'merged-activity')
    ->get();
```

### Notes
- **Subject must be persisted.** `ActivityLogSource::resolve()` throws a `DomainException` when `$subject->getKey() === null`. Don't call `timeline()` from a `creating` model event or on a fresh, unsaved instance.
- **Same-save merge is opt-in.** Default `$mergedRenderer = null` keeps the original per-row behaviour.
- **Requires a `batch_uuid` column.** Rows are grouped by spatie's `batch_uuid`. The package only reads this column — the host app owns it.
- **Read-side only.** Merge never changes how activities are written/logged — it only groups on read.

### Merge Behavior
- **One entry per batch.** Rows sharing a `batch_uuid` become a single entry; rows without a `batch_uuid` each stay their own entry.
- **Combined `properties`.** The merged entry's `properties` is the union of every grouped row's data (native `attribute_changes` + custom `properties`), so no payload is lost.
- **Explicit `renderer`.** The merged entry's `renderer` is set to your string. `RendererRegistry` resolves `renderer` *before* event/type, so the merge picks a renderer without overriding any global event renderer.
- **Repeated array-valued keys accumulate** instead of overwriting.
- The rest of the entry comes from a representative `base` row — the first grouped row that carries non-empty `attribute_changes`, else the first row — so `event`, `title`, `occurredAt`, and `causer` reflect that row.

### Migration for batch_uuid
```php
Schema::table('activity_log', function (Blueprint $table): void {
    $table->uuid('batch_uuid')->nullable()->index();
});
```

### Renderer Registration Example
```php
use Relaticle\ActivityLog\Facades\Timeline;

Timeline::registerRenderer('merged-activity', \App\Timeline\Renderers\MergedActivityRenderer::class);
```

### End-to-End Wiring Steps
1. Add the `batch_uuid` column (see migration above).
2. Stamp one `batch_uuid` per save so the rows from a single save share it. This is host-owned — the package only reads the column.
3. Register a renderer for the merge key.
4. Enable the merge on the builder.

### Renderer Input
A merged entry's `properties` is the **union of every grouped row's payload** — native `attribute_changes` (the `attributes` / `old` maps) plus each row's custom `properties`, keyed as each row had them. Write your renderer against `$entry->properties` (mixed native + custom keys); the built-in `ActivityLogSummary` helper still works for the native portion.
```

--------------------------------

### Register the panel plugin

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/1.installation.md

Register the plugin in your Filament panel configuration. This step is optional and only required if you need to register custom renderers.

```php
use Relaticle\ActivityLog\Filament\ActivityLogPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(ActivityLogPlugin::make())
        // ... rest of panel config
    ;
}
```

--------------------------------

### fromActivityLog() with mergedRenderer

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Opt-in same-save merge: pass $mergedRenderer to collapse rows sharing a non-empty batch_uuid into one TimelineEntry. The merged entry's renderer is set to the given string, and properties are the union of all grouped rows' data. Requires a batch_uuid column on the activity_log table.

```php
$entries = $record->timeline()
    ->fromActivityLog(mergedRenderer: 'merged-activity')
    ->get();
```

--------------------------------

### Enable caching with TTL

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/5.caching.md

Wrap a `paginate()` call with `cached(ttlSeconds: 300)` to cache the result for 300 seconds. This is opt-in and disabled by default.

```php
$entries = $record->timeline()->cached(ttlSeconds: 300)->paginate();
```

--------------------------------

### Add compound index to activity_log table

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/1.installation.md

Add this index to the spatie activity_log table to ensure responsive timeline queries and prevent performance issues with large logs.

```php
Schema::table('activity_log', function (Blueprint $table) {
    $table->index(['subject_type', 'subject_id', 'created_at']);
});
```

--------------------------------

### Implement RedactedAuditRenderer

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/2.audit-log-for-admins.md

Create a custom renderer that filters sensitive keys from the properties array before delegating to the original ActivityLogRenderer.

```php
namespace App\Timeline\Renderers;

use Illuminate\Contracts\View\View;
use Illuminate\Support\HtmlString;
use Relaticle\ActivityLog\Contracts\TimelineRenderer;
use Relaticle\ActivityLog\Renderers\ActivityLogRenderer;
use Relaticle\ActivityLog\Timeline\TimelineEntry;

final class RedactedAuditRenderer implements TimelineRenderer
{
    /** @var array<int, string> */
    private const REDACTED_KEYS = ['password', 'remember_token', 'two_factor_secret', 'two_factor_recovery_codes'];

    public function __construct(private readonly ActivityLogRenderer $inner) {}

    public function render(TimelineEntry $entry): View|HtmlString
    {
        $properties = $entry->properties;

        foreach (['attributes', 'old'] as $bucket) {
            if (! isset($properties[$bucket]) || ! is_array($properties[$bucket])) {
                continue;
            }

            foreach (self::REDACTED_KEYS as $key) {
                if (array_key_exists($key, $properties[$bucket])) {
                    $properties[$bucket][$key] = '••••••••';
                }
            }
        }

        $redacted = new TimelineEntry(
            id: $entry->id,
            type: $entry->type,
            event: $entry->event,
            occurredAt: $entry->occurredAt,
            dedupKey: $entry->dedupKey,
            sourcePriority: $entry->sourcePriority,
            subject: $entry->subject,
            causer: $entry->causer,
            relatedModel: $entry->relatedModel,
            title: $entry->title,
            description: $entry->description,
            icon: $entry->icon,
            color: $entry->color,
            renderer: $entry->renderer,
            properties: $properties,
        );

        return $this->inner->render($redacted);
    }
}
```

--------------------------------

### Implement custom TimelineRenderer with ActivityLogSummary

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Minimal custom renderer that implements TimelineRenderer and delegates to ActivityLogSummary, passing the summary to a custom Blade view. The view can access $summary->causerName, $summary->operation, $summary->changedFieldLabels, $summary->summarySentence, $summary->diffRows, and $summary->hasDiff.

```php
use Illuminate\Contracts\View\View;
use Relaticle\ActivityLog\Contracts\TimelineRenderer;
use Relaticle\ActivityLog\Support\ActivityLogSummary;
use Relaticle\ActivityLog\Timeline\TimelineEntry;

final class AuditedActivityLogRenderer implements TimelineRenderer
{
    public function render(TimelineEntry $entry): View
    {
        $summary = ActivityLogSummary::from($entry);

        return view('audit.timeline.entry', [
            'entry' => $entry,
            'summary' => $summary,
        ]);
    }
}
```

--------------------------------

### Register renderer for merge key

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Register a renderer for the merge key. The string passed as mergedRenderer becomes $entry->renderer, which the registry resolves first, before any event/type binding. This is step 3 of the end-to-end wiring for same-save merge.

```php
use Relaticle\ActivityLog\Facades\Timeline;

Timeline::registerRenderer('merged-activity', \App\Timeline\Renderers\MergedActivityRenderer::class);
```

--------------------------------

### Timeline pipeline flow

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/2.concepts/1.how-it-works.md

A visual representation of the data flow from the initial builder call through resolution, processing, and final rendering.

```text
$record->timeline()             [TimelineBuilder]
    ↓ resolves
TimelineSource(s) per source    [resolve(subject, Window)]
    ↓ yields
TimelineEntry stream            [filter → dedup → sort]
    ↓ paginated
LengthAwarePaginator → Renderer → Blade view
```

--------------------------------

### Override source priority per-call

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/2.concepts/1.how-it-works.md

Pass the second argument to any builder helper to override the default source priority.

```php
$record->timeline()->fromCustom($resolver, priority: 100);
```

--------------------------------

### Register renderer with class string

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Registers a renderer by providing a class string that implements the TimelineRenderer contract. The class is resolved through the container, allowing constructor dependency injection.

```php
use Relaticle\ActivityLog\Facades\Timeline;

Timeline::registerRenderer('email_sent', \App\Timeline\Renderers\EmailSentRenderer::class);
```

--------------------------------

### Override source priority with $priority in from*() methods

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Use this snippet to override the default source priority for individual timeline sources. Each from*() method accepts an optional $priority argument, which takes precedence over config('activity-log.source_priorities.*'). Useful when a resource needs a non-default priority without modifying config/activity-log.php.

```php
$record->timeline()
    ->fromActivityLog(priority: 50)
    ->fromActivityLogOf(['comments'], priority: 60)
    ->fromRelation('invoices', $configure, priority: 80)
    ->fromCustom($resolver, priority: 100);
```

--------------------------------

### Basic fromActivityLog() usage

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Basic usage of fromActivityLog() to retrieve timeline entries from the activity_log table where subject_type and subject_id match the subject. Each row becomes a TimelineEntry with type='activity_log'. The subject must be persisted; otherwise ActivityLogSource::resolve() throws a DomainException.

```php
$entries = $record->timeline()
    ->fromActivityLog()
    ->get();
```

--------------------------------

### Person model with composed timeline() method

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/1.crm-person-feed.md

Defines the Person model with HasMany relations and a timeline() method that merges activity from the person's own log, related model logs, and timestamp-based events. Uses Relaticle's TimelineBuilder with fromActivityLog, fromActivityLogOf, and fromRelation sources. Requires the Email model to have a sent_at column and Task to have completed_at.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Relaticle\ActivityLog\Concerns\InteractsWithTimeline;
use Relaticle\ActivityLog\Contracts\HasTimeline;
use Relaticle\ActivityLog\Timeline\Sources\RelatedModelSource;
use Relaticle\ActivityLog\Timeline\TimelineBuilder;
use Spatie\Activitylog\LogOptions;
use Spatie\Activitylog\Traits\LogsActivity;

final class Person extends Model implements HasTimeline
{
    use InteractsWithTimeline;
    use LogsActivity;

    protected $fillable = ['name', 'email', 'company'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()->logFillable();
    }

    public function emails(): HasMany
    {
        return $this->hasMany(Email::class);
    }

    public function notes(): HasMany
    {
        return $this->hasMany(Note::class);
    }

    public function tasks(): HasMany
    {
        return $this->hasMany(Task::class);
    }

    public function timeline(): TimelineBuilder
    {
        return TimelineBuilder::make($this)
            ->fromActivityLog()
            ->fromActivityLogOf(['emails', 'notes', 'tasks'])
            ->fromRelation('emails', function (RelatedModelSource $source): void {
                $source
                    ->event(column: 'sent_at', event: 'email_sent', icon: 'heroicon-o-paper-airplane', color: 'primary')
                    ->title(fn (Email $email): string => $email->subject ?? 'Email')
                    ->description(fn (Email $email): ?string => "to {$email->recipient}")
                    ->causer(fn (Email $email) => $email->sender);
            })
            ->fromRelation('tasks', function (RelatedModelSource $source): void {
                $source
                    ->event(column: 'completed_at', event: 'task_completed', icon: 'heroicon-o-check-circle', color: 'success')
                    ->title(fn (Task $task): string => $task->title);
            });
    }
}
```

--------------------------------

### Mount ActivityLogRelationManager with ownerRecord and pageClass

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Mounts the relation manager in a Pest test, requiring both 'ownerRecord' and 'pageClass'. Adjust 'pageClass' to the hosting resource page, typically an Edit* or View* page.

```php
use App\Filament\Resources\People\Pages\EditPerson;
use Relaticle\ActivityLog\Filament\RelationManagers\ActivityLogRelationManager;

use function Pest\Livewire\livewire;

it('mounts the activity log relation manager for a record', function (): void {
    livewire(ActivityLogRelationManager::class, [
        'ownerRecord' => $this->record,
        'pageClass' => EditPerson::class,
    ])->assertSuccessful();
});
```

--------------------------------

### MIT License text

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/7.community/2.license.md

The full MIT License text for relaticle/activity-log. It grants permission to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software, provided the copyright notice and permission notice are included. The software is provided 'AS IS' without warranty of any kind.

```text
Copyright (c) Relaticle

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
```

--------------------------------

### Embed ActivityLog Infolist Component

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/2.filament-ui.md

Use the ActivityLog component to embed a timeline within a Filament infolist. It supports fluent configuration for grouping, pagination, empty states, and infinite scrolling.

```php
use Relaticle\ActivityLog\Filament\Infolists\Components\ActivityLog;

ActivityLog::make('timeline')
    ->groupByDate()
    ->perPage(10)
    ->emptyState('Nothing here yet — give it time.')
    ->infiniteScroll()
    ->columnSpanFull(),
```

--------------------------------

### Register ActivityLogAction in Header

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/2.filament-ui.md

Add the ActivityLogAction to the getHeaderActions method of your Filament page to open the activity timeline in a slide-over.

```php
use Relaticle\ActivityLog\Filament\Actions\ActivityLogAction;

protected function getHeaderActions(): array
{
    return [
        ActivityLogAction::make(),
    ];
}
```

--------------------------------

### fromActivityLogOf() - Register related activity-log source

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Registers RelatedActivityLogSource for spatie activity-log entries of related models. The first block is the method signature; the second shows usage with an opportunity timeline. For each named relation, the source loads related rows and queries activity_log for matching (subject_type, subject_id) pairs. Warning: it fetches all related rows without a limit, which can be costly for large relations.

```php
public function fromActivityLogOf(array $relations, ?int $priority = null): self
```

```php
$entries = $opportunity->timeline()
    ->fromActivityLogOf(['comments', 'tasks'])
    ->get();
```

--------------------------------

### timeline()->paginate(?int $perPage, int $page)

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Paginates the timeline results and returns a LengthAwarePaginator instance.

```APIDOC
## timeline()->paginate(?int $perPage = null, int $page = 1)

### Description
Paginates the timeline results and returns a LengthAwarePaginator instance.

### Parameters
- **$perPage** (?int) - Optional - Number of items per page. Defaults to `default_per_page` config (20) if null.
- **$page** (int) - Optional - The page number. Defaults to 1.

### Usage
```php
$page = $record->timeline()->fromActivityLog()->paginate(perPage: 25, page: 2);
```

### Returns
- `LengthAwarePaginator<int, TimelineEntry>` - The paginator instance.

### Notes
`$perPage = null` falls back to `default_per_page` config (20).
```

--------------------------------

### Register renderer with view name

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Registers a renderer by providing a Blade view path string. The view receives $entry in scope automatically.

```php
use Relaticle\ActivityLog\Facades\Timeline;

Timeline::registerRenderer('note_added', 'app::timeline.note-added');
```

--------------------------------

### Register custom activity_log renderer with ActivityLogPlugin

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/4.customization.md

Registers a custom renderer class for the 'activity_log' type key, replacing the built-in ActivityLogRenderer. Use this to redact sensitive fields, change the diff format, or embed approval buttons.

```php
use Relaticle\ActivityLog\Filament\ActivityLogPlugin;

ActivityLogPlugin::make()->renderers([
    'activity_log' => \App\Timeline\Renderers\AuditedActivityLogRenderer::class,
]);
```

--------------------------------

### Gate ActivityLogAction with ->visible()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/2.audit-log-for-admins.md

Add the ActivityLogAction to a Filament ViewRecord page and restrict access to administrators using the ->visible() method.

```php
namespace App\Filament\Resources\Users\Pages;

use App\Filament\Resources\Users\UserResource;
use Filament\Resources\Pages\ViewRecord;
use Relaticle\ActivityLog\Filament\Actions\ActivityLogAction;

final class ViewUser extends ViewRecord
{
    protected static string $resource = UserResource::class;

    protected function getHeaderActions(): array
    {
        return [
            ActivityLogAction::make()
                ->label('Audit log')
                ->icon('heroicon-o-shield-check')
                ->visible(fn (): bool => auth()->user()?->isAdmin() ?? false),
        ];
    }
}
```

--------------------------------

### Assert timeline entries from ActivityLog builder

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Asserts timeline entries directly by creating an Activity row and calling the builder. The same pattern works for fromRelation(), fromActivityLogOf(), and fromCustom(); assert against $entries->pluck('event'), ->count(), or other TimelineEntry properties.

```php
use Spatie\Activitylog\Models\Activity;

it('emits an entry per activity row', function (): void {
    Activity::create([
        'log_name' => 'default',
        'description' => 'updated',
        'event' => 'updated',
        'subject_type' => $this->record->getMorphClass(),
        'subject_id' => $this->record->getKey(),
        'properties' => ['attributes' => ['name' => 'New'], 'old' => ['name' => 'Old']],
    ]);

    $entries = $this->record->timeline()->fromActivityLog()->get();

    expect($entries)
        ->toHaveCount(1)
        ->and($entries->first()->event)->toBe('updated');
});
```

--------------------------------

### User model with focused timeline()

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/2.audit-log-for-admins.md

Defines the User model with LogsActivity and InteractsWithTimeline traits. Uses logFillable() and logOnlyDirty() to log only changed fillable attributes, and timeline() filters to CRUD events (created, updated, deleted, restored). Sensitive fields are hidden via $hidden.

```php
namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Relaticle\ActivityLog\Concerns\InteractsWithTimeline;
use Relaticle\ActivityLog\Contracts\HasTimeline;
use Relaticle\ActivityLog\Timeline\TimelineBuilder;
use Spatie\Activitylog\LogOptions;
use Spatie\Activitylog\Traits\LogsActivity;

final class User extends Authenticatable implements HasTimeline
{
    use InteractsWithTimeline;
    use LogsActivity;

    protected $fillable = ['name', 'email', 'role', 'password'];

    protected $hidden = ['password', 'remember_token'];

    public function getActivitylogOptions(): LogOptions
    {
        return LogOptions::defaults()
            ->logFillable()
            ->logOnlyDirty()
            ->dontSubmitEmptyLogs();
    }

    public function isAdmin(): bool
    {
        return $this->role === 'admin';
    }

    public function timeline(): TimelineBuilder
    {
        return TimelineBuilder::make($this)
            ->fromActivityLog()
            ->ofEvent(['created', 'updated', 'deleted', 'restored']);
    }
}
```

--------------------------------

### Cache key composition format

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/5.caching.md

The cache key format for each cached `paginate()` call. It includes the prefix, model class, subject key, filter hash, and pagination parameters.

```text
{prefix}:{model_class}:{key}:{filter_hash}:p{page}:pp{perPage}
```

--------------------------------

### Pagination buffer formula

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

The pagination buffer over-fetch strategy calculates the maximum entries requested from each source. The cap is perPage multiplied by (page + buffer), with the default buffer value of 2. This over-fetching ensures deeper pages remain complete after deduplication and filtering.

```text
cap = perPage × (page + buffer)
```

--------------------------------

### Sort timeline entries by date

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Use sortByDateDesc() for newest first or sortByDateAsc() for oldest first. Sorting occurs after sources are merged.

```php
$record->timeline()->sortByDateDesc()->get(); // default — newest first

$record->timeline()->sortByDateAsc()->get();  // oldest first
```

--------------------------------

### Add ActivityLogAction to Person table

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/1.crm-person-feed.md

Add the bundled ActivityLogAction to the Person table's actions for quick access from the list view.

```php
use Filament\Tables\Table;
use Relaticle\ActivityLog\Filament\Actions\ActivityLogAction;

public function table(Table $table): Table
{
    return $table
        ->columns([/* ... */])
        ->actions([
            ActivityLogAction::make(),
        ]);
}
```

--------------------------------

### Conditionally enable caching with TTL=0

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/5.caching.md

Use `cached(ttlSeconds: $cacheEnabled ? 300 : 0)` to conditionally enable caching. A TTL of 0 is a no-op, allowing you to toggle caching without changing the call site.

```php
$record->timeline()
    ->cached(ttlSeconds: $cacheEnabled ? 300 : 0)
    ->paginate();
```

--------------------------------

### Call header action 'activityLog' on ViewPerson page

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/5.testing/1.index.md

Tests the default header action named 'activityLog' by calling it on the page. If the action was renamed via ActivityLogAction::make('history'), pass 'history' instead.

```php
use App\Filament\Resources\People\Pages\ViewPerson;

use function Pest\Livewire\livewire;

it('opens the activity log slide-over', function (): void {
    livewire(ViewPerson::class, ['record' => $this->record->getKey()])
        ->callAction('activityLog')
        ->assertSuccessful();
});
```

--------------------------------

### Filter timeline with between, ofType, exceptType, ofEvent, exceptEvent

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Chainable filter methods on TimelineBuilder. The between() method passes a Window to each source; type and event filters are mirrored onto each source's Window and re-applied post-yield as a safety net. Use ofType(['activity_log', 'related_activity_log']) to match both spatie-log sources.

```php
$record->timeline()
    ->between(now()->subMonth(), now())
    ->ofType(['activity_log'])
    ->exceptType(['custom'])
    ->ofEvent(['created', 'updated'])
    ->exceptEvent(['draft_saved'])
    ->get();
```

--------------------------------

### Register renderer in AppPanelProvider

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/1.crm-person-feed.md

Registers the custom renderer for the 'email_sent' event via ActivityLogPlugin::make()->renderers(). Only email_sent entries use this renderer; others fall back to defaults.

```php
use App\Timeline\Renderers\EmailSentRenderer;
use Relaticle\ActivityLog\Filament\ActivityLogPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(ActivityLogPlugin::make()->renderers([
            'email_sent' => EmailSentRenderer::class,
        ]))
        // ...
    ;
}
```

--------------------------------

### Trigger activity with tinker update command

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/2.quick-start.md

Trigger an activity by updating a Person record via tinker. After refreshing the view page, an entry titled "updated" appears with the changed-fields diff inline.

```bash
php artisan tinker --execute 'App\Models\Person::find(1)->update(["name" => "New name"]);'
```

--------------------------------

### PHP renderer class for email_sent

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/4.recipes/1.crm-person-feed.md

Implements TimelineRenderer to return a view for the email_sent event. The render method receives a TimelineEntry and returns a View.

```php
namespace App\Timeline\Renderers;

use Illuminate\Contracts\View\View;
use Relaticle\ActivityLog\Contracts\TimelineRenderer;
use Relaticle\ActivityLog\Timeline\TimelineEntry;

final class EmailSentRenderer implements TimelineRenderer
{
    public function render(TimelineEntry $entry): View
    {
        return view('app.timeline.email-sent', ['entry' => $entry]);
    }
}
```

--------------------------------

### Customize deduplication key

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/3.refining-the-timeline.md

Override the default deduplication key by providing a closure that returns a unique string for each TimelineEntry.

```php
$record->timeline()
    ->dedupKeyUsing(fn ($entry) => "{$entry->type}:{$entry->event}:{$entry->occurredAt->toDateString()}");
```

--------------------------------

### Add batch_uuid column migration

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/3.essentials/1.sources.md

Migration to add the batch_uuid column to the activity_log table. Required for the same-save merge feature. The package only reads this column; the host app owns it. Rows with null/empty batch_uuid are never merged.

```php
Schema::table('activity_log', function (Blueprint $table): void {
    $table->uuid('batch_uuid')->nullable()->index();
});
```

--------------------------------

### Add plugin views to Tailwind theme

Source: https://github.com/relaticle/activity-log/blob/1.x/docs/content/1.getting-started/1.installation.md

Add this line to your custom theme.css file to ensure the plugin's Blade templates are compiled correctly. This is only required if you are using a custom Filament theme.

```css
@source '../../../../vendor/relaticle/activity-log/resources/views/**/*';
```
Tokens:
Raw