Filament Logger

https://github.com/mradder/filament-logger
Admin
Filament Logger is an audit log and activity log package for Filament admin panels. Built on...
Tokens:61,971
Snippets:455
Trust Score:7.7
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Run migrations

Source: https://github.com/mradder/filament-logger/blob/main/docs/installation.md

Run this artisan command to execute the published migrations.

```bash
php artisan migrate
```

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

### Publish translations

Source: https://github.com/mradder/filament-logger/blob/main/docs/installation.md

Run this artisan command to publish the translation files for the package.

```bash
php artisan vendor:publish --tag="filament-logger-translations"
```

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

### Publish config and migrations

Source: https://github.com/mradder/filament-logger/blob/main/docs/installation.md

Run this artisan command to publish the package config and the Spatie Activitylog migration stub.

```bash
php artisan filament-logger:install
```

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

### Example: log only web guard events

Source: https://github.com/mradder/filament-logger/blob/main/README.md

Example configuration for a Filament panel + storefront app that logs only panel auth events from the web guard.

```php
'access' => [
    // Log only panel auth events from the web guard.
    'guards' => ['web'],
],
```

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

### Install filament-logger via Composer

Source: https://github.com/mradder/filament-logger/blob/main/README.md

Run this command to install the mradder/filament-logger package.

```bash
composer require mradder/filament-logger
```

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

### Prune command examples with options

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Examples of pruning with various options: --days=90, --log-name (repeatable), --except-log-name, and --dry-run. These show how to target specific logs or preview the operation.

```bash
php artisan filament-logger:prune --days=90
```

```bash
php artisan filament-logger:prune --days=90 --log-name=Access --log-name=Resource
```

```bash
php artisan filament-logger:prune --days=90 --except-log-name=Notification
```

```bash
php artisan filament-logger:prune --dry-run
```

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

### Install dependencies

Source: https://github.com/mradder/filament-logger/blob/main/CONTRIBUTING.md

Install PHP and JavaScript dependencies for local development.

```bash
composer install
npm install
```

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

### Example export metadata header contents

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Shows the JSON structure of the X-Activity-Export-Metadata response header. The header is dropped if it exceeds 4 KB; applied filters are not included in the header.

```json
{
    "exported_at": "2026-05-26T12:00:00+00:00",
    "exported_by": 1,
    "exported_by_name": "alice@example.com",
    "columns": ["id", "description", "tags", "created_at"],
    "source": "MrAdder\\FilamentLogger\\Resources\\ActivityResource"
}
```

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

### Start Tinker for testing alerts

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Opens an interactive PHP shell to manually trigger and verify alert behavior.

```bash
php artisan tinker
```

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

### Create notifications table for database notifications

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Required setup when 'notify' is set to 'database'. Creates Laravel's notifications table and runs migrations; without this, Filament database notifications will not work.

```bash
php artisan make:notifications-table   # or: php artisan notifications:table
php artisan migrate
```

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

### Publish and run optional migration for indexes

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Publish and run the optional migration adding indexes on created_at and (event, created_at) for large audit trails.

```bash
php artisan vendor:publish --tag=filament-logger-migrations
php artisan migrate
```

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

### Deep-link URL example

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Shows the equivalent deep link to an Activity resource view with a specific tab and date filter, as resolved from playbook links.

```text
/admin/activity-logs?activeTab=high_risk&tableFilters[created_at][preset]=last_30_days
```

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

### Custom playbook example

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Shows how to add a custom playbook for a specific workflow, such as reviewing sensitive changes in the last 24 hours. Uses the 'high_risk' preset with a 'last_24_hours' date preset.

```php
'activity_playbooks' => [
    'sensitive_changes_last_24h' => [
        'label' => 'Sensitive Changes (24h)',
        'icon' => 'heroicon-o-key',
        'preset' => 'high_risk',
        'date_preset' => 'last_24_hours',
    ],
],
```

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

### Register hooks in service provider boot()

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Register all hooks from the boot() method of a service provider. This example registers a causer label hook and an activity alert rule for the 'contract_signed' event.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use MrAdder\FilamentLogger\Support\ActivityAlertRules;
use MrAdder\FilamentLogger\Support\ActivityDisplay;

class AuditServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        ActivityDisplay::causerLabelUsing(
            fn (?Model $causer): ?string => $causer?->full_name,
        );

        ActivityAlertRules::register('contract_signed', [
            'enabled' => true,
            'channels' => ['webhook'],
            'events' => ['Contract Signed'],
        ]);
    }
}
```

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

### Register custom activity description callback

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Registers a callback via FilamentLogger::describeUsing to override activity descriptions globally. Returning null falls back to the built-in description. The example customizes descriptions for Order models.

```php
use MrAdder\FilamentLogger\Facades\FilamentLogger;

