README

Beautiful, modern UI for Spatie's Activity Log

Important: This package assumes you already have Spatie's Activity Log installed and configured in your Laravel application. It does not replace the logging package—only provides a powerful UI for viewing and analyzing the stored activities.

✨ Features

Dashboard Views

Table View: Sortable, paginated activity log with inline details modal
Timeline View: Chronological activity visualization grouped by date
Analytics Dashboard: Statistics, trends, heatmap, user profiles, and popular models

Filtering & Search

Advanced filter panel with date presets (today, last 7/30 days, this/last month, custom range)
Filter by event type, user/causer, subject model, and search across descriptions
Real-time filter suggestions

Saved Preferences

Save custom filter configurations as reusable views
Per-page display options (10, 25, 50, 100 per page)
Sort and pagination preferences

Analytics & Insights

Total, daily, weekly, and monthly activity counts
Active users count
Event type breakdown with percentages
Top active users and popular models
30-day activity trends chart
Activity heatmap (365 days)
User activity profiles with event breakdown and daily stats

Exports

Export to CSV (built-in)
Export to Excel (XLSX) (requires maatwebsite/excel)
Export to PDF (requires barryvdh/laravel-dompdf)
Export to JSON (built-in)
Queued exports for large datasets (>1000 records)
Automatic cleanup of old export files
Email notifications for queued exports

Authorization & Access

Authorization gate (viewActivityLogUi) auto-registered
Optional email/role-based access whitelisting
Configurable middleware stack
Middleware granular control

Performance & UX

Cached analytics (default 1 hour TTL, configurable)
Pagination powered by Laravel cache
No build step required (Bootstrap 5 + jQuery)
AJAX-powered filtering and data loading

🗒️ Requirements

PHP ≥ 8.4
Laravel 12 | 13 (auto-discovery enabled)
spatie/laravel-activitylog ≥ 5.0 (must be installed and configured)
- Table activity_log must exist with Spatie v5 schema (includes attribute_changes column)
- Activities must be logged via Spatie package before UI will display data

Optional Dependencies

For enhanced export functionality, install these packages:

Feature	Package	Version	Notes
Excel (XLSX)	`maatwebsite/excel`	^3.1	Falls back to CSV if not installed
PDF	`barryvdh/laravel-dompdf`	^2.0	Falls back to JSON if not installed
Queued Exports	Built-in with Laravel queues	-	Enable in config
Role-based Access	`spatie/laravel-permission`	^6.0	Optional, for role checks

Install export packages when needed:

composer require maatwebsite/excel barryvdh/laravel-dompdf

🚀 Installation

Install the package

 composer require ekoyanu99/laravel-activitylog-ui

(Optional) Publish resources

# Config file (config/activitylog-ui.php)
 php artisan vendor:publish --provider="ekoyanu99\ActivitylogUi\ActivitylogUiServiceProvider" --tag="activitylog-ui-config"

# Blade views (if you want to customise)
 php artisan vendor:publish --provider="ekoyanu99\ActivitylogUi\ActivitylogUiServiceProvider" --tag="activitylog-ui-views"

# Public assets (logo, js, css)
 php artisan vendor:publish --provider="ekoyanu99\ActivitylogUi\ActivitylogUiServiceProvider" --tag="activitylog-ui-assets"

Run migrations
Ensure you have already run Spatie’s migrations so the activity_log table exists:

php artisan vendor:publish --provider="Spatie\Activitylog\ActivitylogServiceProvider" --tag="activitylog-migrations"
php artisan migrate

Verify Spatie is logging activities

Make sure your models are using Spatie's activity logging:

use Spatie\Activitylog\Traits\LogsActivity;

class YourModel extends Model {
    use LogsActivity;
}

Visit the UI

Once installed, access the dashboard:

http://yourapp.local/activitylog-ui   # primary route
http://yourapp.local/ActivityLog      # legacy route (for backward compatibility)

Local package development (path repository)

If you are developing this package locally and want to test it in a Laravel app, add this to your host app composer.json:

{
  "repositories": [
    {
      "type": "path",
      "url": "../laravel-activity-ui",
      "options": {
        "symlink": true
      }
    }
  ]
}

Then install from your host app:

composer require ekoyanu99/laravel-activitylog-ui:@dev

This package also keeps legacy route compatibility for existing jQuery views:

/activitylog-ui (primary route)
/ActivityLog (legacy route alias)

