Laravel Activitylog Ui Laravel Package

Getting Started

Minimal Steps

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

   composer require muhammadsadeeq/laravel-activitylog-ui
   

3. Publish Config (optional but recommended for customization):

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

4. Access UI: Visit /activitylog-ui in your browser. No additional setup is required for basic functionality.

First Use Case

Debugging a User Action:

• Navigate to the Table View and filter by:
  • User: Select the user ID/email from the dropdown.
  • Event: Choose the relevant activity log event (e.g., deleted, updated).
  • Date Range: Use presets like "Last 24 Hours" or customize.
• Click an activity to see attribute changes (e.g., title from "Old Value" to "New Value") and custom properties (e.g., source_ip).
• Export the filtered results to CSV/JSON for further analysis.

Implementation Patterns

Core Workflows

1. Filtering and Analysis

• Dynamic Filtering: Use the filter panel (collapsible sidebar) to narrow down activities by:

  • Event Type: Dropdown of all registered log events (e.g., created, deleted).
  • User/Subject: Searchable dropdowns for causer_id (who performed the action) and subject_id (what was acted upon).
  • Date Range: Presets (Today, Last 7 Days) or custom ranges.
  • Search: Full-text search across description, properties, and attribute_changes.
  • Saved Views: Bookmark filters (e.g., "Failed Logins") via the star icon in the filter panel.
  • Pro Tip: Combine filters (e.g., event=deleted AND user=admin@example.com) for granular queries.

• Analytics Dashboard: Enable via config/activitylog-ui.php:

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

  View:

  • Event Frequency: Bar chart of activity types over time.
  • User Activity: Top users by event count.
  • Subject Types: Most acted-upon models (e.g., Post, User).
  • Use Case: Identify anomalies (e.g., sudden spike in deleted events).

2. Exporting Data

• Trigger Exports:
  • Click the export button (top-right) to download filtered activities.
  • Supported formats: CSV (default), XLSX (requires maatwebsite/excel), PDF (requires barryvdh/laravel-dompdf), JSON.
  • Example: Export all updated activities from the last month to XLSX for a compliance report.
• Queue Large Exports: Configure in config/activitylog-ui.php:

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

  • Exports > threshold are dispatched to a queue (default: exports). Useful for avoiding timeouts.

3. 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
  });
  

• Role/Email Whitelisting: Bypass gates for specific users/roles:

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

4. Customization

• Blade Views: Publish and override views:

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

  • Modify resources/views/vendor/activitylog-ui/layouts/app.blade.php to add headers/footers.
  • Extend resources/views/vendor/activitylog-ui/partials/activity-table.blade.php to add columns (e.g., ip_address).
• Tailwind CSS: Extend the default theme by publishing assets:

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

  Add custom CSS to resources/css/activitylog-ui.css:

  @layer components.activitylog-ui {
      .activitylog-ui .custom-badge {
          background-color: #10b981;
      }
  }
  

• JavaScript: Extend Alpine.js components by publishing assets and modifying: resources/js/activitylog-ui/filters.js (e.g., add a custom filter for status=pending).

5. Integration with Existing Code

• Log Custom Events: Use Spatie’s logger to generate activities:

  $user->logActivity('post.updated', $post);
  

  • The UI will automatically pick up these events in the filter dropdown.
• Add Metadata: Attach custom properties for richer filtering:

  $user->logActivity('post.updated', $post, [
      'source' => 'admin_panel',
      'ip_address' => request()->ip(),
  ]);
  

  • These appear in the Custom Properties panel and are searchable.

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 by this package.
   • Fix: Upgrade PHP or use v1.x of the package (if still needed).

3. Attribute Changes Column Missing:

   • Issue: Activities logged with laravel-activitylog <5.0 won’t show attribute_changes.
   • Fix: Use the legacy fallback in the UI (automatically handles properties.old/properties.attributes).

4. Export Failures:

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

     composer require maatwebsite/excel
     

   • Fallback: The UI gracefully degrades to CSV/JSON if dependencies are missing.

5. Authorization Conflicts:

   • Issue: Users with allowed_users access are still blocked by the gate.
   • Fix: Whitelist users or disable the gate (authorization.enabled = false).

6. Performance with Large Datasets:

   • Symptom: Slow loading or timeouts when filtering all activities.
   • Fix:
     • Use id sorting (default in v2+) instead of created_at.
     • Limit initial load with pagination (default: 50 records/page).
     • Queue exports for >10,000 records.

Debugging Tips

1. Check API Responses:

   • Open browser dev tools (Network tab) and inspect /activitylog-ui/api/activities for errors.
   • Look for 500 Internal Server Error responses to identify backend issues (e.g., missing columns).

2. Enable Debug Logging: Add to config/activitylog-ui.php:

   'debug' => [
       'enabled' => true,
       'log_level' => 'debug',
   ]
   

   Check storage/logs/laravel.log for detailed queries and errors.

3. Clear Cache:

   • Issue: Stale UI or filter states.
   • Fix:

     php artisan cache:clear
     php artisan view:clear
     

4. Timeline View Glitches:

   • Symptom: Activities not rendering in the timeline.
   • Fix: Ensure created_at is indexed in your activity_log table:

     Schema::table('activity_log', function (Blueprint $table) {
         $table->index('created_at');
     });
     

Extension Points

1. Add Custom Columns to Table View:

   • Override resources/views/vendor/activitylog-ui/partials/activity-table.blade.php:

     <th>IP Address</th>
     <!-- ... -->
     <td>{{ $activity->properties['ip_address'] ?? '-' }}</td>
     

2. Modify Filter Panel:

   • Extend the filter component by