FilamentLogger::describeUsing(function ($subject, string $event, string $logName): ?string {
    return $subject instanceof \App\Models\Order
        ? "Order {$subject->reference} {$event}"
        : null;
});
```

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

### Register ExportPresetResource in panel

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Register the management resource in the panel that should administer DB presets; it is not registered automatically.

```php
use MrAdder\FilamentLogger\Resources\ExportPresetResource;

return $panel->resources([
    config('filament-logger.activity_resource'),
    ExportPresetResource::class,
]);
```

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

### Analyze Filament 3 compatibility shims

Source: https://github.com/mradder/filament-logger/blob/main/CONTRIBUTING.md

Install Filament 3 and run PHPStan with the dedicated config for the compatibility shims.

```bash
composer require "filament/filament:3.*" --with-all-dependencies
vendor/bin/phpstan analyse -c phpstan-filament3.neon.dist
```

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

### Webhook channel configuration with custom headers

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configure the generic 'webhook' alert channel with a URL and custom headers, such as an Authorization bearer token. This channel receives a structured JSON payload instead of a service-specific shape. The example uses environment variables for the URL and token.

```php
'alerts' => [
    'webhook' => [
        'url' => env('AUDIT_WEBHOOK_URL'),
        'headers' => [
            'Authorization' => 'Bearer '.env('AUDIT_WEBHOOK_TOKEN'),
        ],
    ],
],
```

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

### Example webhook JSON payload

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Example JSON payload sent to the generic webhook channel. It includes alert title, message, rule name, count, and activity details such as event, description, risk, subject, causer, and timestamp. This payload is used when a rule triggers an alert.

```json
{
    "title": "Destructive activity detected",
    "message": "Record deleted\nEvent: Deleted\nLog: Resource\n...",
    "rule": "Destructive Activity",
    "count": 1,
    "activity": {
        "id": 4213,
        "log_name": "Resource",
        "event": "Deleted",
        "description": "Order Deleted by Dan",
        "risk": "high",
        "risk_reasons": "destructive",
        "subject_type": "App\\Models\\Order",
        "subject_id": 42,
        "causer_type": "App\\Models\\User",
        "causer_id": 1,
        "logged_at": "2026-08-10 14:03:11"
    }
}
```

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

### Define alert title and message templates with placeholders

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configure a rule's 'title' and 'message' templates using ':placeholder' tokens. The 'label' key still works as the title if templates are not defined.

```php
'rules' => [
    'role_changes' => [
        'channels' => ['slack'],
        'risk_reasons' => ['role_change', 'permission_change'],
        'title' => '[:risk] :rule on :subject',
        'message' => ':causer changed :subject at :logged_at (:risk_reasons)',
    ],
],
```

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

### Prune exports with dry-run

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Manually run the prune command with a retention period of 7 days and a dry-run to preview what would be deleted.

```bash
php artisan filament-logger:prune-exports --days=7 --dry-run
```

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

### Resource Logging Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configures resource observers, enabled by default, with global, per-model, and per-resource ignore lists for noisy attributes.

```php
'resources' => [
    'enabled' => true,
    'ignore' => ['updated_at', 'remember_token'],
    'ignore_for_models' => [
        App\Models\User::class => ['last_seen_at', 'login_count'],
    ],
    'ignore_for_resources' => [
        App\Filament\Resources\UserResource::class => ['last_seen_at', 'login_count'],
    ],
],
```

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

### Configure performance caching for filter options

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configure cache store, TTL, and limit for filter dropdown options. 'cache_store' null uses default store, TTL 300 seconds, limit caps distinct values.

```php
'performance' => [
    'cache_store' => null,          // null uses the default store
    'filter_options_cache_ttl' => 300,  // seconds; 0 disables caching
    'filter_options_limit' => 200,      // cap on distinct values pulled
],
```

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

### Model Logging Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Registers additional Eloquent models not managed through Filament resources, with optional ignore lists per model.

```php
'models' => [
    'enabled' => true,
    'register' => [
        App\Models\User::class,
    ],
    'ignore' => ['updated_at', 'remember_token'],
    'ignore_for' => [
        App\Models\User::class => ['last_seen_at', 'login_count'],
    ],
],
```

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

### Slack alert configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

References the Slack webhook URL from the environment in the package config. This is part of the Slack channel setup.

```php
'alerts' => [
    'enabled' => true,
    'slack' => [
        'webhook_url' => env('FILAMENT_LOGGER_SLACK_WEBHOOK_URL'),
    ],
],
```

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

### Discord alert configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

References the Discord webhook URL from the environment in the package config. This is part of the Discord channel setup.

```php
'alerts' => [
    'enabled' => true,
    'discord' => [
        'webhook_url' => env('FILAMENT_LOGGER_DISCORD_WEBHOOK_URL'),
    ],
],
```

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

### Configure digest alerts for a rule

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Batch matching activities into one alert by setting 'digest' to true and specifying 'digest_minutes'. The first matching activity opens a window; one alert is sent when it closes, carrying ':count'.

```php
'rules' => [
    'destructive_activity' => [
        'channels' => ['slack'],
        'events' => ['Deleted', 'Force Deleted'],
        'digest' => true,
        'digest_minutes' => 60,
        'digest_title' => ':count deletions in the last :window minutes',
        'digest_message' => 'Latest: :description',
    ],
],
```

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

### Access Event Logging Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Enables or disables auth event logging per event type. The two_factor_recovery event is only registered when the Fortify event class is available.

```php
'access' => [
    'events' => [
        'login' => true,
        'logout' => true,
        'failed' => true,
        'lockout' => true,
        'password_reset' => true,
        'two_factor_recovery' => true,
    ],
],
```

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

### ActivityPolicy with panel-based access

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Policy that differentiates access per panel. Partners get no audit log; admin requires 'audit.view-all' permission. Strict by default: missing policy or methods denies access.

```php
namespace App\Policies;