Run Package Tests

From this package root:

composer install
composer test

This runs phpunit with phpunit.xml.dist config. Tests verify:

Named routes are registered
Export route supports GET & POST (for legacy jQuery flow)
Package views are discoverable

⚙️ Configuration Overview

A full configuration file is published to config/activitylog-ui.php. Below is a quick reference:

return [
    'route' => [
        'prefix' => 'activitylog-ui', // URL prefix
        'middleware' => null,         // Auto-detected or custom array
    ],

    'authorization' => [
        'enabled' => false,           // true => uses Gate / auth middleware
        'gate'    => 'viewActivityLogUi',
    ],

    'access' => [
        'allowed_users' => [],        // user email whitelist
        'allowed_roles' => [],        // role names (Spatie Permission, etc.)
    ],

    'features' => [
        'analytics'   => true,      // Show analytics dashboard tab
        'exports'     => true,      // Enable data exports
        'saved_views' => true,      // Allow saving filter configurations
    ],

    'exports' => [
        'enabled_formats' => ['csv', 'xlsx', 'pdf', 'json'],
        'max_records'     => 10000, // Max records per export (configurable via ACTIVITYLOG_MAX_EXPORT_RECORDS)
        'queue' => [
            'enabled'   => false,   // Queue exports >1000 records
            'threshold' => 1000,    // Records count threshold for queueing
            'queue_name'=> 'exports',
            'timeout'   => 300,     // 5 minutes
            'tries'     => 3,       // Retry failed exports 3 times
        ],
    ],
];

Refer to the inline comments in the file for every available option.

🔐 Authorization & Access Control

Gate: viewActivityLogUi is auto-registered (see ActivitylogUiServiceProvider). You may define it in your own code or rely on the package’s default email/role checks.
Toggle authentication: Set authorization.enabled to true to require login + gate.
Granular lists: access.allowed_users and access.allowed_roles let you open the UI to a subset of users—regardless of the gate.

📤 Exports

CSV & JSON work out-of-the-box.
Excel (XLSX) requires maatwebsite/excel – otherwise we gracefully fall back to CSV.
PDF requires barryvdh/laravel-dompdf – otherwise we fall back to JSON.
Large exports can be queued; enable exports.queue.enabled.

📈 Analytics Dashboard

Enable/disable with features.analytics. Caches stats for analytics.cache_duration seconds (default 1 h).

🔧 API Endpoints

Main Dashboard

GET /activitylog-ui/ – Main UI page

API Routes (JSON)

GET /activitylog-ui/api/activities – List activities with filters & pagination
GET /activitylog-ui/api/activities/{id} – Get activity detail
GET /activitylog-ui/api/activities/{id}/related – Related activities by subject
GET /activitylog-ui/api/filter-options – Available filters (events, users, subjects)
GET /activitylog-ui/api/event-types-styling – Event type icons & colors
GET /activitylog-ui/api/analytics – Dashboard stats and charts
GET /activitylog-ui/api/analytics/heatmap – Activity heatmap data
GET /activitylog-ui/api/users/{userId}/profile – User activity profile
GET /activitylog-ui/api/recent?hours=1&limit=50 – Recent activities
GET /activitylog-ui/api/search/suggestions?q=query – Search suggestions
GET /activitylog-ui/api/views – Saved filter views
POST /activitylog-ui/api/views – Save a filter view
DELETE /activitylog-ui/api/views – Delete a view
GET|POST /activitylog-ui/api/export – Export activities (supports legacy GET redirect)
GET /activitylog-ui/api/export/formats – Available export formats
GET /activitylog-ui/api/export/progress?job_id=xxx – Queued export progress
POST /activitylog-ui/api/export/cleanup – Cleanup old export files
GET /activitylog-ui/export/download?path=base64 – Download exported file

Legacy Routes (Backward Compatibility)

GET /ActivityLog/ – Main UI (redirects to /activitylog-ui)
GET /ActivityLog/api/* – API endpoints (same as above)

🤝 Contributing

PRs and issues are welcome! Please ensure:

All tests pass: composer test
Code follows PSR-12 style
ActivityLogList.blade.php remains unchanged (Bootstrap + jQuery base)

📝 License

The MIT License (MIT). See LICENSE for details.

ekoyanu99 / laravel-activitylog-ui

Maintainers

Package info

Statistics

Security