Arkhe Watcher Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation Run composer require adhocrat-io/arkhe-watcher and execute php artisan arkhe:watcher:install. This handles config, migrations, and UI integration automatically.

2. Prerequisites Check Ensure your project meets requirements:

   • PHP 8.3+
   • adhocrat-io/arkhe-main ^3.2
   • Livewire 4 + Flux 2 (included in Arkhè Main)

3. First Use Case Access the dashboard at /administration/watcher to monitor:

   • Requests (timing, status, payload)
   • Exceptions (stack traces, context)
   • Database queries (duration, SQL)
   • Queued jobs (status, duration)
   • Scheduled tasks (execution logs)
   • Logs and mails (with metadata)

Implementation Patterns

Core Workflow

1. Automatic Instrumentation The package hooks into Laravel’s core events (e.g., Illuminate\Http\Kernel::handle) and queues (e.g., job.processed) without manual setup. Example: No need to wrap DB::query()—queries are auto-captured.

2. Flux UI Integration Uses Arkhè Main’s Flux 2 dashboard for a reactive, collapsible UI.

   • Collapsible Groups: The Watcher menu auto-registers into Arkhè’s navigation.
   • Real-Time Updates: Leverages Livewire for dynamic filtering (e.g., time ranges, status codes).

3. Configuration Key settings in config/watcher.php:

   'enabled' => env('WATCHER_ENABLED', true), // Toggle globally
   'max_entries' => 1000, // Retention limit
   'ignored_exceptions' => [\Symfony\Component\HttpKernel\Exception\HttpException::class], // Exclude noise
   

4. Customization

   • Extend Entry Types: Publish the package’s migrations and config, then add custom columns to watcher_entries (e.g., user_agent for requests).
   • Filtering: Use Flux’s built-in filters or add Livewire properties to the WatcherController:

     public $statusFilter = 'success';
     protected $queryString = ['statusFilter'];
     

5. Permissions The installer grants view-watcher to root/administrator roles. Extend via Arkhè’s role system:

   // app/Providers/ArkheServiceProvider.php
   Arkhe::role('developer')->givePermission('view-watcher');
   

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Query Logging: Disable for high-traffic apps by setting 'log_queries' => false in config.
   • Entry Retention: Monitor watcher_entries size; adjust max_entries or add a scheduled cleanup:

     // app/Console/Commands/CleanWatcherEntries.php
     use Illuminate\Support\Facades\DB;
     DB::table('watcher_entries')->where('created_at', '<', now()->subDays(30))->delete();
     

2. Migration Conflicts

   • If manually altering watcher_entries, run php artisan arkhe:watcher:install --force to republish migrations.
   • Backup the table before schema changes.

3. Flux/Livewire Quirks

   • Stale UI: Clear cache (php artisan view:clear) if the Watcher menu doesn’t appear.
   • Livewire Props: Ensure public properties in WatcherController are marked with protected $queryString for URL persistence.

4. Exception Ignoring

   • Overzealous ignored_exceptions may hide critical errors. Test with:

     'ignored_exceptions' => [
         \Symfony\Component\HttpKernel\Exception\HttpException::class,
         // Except 500s
         !\Symfony\Component\HttpKernel\Exception\HttpException::class => function ($e) {
             return $e->getStatusCode() !== 500;
         },
     ],
     

Debugging Tips

1. Log Inspection Check storage/logs/laravel.log for Watcher-related errors (e.g., missing Arkhè Main dependencies).

2. Entry Debugging Dump raw entries via Tinker:

   php artisan tinker
   >>> \App\Models\WatcherEntry::latest()->first()->toArray();
   

3. UI Debugging

   • Flux Issues: Verify resources/css/app.css includes @source from the installer.
   • Livewire Errors: Check browser console for Livewire or Flux warnings.

Extension Points

1. Custom Entry Types Extend the WatcherEntry model (published in app/Models/WatcherEntry.php after installation):

   // Add a custom column
   public function setCustomAttribute($key, $value) {
       $this->attributes[$key] = $value;
   }
   

2. Event Hooks Listen for watcher.entry.created to process entries post-save:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Adhocrat\Watcher\Events\EntryCreated::class => [
           \App\Listeners\ProcessWatcherEntry::class,
       ],
   ];
   

3. Dashboard Widgets Add custom Flux widgets to the Watcher page by extending the WatcherController:

   // app/Http/Livewire/WatcherController.php
   public function mount() {
       $this->customWidget = new \App\Widgets\QueryDurationWidget();
   }