use Filament\Facades\Filament;
use Spatie\Activitylog\Models\Activity;

class ActivityPolicy
{
    public function viewAny(User $user): bool
    {
        return match (Filament::getCurrentPanel()?->getId()) {
            'admin' => $user->can('audit.view-all'),
            'partner' => false,          // partners get no audit log at all
            default => false,
        };
    }

    public function view(User $user, Activity $activity): bool
    {
        return $this->viewAny($user);
    }
}
```

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

### Store full IPs and redact for unauthorized viewers

Source: https://github.com/mradder/filament-logger/blob/main/docs/security.md

Most flexible IP setup: store full IPs and only redact them for viewers who do not pass the sensitive-data check. Keeps full IPs available for privileged reviewers while showing [REDACTED] to other users.

```php
'access' => [
    'store_ip' => true,
    'anonymize_ip' => false,
    'redact_ip_for_unauthorized_viewers' => true,
],
```

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

### Diff Formatting Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Adjusts how large values are displayed in the structured diff view on the activity detail page. The 'collapse_after' sets the threshold for collapsing large values, and 'pretty_print_json' enables pretty printing of JSON.

```php
'diff' => [
    'collapse_after' => 120,
    'pretty_print_json' => true,
],
```

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

### Flush filter options cache

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Call flushCache() to immediately refresh cached filter options after bulk import or prune.

```php
use MrAdder\FilamentLogger\Resources\ActivityResource\Support\ActivityResourceTableOptions;

ActivityResourceTableOptions::flushCache();
```

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

### Schedule export pruning command

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Schedule the cleanup command to prune generated export files. Run daily via Laravel's scheduler.

```php
Schedule::command('filament-logger:prune-exports')->daily();
```

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

### Set translation lines for activity descriptions

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Defines translation lines for activity descriptions. The keys 'log.description' and 'log.description_by' control the format, using placeholders like ':model', ':event', ':description', and ':user'.

```php
'log.description' => ':model :event',
'log.description_by' => ':description by :user',
```

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

### Complete alerts configuration with rules

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

Full alerts configuration including enabled flag, cache store, channel settings, and multiple rules with channels, events, risk reasons, thresholds, and cooldowns. This is the comprehensive setup for sensitive activity alerts.

```php
'alerts' => [
    'enabled' => true,
    'cache_store' => 'redis',
    'mail' => [
        'to' => ['security@example.com'],
    ],
    'slack' => [
        'webhook_url' => 'https://hooks.slack.com/services/...',
    ],
    'discord' => [
        'webhook_url' => 'https://discord.com/api/webhooks/...',
    ],
    'rules' => [
        'destructive_activity' => [
            'channels' => ['mail', 'slack', 'discord'],
            'events' => ['Deleted', 'Force Deleted'],
            'cooldown_minutes' => 10,
        ],
        'role_changes' => [
            'channels' => ['mail'],
            'risk_reasons' => ['role_change'],
            'cooldown_minutes' => 15,
        ],
        'failed_login_spike' => [
            'type' => 'threshold',
            'log_names' => ['Access'],
            'events' => ['Failed Login'],
            'threshold' => 5,
            'window_minutes' => 10,
            'cooldown_minutes' => 15,
        ],
    ],
],
```

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

### Privacy-related configuration overrides

Source: https://github.com/mradder/filament-logger/blob/main/docs/security.md

Example overrides for redaction, sensitive keys, authorization, access, and notification settings. The key matcher is recursive and normalization-aware, catching variants like client-secret, request_authorization, or nested profile.ip_address values.

```php
'redacted_placeholder' => '[REDACTED]',

'sensitive_keys' => [
    'password',
    'api_token',
    'client_secret',
    'webhook_url',
    'authorization',
    'ip_address',
],

'authorization' => [
    'sensitive_ability' => 'viewSensitiveData',
],

'access' => [
    'store_ip' => true,
    'anonymize_ip' => true,
    'redact_ip_for_unauthorized_viewers' => false,
    'store_user_agent' => true,
    'user_agent_max_length' => 255,
],

