Laravel Surveillance Ui Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies

   composer require neelkanthk/laravel-surveillance-ui
   composer require neelkanthk/laravel-surveillance
   

   Ensure laravel-surveillance is configured first (see its docs).

2. Publish Assets

   php artisan vendor:publish --provider="Neelkanth\SurveillanceUI\SurveillanceUIServiceProvider" --tag="public"
   php artisan vendor:publish --provider="Neelkanth\SurveillanceUI\SurveillanceUIServiceProvider" --tag="config"
   

   This publishes the UI assets (CSS/JS) and config file to public/vendor/surveillance-ui/ and config/surveillance-ui.php.

3. Add Middleware Register the UI middleware in app/Http/Kernel.php:

   'web' => [
       // ...
       \Neelkanth\SurveillanceUI\Middleware\SurveillanceUI::class,
   ],
   

   Or protect a specific route:

   Route::middleware(['web', \Neelkanth\SurveillanceUI\Middleware\SurveillanceUI::class])->group(function () {
       // Surveillance UI routes
   });
   

4. Access the UI Visit /surveillance-ui (or your configured path) to see the dashboard. Authenticate via Laravel’s default auth (e.g., auth:api or web middleware).

First Use Case: Viewing Surveillance Logs

• Navigate to the Logs tab to see real-time or historical surveillance events (e.g., blocked IPs, suspicious activity).
• Use filters (e.g., IP, User Agent, Timestamp) to narrow down logs.
• Click on a log entry to expand details (e.g., request payload, response, headers).

Where to Look First

• Config File: config/surveillance-ui.php (customize paths, middleware, or UI behavior).
• Blade Templates: resources/views/vendor/surveillance-ui/ (override default views if needed).
• Middleware: app/Http/Middleware/SurveillanceUI.php (extend logic for route protection).

Implementation Patterns

Workflows

1. Integrating with Existing Auth

• Use Laravel’s built-in auth (e.g., auth:api) alongside the UI middleware:

  Route::middleware(['auth:api', \Neelkanth\SurveillanceUI\Middleware\SurveillanceUI::class])->get('/surveillance', [SurveillanceController::class, 'index']);
  

• For admin-only access, combine with can:admin:

  Route::middleware(['auth', 'can:admin'])->group(function () {
      // Surveillance UI routes
  });
  

2. Customizing the Dashboard

• Override the default blade template:

  cp vendor/neelkanth/surveillance-ui/resources/views/vendor/surveillance-ui/dashboard.blade.php resources/views/vendor/surveillance-ui/
  

• Extend the layout with additional tabs or widgets:

  @extends('vendor.surveillance-ui.layout')
  @section('content')
      {{ parent::section('content') }}
      <div class="card">
          <h5>Custom Widget</h5>
          <!-- Your content -->
      </div>
  @endsection
  

3. Programmatic Access to Surveillance Data

• Use the underlying Surveillance facade to fetch logs in your controllers:

  use Neelkanth\Surveillance\Facades\Surveillance;
  
  $logs = Surveillance::logs()->latest()->take(100)->get();
  

• Pass data to the UI via a custom controller:

  public function customView(Request $request) {
      $data = Surveillance::logs()->where('ip', $request->ip)->get();
      return view('custom.surveillance-view', compact('data'));
  }
  

4. Real-Time Monitoring with Events

• Listen to Surveillance\Events\LogCreated to trigger actions (e.g., notifications):

  Surveillance::onLogCreated(function ($log) {
      // Send Slack/email alert
      event(new SurveillanceAlert($log));
  });
  

Integration Tips

• Laravel Scout Integration: If using Scout for search, extend the UI to include a search bar:

  $searchResults = Surveillance::logs()->search($query)->get();
  

• Laravel Echo/Pusher: Add real-time updates for new logs:

  Echo.channel('surveillance-logs')
      .listen('LogCreated', (log) => {
          // Update UI dynamically
      });
  

• API Endpoints: Expose surveillance data via API for third-party tools:

  Route::get('/api/surveillance/logs', function () {
      return Surveillance::logs()->latest()->paginate(20);
  });
  

Gotchas and Tips

Pitfalls

1. Middleware Order Matters

   • Place SurveillanceUI middleware after auth middleware to avoid infinite redirects:

     // Wrong: Redirect loop
     ['auth', \Neelkanth\SurveillanceUI\Middleware\SurveillanceUI::class]
     
     // Correct:
     ['web', \Neelkanth\SurveillanceUI\Middleware\SurveillanceUI::class]
     

2. Asset Paths in Production

   • Ensure public/vendor/surveillance-ui/ is symlinked or copied to public/:

     php artisan storage:link  # If using storage for assets
     

   • Clear cached views if assets aren’t loading:

     php artisan view:clear
     

3. Performance with Large Logs

   • Paginate logs in the UI config:

     'logs_per_page' => 50, // Default is 20
     

   • Add database indexes to surveillance_logs table for ip, user_id, and created_at.

4. CSRF Token Mismatch

   • If using API routes, ensure CSRF is disabled for the UI middleware:

     class SurveillanceUI extends Middleware {
         public function handle($request, Closure $next) {
             if ($request->is('api/*')) {
                 return $next($request);
             }
             return $next($request)->unless($request->is('surveillance-ui*'));
         }
     }
     

Debugging

1. Logs Not Appearing?

   • Verify laravel-surveillance is recording logs:

     php artisan surveillance:list
     

   • Check the surveillance_logs table directly in the database.

2. UI Styling Issues

   • Clear compiled assets:

     npm run dev  # or `npm run prod` for production
     

   • Override Bootstrap variables in resources/sass/app.scss if needed.

3. Permission Denied

   • Ensure the user has the view surveillance permission (if using Laravel’s gate):

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

Tips

1. Custom Log Fields

   • Extend the surveillance_logs table and hydrate custom fields:

     Surveillance::extend(function ($surveillance) {
         $surveillance->logCustomField = function ($request) {
             return $request->input('custom_field');
         };
     });
     

   • Display in the UI by overriding the log template.

2. IP Blocking Automation

   • Use the UI to trigger blocks programmatically:

     Surveillance::blockIp($ip, 'Suspicious activity detected');
     

3. Localization

   • Publish and translate language files:

     php artisan vendor:publish --tag=surveillance-ui-lang
     

   • Add translations to resources/lang/{locale}/surveillance-ui.php.

4. Testing

   • Mock surveillance logs in tests:

     Surveillance::fake()->log('test-event', ['key' => 'value']);
     

   • Assert UI visibility:

     $response = $this->actingAs($user)->get('/surveillance-ui');
     $response->assertSee('test-event');
     

5. Backup Strategy

   • Schedule log cleanup via a command:

     Surveillance::logs()->where('created_at', '<', now()->subDays(30))->delete();
     

   • Use Laravel’s scheduler:

     $schedule->command('surveillance:prune')->daily();