Filament No Connection Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require marjose123/filament-no-connection
   

   Run this in your Laravel project to add the package.

2. Service Provider Registration: The package auto-discovery will handle this, but ensure FilamentNoConnectionServiceProvider is registered in config/app.php under providers if not using auto-discovery.

3. First Use Case:

   • Check for Server Connection: The package automatically detects if the server loses connection (e.g., database, API, or external service failures) and displays a user-friendly alert in Filament panels.
   • No Additional Code Needed: By default, it integrates with Filament’s layout and shows an alert when a critical connection issue is detected. Test by simulating a connection failure (e.g., disable your database temporarily).

Where to Look First

• Configuration: Check config/filament-no-connection.php (published via php artisan vendor:publish --tag="filament-no-connection-config").
• Views: Published views are located in resources/views/vendor/filament-no-connection/. Customize these if you need to alter the alert appearance.
• Service Provider: Review FilamentNoConnectionServiceProvider to understand how connection checks are hooked into Filament’s lifecycle.

Implementation Patterns

Usage Patterns

1. Basic Integration:

   • The package passively monitors connections (e.g., database, HTTP clients) and triggers alerts when failures occur. No manual intervention is required for standard use.
   • Example workflow:

     // In a Filament resource or page, trigger a manual check (if needed):
     use MarJose123\FilamentNoConnection\Facades\FilamentNoConnection;
     
     public function mount()
     {
         FilamentNoConnection::checkConnections(); // Force a check (optional)
     }
     

2. Custom Connection Checks:

   • Extend the package to monitor additional connections (e.g., third-party APIs, queues). Override the ConnectionChecker class or bind a custom checker in the service provider:

     $this->app->bind(
         \MarJose123\FilamentNoConnection\Contracts\ConnectionChecker::class,
         \App\Services\CustomConnectionChecker::class
     );
     

3. Alert Customization:

   • Publish the views and modify resources/views/vendor/filament-no-connection/alert.blade.php to change the alert message, styling, or behavior.
   • Dynamically pass data to the alert:

     FilamentNoConnection::setAlertData(['error' => 'Custom error message']);
     

4. Conditional Alerts:

   • Disable alerts for specific routes or panels by configuring the ignored_routes or ignored_panels in the config file:

     'ignored_routes' => [
         'filament/admin/pages/dashboard',
     ],
     

Workflows

1. Debugging Connection Issues:

   • Use the package to surface connection errors to end-users while logging detailed errors for developers. Example:

     // In AppServiceProvider's boot method:
     FilamentNoConnection::setLogger(\Log::channel('single'));
     

2. Graceful Degradation:

   • Combine with Laravel’s try-catch blocks to handle failures gracefully. Example:

     try {
         DB::connection()->getPdo();
     } catch (\Exception $e) {
         FilamentNoConnection::triggerAlert('Database unavailable');
     }
     

3. Testing:

   • Simulate connection failures in tests:

     $this->partialMock(DB::class, 'connection')->shouldReceive('getPdo')->andThrow(new \Exception('Test failure'));
     $this->get('/filament/admin')->assertSee('No connection');
     

Integration Tips

• Filament Panels: The package works seamlessly with Filament’s layout system. Alerts appear in the top-right corner by default.
• Localization: Support multiple languages by publishing the language files and extending them:

  php artisan vendor:publish --tag="filament-no-connection-lang"
  

• Performance: Connection checks are lightweight and run asynchronously where possible. Avoid adding heavy checks to critical paths.

Gotchas and Tips

Pitfalls

1. False Positives:

   • The package may trigger alerts for transient issues (e.g., slow database queries). Configure config/filament-no-connection.php to adjust sensitivity:

     'retries' => 3, // Number of retries before showing an alert
     'retry_delay' => 5, // Delay in seconds between retries
     

2. Ignored Routes Misconfiguration:

   • Accidentally ignoring critical routes can hide important alerts. Double-check the ignored_routes and ignored_panels arrays in the config.

3. Overriding Views Incorrectly:

   • If you publish and modify views but the changes don’t reflect, clear the view cache:

     php artisan view:clear
     

4. Database Connection Checks:

   • The package checks the default database connection by default. To monitor specific connections, bind a custom ConnectionChecker as shown in the Implementation Patterns section.

5. Filament Version Compatibility:

   • Ensure your Filament version is compatible with the package. Check the package’s composer.json for supported versions.

Debugging

1. Log Connection Checks:

   • Enable debug mode in the config to log connection checks:

     'debug' => env('APP_DEBUG', false),
     

   • Check logs in storage/logs/laravel.log for detailed connection check results.

2. Manual Alert Triggering:

   • Force an alert for testing:

     FilamentNoConnection::triggerAlert('Test alert', 'error');
     

3. Check for Conflicts:

   • If alerts don’t appear, verify that no other package or middleware is interfering with Filament’s layout rendering.

Tips

1. Custom Alert Icons:

   • Use Filament’s icon system to customize alert icons. Modify the published view:

     <x-filament::icon icon="heroicon-o-exclamation-circle" class="mr-2" />
     

2. Alert Dismissal:

   • Allow users to dismiss alerts temporarily by adding a "Dismiss" button to the alert view and storing dismissed alerts in the session:

     if (session()->has('dismissed_alerts')) {
         $dismissed = session('dismissed_alerts');
     }
     

3. Multi-Tenant Environments:

   • For multi-tenant apps, scope connection checks to the current tenant’s connections. Override the ConnectionChecker to include tenant-specific logic.

4. Performance Monitoring:

   • Combine with Laravel Telescope or similar tools to monitor connection check performance:

     Telescope::monitor(\MarJose123\FilamentNoConnection\Events\ConnectionCheckFailed::class);
     

5. Extending for APIs:

   • Use the package’s events to notify API clients of connection issues. Listen to ConnectionCheckFailed:

     \MarJose123\FilamentNoConnection\Events\ConnectionCheckFailed::class => function () {
         // Send a webhook or broadcast the event
     },