'notifications' => [
    'log_recipient' => false,
    'mask_recipient' => true,
],
```

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

### Queued exports configuration array

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configuration block for enabling queued exports. Set 'enabled' to true and adjust 'threshold' (rows above which export is queued; 0 always queues), 'connection', 'name', 'disk', 'path', 'notify' ('mail' | 'database' | null), 'routes', 'route_prefix', 'route_middleware', 'link_minutes', and 'retention_days'. Default 'enabled' is false, which streams exports directly.

```php
'exports' => [
    'queue' => [
        'enabled' => true,
        'threshold' => 5000,   // rows above which an export is queued; 0 always queues
        'connection' => null,
        'name' => null,
        'disk' => 'local',
        'path' => 'filament-logger/exports',
        'notify' => 'mail',   // 'mail' | 'database' | null
        'routes' => true,
        'route_prefix' => 'filament-logger',
        'route_middleware' => ['web', 'signed'],
        'link_minutes' => 1440,
        'retention_days' => 7,
    ],
],
```

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

### Remove a table column with tableColumnsUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Remove a column from the activity table by filtering the columns array. This example removes the 'description' column.

```php
ActivityDisplay::tableColumnsUsing(
    fn (array $columns): array => array_values(array_filter(
        $columns,
        fn ($column): bool => $column->getName() !== 'description',
    )),
);
```

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

### Export authorization ability configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configure export gating in the Filament resource. Set 'ability' to null to allow any viewer; without the ability, export actions are hidden and direct export method calls return a 403.

```php
'exports' => [
    'ability' => 'exportActivity',        // set to null to allow any viewer
    'manage_ability' => 'manageExportPresets',
],
```

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

### Schedule digest alert command

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Schedule the 'filament-logger:send-alert-digests' command to run every five minutes for reliable, on-time delivery of digest alerts.

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('filament-logger:send-alert-digests')->everyFiveMinutes();
```

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

### Remove a review tab with tabsUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Remove specific review tabs by their filter preset name using tabsUsing. This example drops the 'auth_anomalies' tab.

```php
ActivityDisplay::tabsUsing(
    fn (array $tabs): array => collect($tabs)->except(['auth_anomalies'])->all(),
);
```

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

### Guard-Based Access Logging Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Scopes access logging to specific guards in multi-guard applications. With ['web'], only events with a guard property (Login, Logout, Failed) for listed guards are logged; events without a guard property are always logged.

```php
'access' => [
    'guards' => ['web'],
],
```

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

### Queue alerts with webhook timeout configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configure alert delivery to use a queue with a Redis connection and a named queue, and set a webhook timeout of 5 seconds. Enabling 'queue' moves mail alerts and webhook dispatches to the queue, avoiding slow webhooks blocking the audited action. Webhook failures (non-2xx responses) release the rule cooldown to allow retries.

```php
'alerts' => [
    'queue' => true,
    'queue_connection' => 'redis',
    'queue_name' => 'audit-alerts',
    'webhook_timeout' => 5,
],
```

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

### Override alert rules with ActivityAlertRules::resolveUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Use this for full control over the merged rule set. It runs last and receives the merged rules, so it can remove rules as well as add them. The example disables all alerts outside production.

```php
ActivityAlertRules::resolveUsing(function (array $rules): array {
    return app()->environment('production')
        ? $rules
        : [];   // no alerts outside production
});
```

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

### Mail alert recipients configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

Sets the recipients for alert emails in the package config. This block is part of the mail channel setup and must be used after configuring the mailer in `.env`.

```php
'alerts' => [
    'enabled' => true,
    'mail' => [
        'to' => [
            'security@example.com',
            'ops@example.com',
        ],
    ],
],
```

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

### Risk Tagging Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Automatically tags high-risk activity based on specific events or changed attributes. The 'high' risk level includes events like 'Deleted' and 'Force Deleted', and change keys like 'role' and 'permissions'.

```php
'risk' => [
    'high' => [
        'events' => [
            'Deleted',
            'Force Deleted',
            'Failed Login',
            'Lockout',
        ],
        'change_keys' => [
            'role',
            'role_id',
            'roles',
            'permission',
            'permissions',
        ],
    ],
],
```

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

### Configure custom risk heuristic for billing changes

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Adds a custom risk heuristic named 'billing_change' under 'risk.heuristics' with a medium level and specific change keys. Set an array to empty to disable a heuristic; an explicitly supplied risk level is never overridden.

```php
'risk' => [
    'heuristics' => [
        'billing_change' => [
            'level' => 'medium',
            'change_keys' => ['plan', 'billing_email', 'card_last_four'],
        ],
    ],
],
```

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

### Sensitive Key Redaction Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Extends the list of redactable keys in the config. Applies recursively across old, attributes, metadata, exports, and the activity detail view. The matcher normalizes key names, catching values like request_authorization, client-secret, and nested profile.ip_address.

