Getting Started

Minimal Setup

Prerequisite Check: Ensure Spatie's laravel-activitylog (v5+) is installed and configured with migrations run (php artisan migrate).

Install the UI:

composer require muhammadsadeeq/laravel-activitylog-ui

Publish Config (Optional):

php artisan vendor:publish --provider="MuhammadSadeeq\ActivitylogUi\ActivitylogUiServiceProvider" --tag="activitylog-ui-config"

Access the UI: Visit /activitylog-ui (default route). No additional setup is required for basic functionality.

First Use Case: Debugging User Activity

Navigate to the UI and use the search bar to filter by a user’s email (e.g., user@example.com).
Switch to the Timeline view to visualize sequential events for a specific model (e.g., Post).
Export filtered results to CSV for auditing by clicking the export button.

Implementation Patterns

Core Workflows

Filtering and Analysis:
- Use the filter panel to narrow down activities by:
  - Date ranges (presets like "Last 7 days" or custom ranges).
  - Event types (e.g., created, updated, deleted).
  - Users (via dropdown or search).
  - Subjects (models like Post, User).
  - Search term (covers description, properties, and attribute_changes).
- Saved Views: Bookmark frequent filters (e.g., "Failed Payments") via the "Save View" button.
Exporting Data:
- Trigger exports via the export dropdown (CSV/JSON by default; Excel/PDF require optional packages).
- For large datasets (>1000 records), enable queued exports in config/activitylog-ui.php:
```
'exports' => [
    'queue' => [
        'enabled' => true,
        'threshold' => 1000,
    ],
],
```

Authorization:

Restrict access via gates or role/email whitelists:

'authorization' => [
    'enabled' => true,
    'gate' => 'viewActivityLogUi',
],
'access' => [
    'allowed_roles' => ['admin', 'auditor'],
],

Customization:
- Override Views: Publish and modify Blade templates:
```
php artisan vendor:publish --tag="activitylog-ui-views"
```
- Extend Filters: Add custom filters by extending the ActivitylogUiServiceProvider and binding a new filter class to the container.
Analytics Dashboard:
- Enable the analytics tab to visualize:
  - Event frequency over time (charts).
  - Top users by activity count.
- Cache duration is configurable (analytics.cache_duration in seconds).

Integration Tips

Laravel Scout: Use the UI to debug search activity logs for scout:search events.
Event Dispatching: Log critical actions (e.g., Order::created) to correlate UI events with business logic:
```
event(new OrderCreated($order));
```
Real-Time Monitoring: Combine with Laravel Echo/Pusher to notify admins of high-activity events (e.g., deleted on sensitive models).

Gotchas and Tips

Pitfalls

Missing attribute_changes Column:
- If upgrading from Spatie v4, ensure your activity_log table includes the attribute_changes column (added in v5). Run:
```
php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php artisan migrate
```
- Legacy Fallback: The UI automatically falls back to properties.old/properties.attributes for unmigrated rows, but performance may degrade.
Authorization Conflicts:
- If using authorization.enabled = true, ensure the viewActivityLogUi gate is defined in your AuthServiceProvider:
```
Gate::define('viewActivityLogUi', function ($user) {
    return $user->hasRole(['admin', 'auditor']);
});
```
- Whitelist Override: The allowed_users/allowed_roles config bypasses gates entirely.
Export Failures:
- Excel/PDF Dependencies: Missing maatwebsite/excel or barryvdh/laravel-dompdf will silently fall back to CSV/JSON. Check the UI’s export dropdown for disabled options.
- Queue Stuck Jobs: Monitor the exports queue for large exports. Increase queue.threshold if jobs fail due to memory limits.
Performance with Large Datasets:
- Pagination: The UI uses Laravel’s cursor pagination (cursor()) for efficient loading. Avoid take() for initial queries.
- Indexing: Ensure activity_log has indexes on created_at, causer_id, and subject_type:
```
Schema::table('activity_log', function (Blueprint $table) {
    $table->index('created_at');
    $table->index('causer_id');
    $table->index('subject_type');
});
```
Timeline View Quirks:
- Null Properties: Activities with null properties may render empty in the timeline. Use the Table view for consistent data display.
- Timezone Issues: Ensure config/app.php sets a consistent timezone (e.g., 'timezone' => 'UTC').

Debugging Tips

API Responses: Check the Network tab in DevTools for failed API calls (e.g., /api/activitylog-ui/activities). Non-JSON responses (e.g., 500 errors) now show clear diagnostics.
Alpine.js Errors: Initialize filters in the init() method (fixed in v1.3.1). Clear Alpine state with:
```
Alpine.store('activitylogUi', { filters: {} });
```
Custom Properties: Filter out legacy keys (old, attributes) from the UI’s "Custom Properties" panel to avoid duplication.

Extension Points

Custom Filters:

Create a filter class (e.g., StatusFilter) extending MuhammadSadeeq\ActivitylogUi\Filters\Filter and bind it in the service provider:
```
$this->app->bind(
    'activitylog-ui.filter.status',
    StatusFilter::class
);
```

'filters' => [
    'custom' => [
        'status' => ['label' => 'Order Status', 'type' => 'select'],
    ],
],

Event-Specific Styling:
- Override the activitylog-ui/partials/event-badge.blade.php view to customize event badges (e.g., color-code by severity).

Analytics Customization:

Extend the AnalyticsService to add custom metrics (e.g., "Failed Logins"):

namespace App\Services;
use MuhammadSadeeq\ActivitylogUi\Services\AnalyticsService;

class CustomAnalyticsService extends AnalyticsService {
    public function failedLogins() { ... }
}

Bind it in the service provider and update the config:

'analytics' => [
    'service' => App\Services\CustomAnalyticsService::class,
],

Real-Time Updates:

Use Laravel Echo to push activity events to the UI:

Echo.channel('activity-log')
    .listen('ActivityLogged', (e) => {
        Alpine.store('activitylogUi').addActivity(e);
    });

Requires a custom event listener and channel setup.

Configuration Quirks

Route Prefix: Change the default /activitylog-ui prefix in config/activitylog-ui.php:
```
'route' => [
    'prefix' => 'admin/activity-logs',
],
```

Middleware: Add custom middleware to the route:

'route' => [
    'middleware' => ['auth', 'verified'],
],

Disabled Features: Toggle features like analytics or saved_views to reduce frontend complexity:
```
'features' => [
    'analytics' => env('APP_ENV') === 'production',
],
```


```markdown

Laravel Activitylog Ui Laravel Package