System Log Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require carcara/system-log
   

   Publish the migration and config:

   php artisan vendor:publish --provider="Carcara\SystemLog\SystemLogServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Carcara\SystemLog\SystemLogServiceProvider" --tag="config"
   

   Run the migration:

   php artisan migrate
   

2. Basic Configuration Edit config/system-log.php to define:

   • Logged routes (e.g., ['/admin/*']).
   • Excluded routes (e.g., ['/api/health']).
   • User model (default: App\Models\User).
   • IP column (default: ip_address).

3. First Use Case: Log All Admin Access Add middleware to app/Http/Kernel.php:

   'web' => [
       \Carcara\SystemLog\Middleware\LogAccess::class,
       // ... other middleware
   ],
   

   Now, every request to /admin/* will auto-log user IP, timestamp, and route.

Implementation Patterns

Core Workflows

1. Logging User Actions Manually log specific events (e.g., sensitive operations):

   use Carcara\SystemLog\Facades\SystemLog;
   
   SystemLog::log('user.id', 'action', ['metadata' => 'value']);
   

2. Customizing Log Fields Extend the Log model (app/Models/Log.php):

   namespace App\Models;
   use Carcara\SystemLog\Models\Log as BaseLog;
   
   class Log extends BaseLog {
       protected $casts = [
           'metadata' => 'array',
           'user_agent' => 'string',
       ];
   }
   

3. Filtering Logs Query logs via Eloquent:

   $logs = \App\Models\Log::where('user_id', auth()->id())
       ->where('action', 'delete')
       ->latest()
       ->get();
   

4. Integration with Events Listen for model events (e.g., Creating):

   use Carcara\SystemLog\Events\LogCreated;
   
   LogCreated::dispatch($log);
   

Advanced Patterns

• Dynamic Route Matching Use regex in config to log complex routes:

  'logged_routes' => [
      '^/admin/(users|products)/\d+$',
  ],
  

• Rate-Limiting Logs Combine with Laravel’s throttle middleware to prevent log spam:

  Route::middleware(['throttle:60,1', 'log'])->group(...);
  

Gotchas and Tips

Common Pitfalls

1. Middleware Order Matters Place LogAccess after auth middleware to avoid logging guest routes incorrectly.

   // Wrong: Logs guests.
   'web' => [LogAccess::class, Authenticate::class],
   
   // Correct: Skips guests.
   'web' => [Authenticate::class, LogAccess::class],
   

2. IP Address Issues

   • Localhost/Testing: Use 127.0.0.1 or ::1 in logs. Avoid null by ensuring Request::ip() works in tests.
   • Proxies: Configure trusted_proxies in AppServiceProvider if behind a load balancer:

     $this->app['request']->setTrustedProxies(['192.168.1.1']);
     

3. Performance

   • Bulk Logging: Avoid logging in loops. Batch actions:

     SystemLog::logBatch([
         ['user_id' => 1, 'action' => 'bulk_update'],
         ['user_id' => 2, 'action' => 'bulk_delete'],
     ]);
     

   • Queue Jobs: Offload logging to a queue for high-traffic routes:

     LogAccess::dispatch($request)->onQueue('logs');
     

Debugging Tips

• Check Logged Data Temporarily add a TAP listener in app/Providers/AppServiceProvider.php:

  public function boot() {
      \Carcara\SystemLog\Models\Log::created(fn ($log) => tap($log)->toArray());
  }
  

• Verify Middleware Test with php artisan route:list to confirm LogAccess is registered.

Extension Points

1. Custom Log Models Override the Log model to add fields (e.g., device_type):

   class Log extends BaseLog {
       protected $fillable = ['device_type'];
   }
   

   Update the migration accordingly.

2. Export Logs Add a scheduled command to export logs to CSV/Excel:

   use Carcara\SystemLog\Models\Log;
   use Illuminate\Support\Facades\Storage;
   
   class ExportLogsCommand extends Command {
       public function handle() {
           $logs = Log::all()->toArray();
           Storage::put('logs.csv', array_to_csv($logs));
       }
   }
   

3. Webhook Notifications Extend the LogCreated event to send alerts:

   LogCreated::listen(function ($log) {
       if ($log->action === 'password_reset') {
           Http::post('https://alerts.example.com', ['log' => $log]);
       }
   });