```php
'redacted_placeholder' => '[REDACTED]',

'sensitive_keys' => [
    'password',
    'api_token',
    'client_secret',
    'webhook_url',
    'authorization',
    'ip_address',
],
```

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

### Disable properties search in search filter

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Set 'include_properties' to false to exclude the JSON properties column from the search filter, improving performance on large tables since LIKE over JSON cannot use an index.

```php
'search' => [
    'include_properties' => false,
],
```

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

### Define custom log names and colors

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Configures custom log names and colors under 'custom' and 'custom_events' keys. The 'custom' array defines a log name 'Security' with color 'danger'; 'custom_events' sets a default log name 'Custom' with color 'primary'.

```php
'custom' => [
    [
        'log_name' => 'Security',
        'color' => 'danger',
    ],
],

'custom_events' => [
    'default_log_name' => 'Custom',
    'color' => 'primary',
],
```

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

### Alert Throttling Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Throttles sensitive activity alerts per rule to reduce noise from repeated matching events. Cooldown keys are stored in the default cache store unless 'alerts.cache_store' is set. Threshold rules alert as soon as the count reaches the threshold and keep alerting while above it, defaulting cooldown to 'window_minutes' unless overridden.

```php
'alerts' => [
    'cache_store' => 'redis',
    'rules' => [
        'destructive_activity' => [
            'events' => ['Deleted', 'Force Deleted'],
            'cooldown_minutes' => 10,
        ],
    ],
],
```

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

### Publish config and migrations

Source: https://github.com/mradder/filament-logger/blob/main/README.md

Run these artisan commands to publish the package configuration and the Spatie activity log migrations.

```bash
php artisan filament-logger:install
php artisan migrate
```

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

### IP Redaction and Sensitive Data Authorization Configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/configuration.md

Redacts stored IP addresses at view/export time for users lacking the sensitive-data policy ability. Useful when security reviewers need full IPs but most admins see [REDACTED].

```php
'authorization' => [
    'sensitive_ability' => 'viewSensitiveData',
],

'access' => [
    'store_ip' => true,
    'anonymize_ip' => false,
    'redact_ip_for_unauthorized_viewers' => true,
],
```

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

### Useful development commands

Source: https://github.com/mradder/filament-logger/blob/main/CONTRIBUTING.md

Run validation, linting, formatting, static analysis, tests, and documentation build.

```bash
composer validate --strict
composer lint      # vendor/bin/pint --test
composer format    # vendor/bin/pint
composer analyse   # vendor/bin/phpstan analyse
composer test      # vendor/bin/pest
composer check     # lint + analyse + test
npm run docs:build
```

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

### Register activity resource in PartnerPanelProvider

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Registers the activity resource in the partner panel via config reference. Use this in every panel that should see the activity log.

```php
// app/Providers/Filament/PartnerPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('partner')
        ->path('partner')
        ->resources([
            config('filament-logger.activity_resource'),
        ]);
}
```

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

### Enable alerts and configure Slack delivery

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Configures alerting with queueing and Slack webhook. Set 'queue' to true to avoid blocking actions; 'cache_store' is used for cooldowns.

```php
// config/filament-logger.php
'alerts' => [
    'enabled' => true,
    'queue' => true,
    'cache_store' => 'redis',
    'slack' => [
        'webhook_url' => env('AUDIT_SLACK_WEBHOOK'),
    ],
],
```

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

### Set access.guards allow-list

Source: https://github.com/mradder/filament-logger/blob/main/README.md

Configure the 'access.guards' option to an allow-list of guards. With null (default), all guards are logged; with a list like ['web'], only events with a matching guard property are logged. Events without a guard property are always logged.

```php
'access' => [
    // ...
    'guards' => ['web'],
],
```

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

### Configure dashboard widgets

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Enable dashboard widgets to display activity metrics. Set 'lookback_days' to control the time range (e.g., 30 days) and 'top_limit' for the number of top items shown.

```php
'dashboard' => [
    'enabled' => true,
    'lookback_days' => 30,
    'top_limit' => 5,
],
```

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

### Add tenant column to activity_log table

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Migration to add a nullable team_id foreign key column to the activity_log table, enabling tenant scoping for Spatie's Activity model.

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

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

### Configure generic webhook channel for alerts

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Posts structured JSON to a custom URL, enabling integration with PagerDuty or internal services. Includes custom headers and a rule for account takeover signals.

```php
'alerts' => [
    'webhook' => [
        'url' => env('AUDIT_WEBHOOK_URL'),
        'headers' => ['Authorization' => 'Bearer '.env('AUDIT_WEBHOOK_TOKEN')],
    ],
    'rules' => [
        'account_takeover_signals' => [
            'enabled' => true,
            'channels' => ['webhook'],
            'risk_reasons' => ['credential_change', 'two_factor_change'],
            'title' => 'Account security change on :subject',
        ],
    ],
],
```

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

