Filament Dadjokes Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require phpsa/filament-dadjokes
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Phpsa\FilamentDadJokes\FilamentDadJokesServiceProvider"
   

2. Enable the Widget: Add the DadJokesWidget to your Filament dashboard by including it in your Dashboard class:

   use Phpsa\FilamentDadJokes\Widgets\DadJokesWidget;
   
   public function widgets(): array
   {
       return [
           DadJokesWidget::class,
       ];
   }
   

3. First Use Case: Visit your Filament admin panel. The widget will automatically display a random dad joke on the dashboard.

Implementation Patterns

Usage Patterns

1. Dashboard Integration:

   • Place the widget in the widgets() method of your Dashboard class.
   • Customize widget position by adjusting the sort property in the widget configuration:

     DadJokesWidget::make()
         ->sort(1) // Lower numbers appear first
     

2. Service Selection:

   • Toggle between joke sources (DadJokes or ChuckJokes) via config:

     'services' => [
         'dad-jokes' => true,
         'chuck-jokes' => false,
     ],
     

   • Defaults to dad-jokes if no config is provided.

3. Caching:

   • Set cache duration (in seconds) to reduce API calls:

     'cache' => 30, // Cache jokes for 30 seconds
     

   • Defaults to 5 seconds.

Workflows

1. Development Workflow:

   • Use php artisan config:clear to reset config changes during testing.
   • Monitor API calls with Laravel Debugbar or Postman to verify joke fetching.

2. Deployment Workflow:

   • Ensure the config is set in config/filament-dadjokes.php before deployment.
   • Test the widget in staging to confirm joke delivery and caching behavior.

Integration Tips

1. Custom Widget Styling: Extend the widget class to modify its appearance:

   use Phpsa\FilamentDadJokes\Widgets\DadJokesWidget;
   
   class CustomDadJokesWidget extends DadJokesWidget
   {
       protected static string $view = 'filament-dadjokes::custom-view';
   }
   

2. API Rate Limiting: If using ChuckJokes, be mindful of API rate limits (typically 5 jokes per minute). Adjust cache duration to mitigate this.

3. Localization: Override the joke display text in your language files (e.g., resources/lang/en/filament-dadjokes.php).

Gotchas and Tips

Pitfalls

1. API Dependencies:

   • The package relies on external APIs (icndb.com for DadJokes, api.chucknorris.io for ChuckJokes`). Downtime or rate limits may cause failures.
   • Fix: Implement a fallback mechanism or local joke storage if APIs are unreliable.

2. Caching Issues:

   • Aggressive caching (e.g., cache: 60) may result in stale jokes.
   • Fix: Use a lower cache duration (e.g., 5-10 seconds) or clear cache manually with php artisan cache:clear.

3. Config Overrides:

   • Forgetting to publish the config file may lead to default settings overriding your .env or manual config.
   • Fix: Always publish the config after installation:

     php artisan vendor:publish --provider="Phpsa\FilamentDadJokes\FilamentDadJokesServiceProvider"
     

4. Widget Visibility:

   • The widget may not appear if not added to the widgets() method of the Dashboard class.
   • Fix: Verify the widget is included in your dashboard configuration.

Debugging

1. API Errors:

   • Check Laravel logs (storage/logs/laravel.log) for API-related errors (e.g., cURL failures).
   • Enable debug mode in .env to surface issues:

     APP_DEBUG=true
     

2. Cached Jokes:

   • Clear the cache to test fresh joke retrieval:

     php artisan cache:clear
     

3. Widget Not Loading:

   • Ensure the widget is registered in config/filament.php under widgets:

     'widgets' => [
         \Phpsa\FilamentDadJokes\Widgets\DadJokesWidget::class,
     ],
     

Tips

1. Extending Functionality:

   • Override the getJoke() method in a custom widget class to fetch jokes from a local database or custom API:

     public function getJoke(): string
     {
         return DB::table('jokes')->value('text');
     }
     

2. Testing:

   • Mock the API responses in tests to avoid external dependencies:

     $this->mock(\Illuminate\Support\Facades\Http::class, function ($mock) {
         $mock->shouldReceive('get')
              ->with('https://api.icndb.com/jokes/random')
              ->andReturn(Http::response(['value' => ['joke' => 'Test joke']]));
     });
     

3. Performance:

   • For high-traffic dashboards, consider pre-fetching jokes during off-peak hours and storing them locally.

4. Custom Joke Sources:

   • Use the config/services.php to dynamically switch joke sources based on environment:

     'services' => env('DAD_JOKES_SERVICE') === 'chuck' ? ['chuck-jokes' => true] : ['dad-jokes' => true],