Laravel Activitylog Ui Laravel Package

Getting Started

Minimal Setup

1. Prerequisites: Ensure you have Spatie's laravel-activitylog installed and configured (v5+). Run its migrations:

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

2. Install the UI:

   composer require muhammadsadeeq/laravel-activitylog-ui
   

3. Publish config (optional):

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

4. Access the UI: Visit /activitylog-ui (default route). No additional routes or middleware are required unless configured.

First Use Case: Debugging User Activity

• Navigate to /activitylog-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 (e.g., created, updated, deleted).
• Click an activity to see attribute changes (e.g., name from "Old Name" to "New Name") in the modal.

Implementation Patterns

Core Workflows

1. Filtering and Searching

• Dynamic Filters: Use the left-hand panel to filter by:
  • Date ranges (presets like "Last 7 days" or custom ranges).
  • Events (e.g., created, updated).
  • Users (dropdown with autocomplete).
  • Subjects (models like Post, User).
  • Full-text search (covers description, properties, and attribute_changes).
• Saved Views: Click the star icon to save a filter combination (e.g., "Failed Payments"). Reopen via the Saved Views dropdown.

2. Exporting Data

• Trigger Exports: Click the export button (CSV/Excel/PDF/JSON).
  • CSV/JSON: No dependencies required.
  • Excel (XLSX): Requires maatwebsite/excel:

    composer require maatwebsite/excel
    

  • PDF: Requires barryvdh/laravel-dompdf:

    composer require barryvdh/laravel-dompdf
    

• Queue Large Exports: Enable in config/activitylog-ui.php:

  'exports' => [
      'queue' => [
          'enabled' => true,
          'threshold' => 1000, // Queue if >1000 records
      ],
  ],
  

3. Analytics Dashboard

• Enable in config:

  'features' => [
      'analytics' => true,
  ],
  

• View event frequency charts, user activity trends, and subject-based metrics.
• Cache duration configurable (default: 1 hour):

  'analytics' => [
      'cache_duration' => 3600, // 1 hour
  ],
  

4. Authorization

• Gate-Based Access: Enable in config:

  'authorization' => [
      'enabled' => true,
      'gate' => 'viewActivityLogUi',
  ],
  

  Define the gate in App\Providers\AuthServiceProvider:

  Gate::define('viewActivityLogUi', function ($user) {
      return $user->isAdmin(); // Custom logic
  });
  

• Whitelist Users/Roles: Bypass gates for specific users/roles:

  'access' => [
      'allowed_users' => ['admin@example.com'],
      'allowed_roles' => ['super-admin'],
  ],
  

5. Customizing Views

• Publish Views:

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

• Override:
  • resources/views/vendor/activitylog-ui/table.blade.php
  • resources/views/vendor/activitylog-ui/timeline.blade.php
• Extend with Alpine.js: Add custom logic to public/js/activitylog-ui.js (published via activitylog-ui-assets).

Integration Tips

1. Linking to ActivityLog UI from Your App

• Add a button in your admin panel:

  <a href="{{ route('activitylog-ui.index') }}" class="btn btn-primary">
      View Activity Log
  </a>
  

• Pass Pre-Filters: Use query parameters:

  route('activitylog-ui.index', [
      'event' => 'deleted',
      'user' => 'user@example.com',
  ]);
  

2. Extending Activity Log Data

• Add Custom Columns: Extend the Activity model or use a trait to add computed properties:

  namespace App\Models;
  
  use Spatie\Activitylog\LogOptions;
  use Spatie\Activitylog\Traits\LogsActivity;
  
  class Post extends Model
  {
      use LogsActivity;
  
      public function getActivitylogOptions(): LogOptions
      {
          return LogOptions::defaults()
              ->logOnly(['title', 'content', 'published_at'])
              ->logOnlyDirty()
              ->dontSubmitEmptyLogs();
      }
  
      // Custom property for UI
      public function getFormattedTitleAttribute()
      {
          return "Post #{$this->id}: {$this->title}";
      }
  }
  

• Display Custom Data: Override the table.blade.php view to include {{ $activity->subject->formatted_title }}.

3. Real-Time Updates

• Use Laravel Echo + Pusher to notify users of new activities:

  // resources/js/app.js
  import Echo from 'laravel-echo';
  
  window.Pusher = require('pusher-js');
  
  window.Echo = new Echo({
      broadcaster: 'pusher',
      key: process.env.MIX_PUSHER_APP_KEY,
  });
  
  Echo.channel('activity-log')
      .listen('ActivityLogged', (e) => {
          alert(`New activity: ${e.description}`);
      });
  

• Broadcast activities in your ActivityService:

  event(new ActivityLogged($activity));
  

4. Dark Mode Support

• The UI supports dark mode out-of-the-box. Force it via config:

  'ui' => [
      'dark_mode' => true,
  ],
  

• Or toggle via the UI’s theme switcher.

Gotchas and Tips

Pitfalls

1. Missing activity_log Table

   • Error: Table 'activity_log' doesn't exist.
   • Fix: Run Spatie’s migrations:

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

2. PHP 8.4+ Required

   • Error: Your PHP version (8.1) is not supported.
   • Fix: Upgrade PHP or use v1.x of the package (deprecated).

3. Spatie v5 Schema Mismatch

   • Error: Column 'attribute_changes' doesn't exist.
   • Fix: Run Spatie’s v5 migrations or use the legacy fallback in the UI (configurable in config/activitylog-ui.php).

4. Export Dependencies Missing

   • Error: Class 'Maatwebsite\Excel\Facades\Excel' not found.
   • Fix: Install the required package:

     composer require maatwebsite/excel
     

5. Alpine.js Conflicts

   • Error: Alpine.js not defined or TypeError in console.
   • Fix: Ensure Alpine is loaded before the UI’s JS:

     @vite(['resources/js/app.js', 'vendor/activitylog-ui/js/activitylog-ui.js'])
     

     Or publish assets:

     php artisan vendor:publish --tag="activitylog-ui-assets"
     

6. Authorization Bypass

   • Issue: Users can access /activitylog-ui without permissions.
   • Fix: Enable the gate in config:

     'authorization' => [
         'enabled' => true,
         'gate' => 'viewActivityLogUi',
     ],
     

7. Large Dataset Performance

   • Issue: Slow loading with >10,000 activities.
   • Fix:
     • Enable queued exports for large exports.
     • Add indexes to activity_log:

       Schema::table('activity_log', function (Blueprint $table) {
           $table->index('event');
           $table->index('causer_id');
           $table->index('subject_type');
           $table->index('subject_id');
       });
       

Debugging Tips

1. Check API Responses
   • Inspect /activitylog-ui/api/activities in browser dev