### Schedule pruning command daily

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Recommended scheduler entry to run the prune command daily. Place this in your scheduler configuration to automate pruning.

```php
use Illuminate\Support\Facades\Schedule;

Schedule::command('filament-logger:prune')->daily();
```

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

### Register activity resource in panel provider

Source: https://github.com/mradder/filament-logger/blob/main/README.md

Add the activity resource to your Filament panel provider using the config value 'filament-logger.activity_resource'.

```php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->resources([
            config('filament-logger.activity_resource'),
        ]);
}
```

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

### Stamp tenant on activity creation

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Event listener on Activity::creating that sets team_id from Filament's current tenant if not already set, ensuring tenant scoping.

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

Activity::creating(function (Activity $activity): void {
    $activity->team_id ??= Filament::getTenant()?->getKey();
});
```

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

### Register activity resource in AdminPanelProvider

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Registers the activity resource in the admin panel via config reference. Use this in every panel that should display the activity log.

```php
// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->resources([
            config('filament-logger.activity_resource'),
        ]);
}
```

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

### Point Spatie to custom Activity model

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Configuration in config/activitylog.php setting 'activity_model' to the custom Activity class, which the package reads for resource, exports, alerts, and pruning.

```php
// config/activitylog.php
'activity_model' => \App\Models\Activity::class,
```

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

### Add detail page entries with infolistEntriesUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Append a new entry to the activity detail page using infolistEntriesUsing. The callback receives the built-in entries array and returns the modified array.

```php
ActivityDisplay::infolistEntriesUsing(function (array $entries): array {
    $entries[] = TextEntry::make('properties.request_id')->label('Request ID');

    return $entries;
});
```

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

### Default activity_playbooks configuration

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Defines the default playbooks for the Activity resource. Each playbook bundles a label, icon, and preset, with optional date_preset to set the review tab and date scope.

```php
'activity_playbooks' => [
    'all_activity' => [
        'label' => 'All Activity',
        'icon' => 'heroicon-o-bars-3-bottom-left',
        'preset' => 'all',
    ],
    'high_risk_incidents' => [
        'label' => 'High Risk Incidents',
        'icon' => 'heroicon-o-shield-exclamation',
        'preset' => 'high_risk',
        'date_preset' => 'last_30_days',
    ],
    'auth_anomalies' => [
        'label' => 'Auth Anomalies',
        'icon' => 'heroicon-o-finger-print',
        'preset' => 'auth_anomalies',
        'date_preset' => 'last_30_days',
    ],
    'failed_logins' => [
        'label' => 'Failed Logins',
        'icon' => 'heroicon-o-exclamation-triangle',
        'preset' => 'failed_logins',
        'date_preset' => 'last_7_days',
    ],
    'destructive_actions' => [
        'label' => 'Destructive Actions',
        'icon' => 'heroicon-o-fire',
        'preset' => 'destructive_recent',
        'date_preset' => 'last_7_days',
    ],
],
```

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

### Slack webhook environment variable

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

Stores the Slack incoming webhook URL in `.env`. Create an incoming webhook in Slack first, then reference it in the package config.

```dotenv
FILAMENT_LOGGER_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
```

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

### Run queue worker for alert delivery

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Required when 'queue' is enabled; otherwise alerts will not be sent.

```bash
php artisan queue:work
```

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

### Configure activity filters and date presets

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Defines the 'activity_filters' configuration array with date presets and saved filter tabs for the activity list page. Each saved filter can specify a label, icon, and criteria such as risk level, events, log names, and a date preset.

```php
'activity_filters' => [
    'date_presets' => [
        'today' => 'Today',
        'last_24_hours' => 'Last 24 Hours',
        'last_7_days' => 'Last 7 Days',
        'last_30_days' => 'Last 30 Days',
        'this_month' => 'This Month',
    ],
    'saved' => [
        'high_risk' => [
            'label' => 'High Risk',
            'icon' => 'heroicon-o-shield-exclamation',
            'risk' => ['high'],
        ],
        'destructive' => [
            'label' => 'Deletes',
            'icon' => 'heroicon-o-trash',
            'events' => ['Deleted', 'Force Deleted'],
        ],
        'auth_issues' => [
            'label' => 'Auth Issues',
            'icon' => 'heroicon-o-lock-closed',
            'log_names' => ['Access'],
            'events' => ['Failed Login', 'Lockout'],
        ],
        'failed_logins' => [
            'label' => 'Failed Logins',
            'icon' => 'heroicon-o-exclamation-triangle',
            'log_names' => ['Access'],
            'events' => ['Failed Login'],
            'date_preset' => 'last_7_days',
        ],
        'destructive_recent' => [
            'label' => 'Recent Destructive',
            'icon' => 'heroicon-o-fire',
            'events' => ['Deleted', 'Force Deleted'],
            'date_preset' => 'last_7_days',
        ],
        'auth_anomalies' => [
            'label' => 'Auth Anomalies',
            'icon' => 'heroicon-o-finger-print',
            'log_names' => ['Access'],
            'events' => ['Failed Login', 'Lockout', 'Two Factor Recovery'],
            'date_preset' => 'last_30_days',
        ],
    ],
],
```

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

### Configure pruning defaults in config

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Set default pruning options in the config file. 'days' sets retention period, 'only' and 'except' arrays filter which logs to prune. These defaults apply when command options are not provided.

```php
'pruning' => [
    'days' => 365,
    'only' => [],
    'except' => [],
],
```

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

### Add a filter with filtersUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Add a custom SelectFilter to the activity table using filtersUsing. The filter queries the 'properties->tenant' JSON column.

```php
use Filament\Tables\Filters\SelectFilter;

