Jokes Widget Laravel Package

Getting Started

The Filament Jokes Widget is a dashboard widget, not a full plugin with migrations or resources. Installation is therefore minimal:

1. Install the package:

   composer require <vendor>/filament-jokes-widget
   

   Confirm the exact package name and version constraints in the README / Packagist entry, and check the composer.json requirements for your Laravel and Filament versions.

2. Register the widget in your Filament panel provider:

   use Filament\Panel;
   use Vendor\FilamentJokesWidget\Widgets\JokesWidget;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->widgets([
               \Filament\Widgets\AccountWidget::class,
               JokesWidget::class,
           ]);
   }
   

3. Ensure your application locale is set. The widget uses the current locale to choose between Indonesian “bapak-bapak” jokes (id) and English dad jokes (en or fallback).

4. Visit your dashboard. You should see the joke card with a refresh button.

Where to look first:

• The package README for the exact widget class namespace and any publishable config or views.
• The widget class itself to confirm which locale source it reads (app()->getLocale() vs. the Filament panel locale).
• The package’s lang/ or translation files if you want to adjust labels.

First use case: Drop it on an internal admin dashboard for a bit of team morale. It is low-risk for internal tools; audit it before exposing it to customer-facing or regulated environments.

Implementation Patterns

Global dashboard widget

Register the widget once in the panel provider’s ->widgets([...]) array. This makes it available on the default dashboard for all users who can access the panel.

Per-page or conditional placement

If you do not want the joke on every dashboard, render it from a custom page or another widget’s Blade view:

@livewire(\Vendor\FilamentJokesWidget\Widgets\JokesWidget::class)

You can also gate visibility with Filament’s standard widget authorization:

public static function canView(): bool
{
    return auth()->user()?->isInternal() ?? false;
}

Check whether the package widget exposes canView(); if not, wrap it in your own subclass or render it conditionally in a custom page.

Locale strategy

• Use id for Indonesian jokes and en for English dad jokes.
• For a multilingual panel, set the locale per request or per panel so the widget picks the intended language.
• Verify whether the widget reads the application locale or the Filament panel locale. If it only reads app()->getLocale(), a panel-specific locale may not affect it unless your middleware sets the app locale.

Refresh and caching

The refresh button is a Livewire action. Every click can trigger a new outbound request for English jokes. If your dashboard is busy or the external API is slow, wrap or cache the fetch:

$joke = Cache::remember(
    'filament-jokes.'.app()->getLocale(),
    now()->addMinutes(10),
    fn () => /* package fetch call or your own HTTP client */,
);

If the package already caches, confirm the TTL and cache key in its source before adding another layer.

Testing

Fake the external API in tests to keep CI deterministic:

use Illuminate\Support\Facades\Http;
use Livewire\Livewire;

Http::fake([
    'icanhazdadjoke.com/*' => Http::response([
        'id' => 'test',
        'joke' => 'A fake dad joke.',
        'status' => 200,
    ], 200),
]);

Livewire::test(\Vendor\FilamentJokesWidget\Widgets\JokesWidget::class)
    ->assertSee('A fake dad joke.');

Also test the Indonesian path by setting the locale to id and asserting that no external HTTP call is made.

Gotchas and Tips

• External API dependency: English jokes depend on icanhazdadjoke.com. Dashboard rendering or refresh can fail or stall if the network is unavailable, the API is rate-limiting you, or egress is blocked in production. Check for timeouts and consider lazy-loading the widget so it does not block the initial dashboard render.
• User-Agent and rate limits: The icanhazdadjoke API is free but expects reasonable use and a descriptive User-Agent. If the package does not set one, you may see intermittent blocks. Verify the HTTP client configuration and consider setting a custom User-Agent via a bound client or a fork.
• Content safety: Dad jokes are generally benign, but external content is not curated for your audience. Indonesian “bapak-bapak” jokes are bundled locally and may include culturally specific humour. Audit before enabling on customer-facing dashboards, and confirm the package escapes output rather than rendering raw HTML.
• Locale mismatch: Only id is treated specially. Locales such as in (legacy Indonesian code), id_ID, or regional variants may fall through to English. Normalise the locale before rendering if you need Indonesian jokes for those codes.
• Refresh behaviour: Each refresh is a Livewire round trip and, for English, an API call. Add caching or throttle if many admins keep dashboards open. Do not assume the refresh button is free.
• Filament v4 vs. v5: The package claims compatibility with both. Register the widget using the panel provider API for your installed version, and avoid copying v5-specific registration examples into a v4 app.
• Duplicate registration: Register the widget either globally or on a specific page, not both, unless you intentionally want multiple instances. Duplicate Livewire components can cause confusing refresh behaviour.
• Extension points to inspect: Check whether the package publishes config, views, or translations. A custom Blade view is usually the cleanest way to restyle the card; a config flag is the cleanest way to disable the external API. If neither exists, subclass the widget and override the fetch or view rather than editing vendor files.
• CI flakiness: Any test that renders the widget without Http::fake() will hit the real API. Fake it globally in your test suite or disable the widget in tests.