Laravel Action Tracker Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require devel8/laravel-action-tracker
   php artisan vendor:publish --provider="Devel8\ActionTracker\ActionTrackerServiceProvider" --tag="migrations"
   php artisan migrate
   

   • Publishes migrations to track actions (e.g., action_tracker_actions table).

2. Basic Usage Track an action on a model:

   use Devel8\ActionTracker\Facades\ActionTracker;
   
   $user = User::find(1);
   ActionTracker::track($user, 'deleted'); // Logs 'deleted' action for user ID 1
   

3. Viewing Actions

   $actions = ActionTracker::getActions($user); // Returns collection of actions
   // Or via relationship (if configured):
   $user->actions; // If using `hasMany` in User model
   

Implementation Patterns

1. Model Integration

• Automatic Tracking via Observers

  use Devel8\ActionTracker\Facades\ActionTracker;
  
  class UserObserver {
      public function deleted(User $user) {
          ActionTracker::track($user, 'deleted');
      }
  }
  

  Register in AppServiceProvider@boot():

  User::observe(UserObserver::class);
  

• Manual Tracking in Controllers

  public function destroy(User $user) {
      $user->delete();
      ActionTracker::track($user, 'deleted');
      return redirect()->route('users.index');
  }
  

2. Customizing Action Metadata

Attach metadata (e.g., IP, user agent) to actions:

ActionTracker::track($user, 'login', [
    'ip' => request()->ip(),
    'user_agent' => request()->userAgent(),
]);

3. Querying Actions

• Filter by Action Type

  $deletedActions = ActionTracker::getActions($user)->where('action', 'deleted');
  

• Scope in Eloquent Add a local scope to your Action model:

  public function scopeRecent($query, $minutes = 5) {
      return $query->where('created_at', '>=', now()->subMinutes($minutes));
  }
  

4. Notifications/Events

Extend with events (e.g., trigger notifications on critical actions):

use Devel8\ActionTracker\Events\ActionTracked;

ActionTracker::track($user, 'password_reset');
event(new ActionTracked($user, 'password_reset'));

Gotchas and Tips

Pitfalls

1. Missing Migrations

   • Forgetting to run php artisan migrate after publishing will break tracking.
   • Fix: Always publish migrations first.

2. Performance with Large Datasets

   • Tracking every model action (e.g., saved) can bloat the database.
   • Tip: Use selective tracking (e.g., only deleted, updated for sensitive fields).

3. Race Conditions

   • If multiple processes track actions simultaneously, ensure atomicity.
   • Tip: Use database transactions for critical bulk operations:

     DB::transaction(function () use ($user) {
         ActionTracker::track($user, 'bulk_update');
     });
     

Debugging

• Check Table Structure Verify action_tracker_actions has columns: model_type, model_id, action, metadata, created_at.

  • Fix: Re-run migrations if columns are missing.

• Log Missing Actions Add a debug middleware to log untracked actions:

  public function handle($request, Closure $next) {
      if (app()->environment('local')) {
          ActionTracker::track($request->user(), 'debug_request', [
              'path' => $request->path(),
          ]);
      }
      return $next($request);
  }
  

Extension Points

1. Custom Action Models Extend the Action model to add fields (e.g., actor_id):

   php artisan make:model ActionExtension --extend=Devel8\ActionTracker\Models\Action
   

   Update the migration and config.

2. Action Policies Restrict who can view/track actions:

   use Devel8\ActionTracker\Models\Action;
   
   class ActionPolicy {
       public function viewAny(User $user) {
           return $user->isAdmin();
       }
   }
   

3. Bulk Actions Optimize bulk inserts with insert instead of loops:

   ActionTracker::insert([
       ['model_type' => 'App\User', 'model_id' => 1, 'action' => 'updated'],
       ['model_type' => 'App\User', 'model_id' => 2, 'action' => 'updated'],
   ]);
   

Config Quirks

• Model Type Handling The package uses getMorphClass() for model_type. Ensure your models implement Morphable or override:

  public function getMorphClass() {
      return class_basename($this);
  }
  

• Metadata Serialization Metadata is JSON-encoded. Avoid circular references or large payloads:

  // Bad: Can cause serialization errors
  ActionTracker::track($user, 'viewed', ['data' => $user->posts]);
  
  // Good: Serialize manually
  ActionTracker::track($user, 'viewed', ['post_ids' => $user->posts->pluck('id')]);