salmanalmajali / jokes-widget

v2.0.0 2026-11-12 14:30 UTC

Requires

• php: ^8.2
• filament/filament: ^4.0|^5.0
• guzzlehttp/guzzle: ^7.10
• spatie/laravel-package-tools: ^1.15.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.0
• nunomaduro/collision: ^8.0
• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-arch: ^3.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.26

MIT

• Salman Al Majali

• laravel
• widget
• filament
• SalmanAlmajali
• jokes-widget

Published on Packagist.org on 2026-11-12 14:31 UTC

README

Add a touch of fun and lightweight Filament PHP widget that brings "Dad Jokes" humor directly to your dashboard and make your Filament Dashboard tell a joke. This plugin is designed to add a bit of humor to the administrative experience by displaying jokes tailored to your application's language settings.

Key Features

• Automatic Localization:
  • Bahasa Indonesia: Displays a collection of iconic local "bapak-bapak" jokes. Collected from Candaan API Repository by Ardhi Putra
  • English: Dynamically fetches fresh dad jokes from the icanhazdadjoke.com API.
• Interactive Refresh: Includes a button to instantly swap jokes without reloading the page using Livewire.
• Filament V4 and V5 Ready: Optimized to run seamlessly on the latest version of Filament.

Installation

You can install the package via Composer:

composer require salmanalmajali/jokes-widget

(Optional) Publish the translation files if you wish to customize the widget text:

php artisan vendor:publish --tag="jokes-widget-translations"

Usage

Register the plugin in your Filament Panel Provider (typically AdminPanelProvider.php):

use SalmanAlmajali\JokesWidget\JokesWidgetPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            JokesWidgetPlugin::make(),
        ]);
}

Alternatively, you can register the widget directly:

use SalmanAlmajali\JokesWidget\JokesWidget;

public function panel(Panel $panel): Panel
{
    return $panel
        ->widgets([
            JokesWidget::class,
        ]);
}

Localization and Screenshoot

The widget automatically detects your application's locale:

• If the locale is set to id, the widget uses the local joke collection.
• or any other locale (default en), the widget fetches data from the external API.

Custom Jokes (Markdown)

Write your own jokes in a Markdown file. Every list item is one joke; indented lines continue it. Headings and paragraphs are ignored, and inline Markdown (**bold**, _italic_, links) is rendered. Raw HTML is escaped.

# Office jokes

- Why do programmers prefer dark mode? Because light attracts **bugs**.
- I told my boss I needed a raise.
  He said: "Have you tried turning it off and on again?"
1. Numbered lists work too.

Point the plugin at the file:

JokesWidgetPlugin::make()
    ->jokesFile(resource_path('jokes.md')),

Or use one file per locale (en_US falls back to en). Locales without a file keep the default behaviour above:

JokesWidgetPlugin::make()
    ->jokesFile([
        'id' => resource_path('jokes/id.md'),
        'en' => resource_path('jokes/en.md'),
    ]),

When a file is set for the current locale, the external API is not called.

Testing

Run the package tests using Pest:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Salman Al Majali
• Ardhi Putra
• All Contributors