ActivityDisplay::filtersUsing(function (array $filters): array {
    $filters[] = SelectFilter::make('tenant')
        ->options(fn (): array => Tenant::pluck('name', 'id')->all())
        ->query(fn ($query, array $data) => filled($data['value'] ?? null)
            ? $query->where('properties->tenant', $data['value'])
            : $query);

    return $filters;
});
```

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

### Discord webhook environment variable

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

Stores the Discord webhook URL in `.env`. Create a Discord webhook first, then reference it in the package config.

```dotenv
FILAMENT_LOGGER_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

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

### Register alert rule from code

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Dynamically registers rules for each active subscription, using a webhook URL and events from the database. Useful when rules cannot be expressed in config.

```php
use MrAdder\FilamentLogger\Support\ActivityAlertRules;

foreach (AlertSubscription::active()->get() as $subscription) {
    ActivityAlertRules::register("subscription_{$subscription->id}", [
        'enabled' => true,
        'channels' => ['webhook'],
        'webhook_url' => $subscription->endpoint,
        'events' => $subscription->events,
    ]);
}
```

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

### ActivityDisplay::infolistEntriesUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Registers a callback to modify the infolist entries on the detail page. The callback receives an array of entries and returns the modified array.

```APIDOC
## ActivityDisplay::infolistEntriesUsing

### Description
Registers a callback to modify the infolist entries on the detail page. The callback receives an array of entries and returns the modified array.

### Method
`ActivityDisplay::infolistEntriesUsing`

### Parameters
- **callback** (callable) - Required - A function that receives `array $entries` and returns `array`.

### Example
```php
ActivityDisplay::infolistEntriesUsing(function (array $entries): array {
    $entries[] = TextEntry::make('properties.request_id')->label('Request ID');
    return $entries;
});
```
```

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

### Define a Slack alert rule for large refunds

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Rule fires on the custom event 'Refund Issued' in the 'Billing' log. Uses cooldown of 5 minutes to prevent alert spam.

```php
'rules' => [
    'large_refund' => [
        'enabled' => true,
        'channels' => ['slack'],
        'log_names' => ['Billing'],
        'events' => ['Refund Issued'],
        'title' => 'Refund issued on :log_name',
        'message' => ':description (risk :risk)',
        'cooldown_minutes' => 5,
    ],
],
```

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

### Prune old activity records with artisan command

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Run the filament-logger:prune command to delete old activity records. Use --days to specify retention period, --log-name to prune only specific logs (repeatable), --except-log-name to exclude logs, and --dry-run to preview without deleting.

```bash
php artisan filament-logger:prune
```

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

### Trigger a test alert via FilamentLogger facade

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Logs a test event to verify alert delivery. With queue enabled, run a worker first; non-2xx webhook responses are treated as failed and retried after cooldown.

```php
MrAdder\FilamentLogger\Facades\FilamentLogger::log(
    event: 'Refund Issued',
    description: 'Test refund alert',
    options: ['logName' => 'Billing', 'risk' => 'medium'],
);
```

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

### Customize table columns per panel

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Uses display hooks to remove the 'causer.name' column for partner panel. Branch on current panel ID.

```php
use Filament\Facades\Filament;
use MrAdder\FilamentLogger\Support\ActivityDisplay;

ActivityDisplay::tableColumnsUsing(function (array $columns): array {
    if (Filament::getCurrentPanel()?->getId() !== 'partner') {
        return $columns;
    }

    // Partners should not see who performed the action.
    return array_values(array_filter(
        $columns,
        fn ($column): bool => $column->getName() !== 'causer.name',
    ));
});
```

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

### Extend Spatie Activity model with team relationship

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Custom Activity model extending Spatie's base model, adding a team() BelongsTo relationship that Filament expects for tenant scoping.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Spatie\Activitylog\Models\Activity as BaseActivity;

class Activity extends BaseActivity
{
    public function team(): BelongsTo
    {
        return $this->belongsTo(Team::class);
    }
}
```

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

### Register ActivityPolicy gate

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Registers the ActivityPolicy for the Activity model. Must be done for the policy to take effect.

```php
Gate::policy(Activity::class, ActivityPolicy::class);
```

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

### Batch destructive activity alerts with digest

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Groups multiple deletion events into a single digest sent every 60 minutes. Reduces alert noise during bulk operations.

```php
'destructive_activity' => [
    'enabled' => true,
    'channels' => ['slack'],
    'events' => ['Deleted', 'Force Deleted'],
    'digest' => true,
    'digest_minutes' => 60,
    'digest_title' => ':count deletions in the last :window minutes',
],
```

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

### Configure export columns and chunk size

Source: https://github.com/mradder/filament-logger/blob/main/docs/activity-review.md

Customize the CSV/JSON export actions on the activity screen. Set 'enabled' to true, adjust 'chunk_size' (default 500), and list the columns to include in the export.

```php
'exports' => [
    'enabled' => true,
    'chunk_size' => 500,
    'columns' => [
        'id',
        'log_name',
        'event',
        'description',
        'subject_type',
        'subject_id',
        'causer_type',
        'causer_id',
        'causer_name',
        'risk',
        'tags',
        'properties',
        'created_at',
    ],
],
```

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

### Add a review tab for a custom log name

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Defines an activity filter tab labeled 'Billing' that shows logs with the 'Billing' log name for the last 30 days. Uses the 'activity_filters' configuration key.

```php
'activity_filters' => [
    'saved' => [
        'billing' => [
            'label' => 'Billing',
            'icon' => 'heroicon-o-banknotes',
            'log_names' => ['Billing'],
            'date_preset' => 'last_30_days',
        ],
    ],
],
```

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

### Rule channel selection with channels key

Source: https://github.com/mradder/filament-logger/blob/main/docs/custom-events.md

Each alert rule chooses its delivery channels with the `channels` key. If a rule references a channel that is not configured, that channel will not be able to deliver notifications for the rule.

```php
'alerts' => [
    'rules' => [
        'destructive_activity' => [
            'channels' => ['mail', 'slack', 'discord'],
        ],
    ],
],
```

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

### ActivityDisplay::causerLabelUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Registers a callback to customize the causer label. The callback receives the causer model and activity model, and returns a string or null to fall back to the default formatting. This is the supported way to support a user model without a `name` column.

```APIDOC
## ActivityDisplay::causerLabelUsing

### Description
Registers a callback to customize the causer label. The callback receives the causer model and activity model, and returns a string or null to fall back to the default formatting. This is the supported way to support a user model without a `name` column.

### Method
`ActivityDisplay::causerLabelUsing`

### Parameters
- **callback** (callable) - Required - A function that receives `(?Model $causer, Model $activity)` and returns `?string`.

### Example
```php
ActivityDisplay::causerLabelUsing(function (?Model $causer, Model $activity): ?string {
    return $causer?->full_name ?? 'System';
});
```
```

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

### Restrict visibility in policy

Source: https://github.com/mradder/filament-logger/blob/main/docs/recipes.md

Policy method viewAny that returns true only if the user is the owner of the current tenant, used when scoping is turned off.

```php
public function viewAny(User $user): bool
{
    return $user->isOwnerOf(Filament::getTenant());
}
```

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

### ActivityDisplay::tabsUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Registers a callback to modify the review tabs. The callback receives an array of tabs keyed by filter preset name and returns the modified array.

```APIDOC
## ActivityDisplay::tabsUsing

### Description
Registers a callback to modify the review tabs. The callback receives an array of tabs keyed by filter preset name and returns the modified array.

### Method
`ActivityDisplay::tabsUsing`

### Parameters
- **callback** (callable) - Required - A function that receives `array $tabs` and returns `array`.

### Example
```php
ActivityDisplay::tabsUsing(
    fn (array $tabs): array => collect($tabs)->except(['auth_anomalies'])->all(),
);
```
```

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

### Add a dashboard widget with widgetsUsing

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Add a custom widget to the dashboard using widgetsUsing. Returning an empty array hides the dashboard, equivalent to setting 'filament-logger.dashboard.enabled' to false.

```php
ActivityDisplay::widgetsUsing(function (array $widgets): array {
    $widgets[] = \App\Filament\Widgets\TenantActivityWidget::class;

    return $widgets;
});
```

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

### Register multiple alert rules with ActivityAlertRules::registerMany

Source: https://github.com/mradder/filament-logger/blob/main/docs/extending.md

Use this to register several alert rules at once. Each rule is merged over config rules, so registering under an existing key replaces that rule.

```php
ActivityAlertRules::registerMany([
    'plan_downgrade' => ['enabled' => true, 'channels' => ['mail']],
    'refund_issued' => ['enabled' => true, 'channels' => ['slack']],
]);
```

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

### Disable strict authorization

Source: https://github.com/mradder/filament-logger/blob/main/docs/security.md

Opt into legacy permissive behavior by setting 'strict' to false in the 'authorization' config.

```php
'authorization' => [
    'strict' => false,
],
```
Tokens:
Raw