Create Your First FilamentPHP v5 Plugin

One of the best ways to learn how Filament plugins work is by building something small and useful.
In this tutorial we’re going to create a basic FilamentPHP v5 plugin that reads Laravel’s environment settings and displays a warning banner whenever the application is running in a development environment.

The plugin itself is intentionally simple, but it demonstrates most of the building blocks you’ll use when creating more advanced Filament plugins later.

What We’ll Build

Our finished plugin will:

• Read the APP_ENV value from Laravel
• Detect local and development environments
• Display a warning banner when development mode is active
• Load views through a package service provider
• Provide a reusable starting point for future plugins

Plugin Folder Structure

Create the following package structure:

filament-dev-banner/
│
├── composer.json
├── README.md
│
├── src/
│   ├── DevBannerPlugin.php
│   └── Providers/
│       └── DevBannerServiceProvider.php
│
├── resources/
│   └── views/
│       └── banner.blade.php
│
└── config/
    └── dev-banner.php

This structure follows the same conventions used by Laravel packages and Filament plugins.

Create composer.json

Every package starts with Composer metadata.

{
    "name": "kodesmart/filament-dev-banner",
    "description": "Filament Development Environment Banner",
    "type": "library",

    "autoload": {
        "psr-4": {
            "KodeSmart\\DevBanner\\": "src/"
        }
    },

    "extra": {
        "laravel": {
            "providers": [
                "KodeSmart\\DevBanner\\Providers\\DevBannerServiceProvider"
            ]
        }
    }
}

The PSR-4 autoloader tells Composer where your classes live and Laravel automatically discovers the service provider.

Create the Service Provider

The service provider loads package resources.

<?php

namespace KodeSmart\DevBanner\Providers;

use Illuminate\Support\ServiceProvider;

class DevBannerServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->loadViewsFrom(
            __DIR__.'/../../resources/views',
            'dev-banner'
        );

        $this->publishes([
            __DIR__.'/../../config/dev-banner.php'
                => config_path('dev-banner.php'),
        ], 'dev-banner-config');
    }
}

This allows your plugin to expose Blade templates and publish configuration files into the host application.

Create the Plugin Class

Now we create the main Filament plugin.

<?php

namespace KodeSmart\DevBanner;

use Filament\Contracts\Plugin;
use Filament\Panel;

class DevBannerPlugin implements Plugin
{
    public function getId(): string
    {
        return 'dev-banner';
    }

    public function register(Panel $panel): void
    {
        //
    }

    public function boot(Panel $panel): void
    {
        view()->share(
            'showDevBanner',
            app()->environment([
                'local',
                'development'
            ])
        );
    }

    public static function make(): static
    {
        return app(static::class);
    }
}

Creating the Banner View

Create the file:

resources/views/banner.blade.php

Then add:

@if($showDevBanner)

<div class="dev-banner">
    ⚠ DEVELOPMENT ENVIRONMENT DETECTED
</div>

<style>
.dev-banner{
    background:#dc2626;
    color:#fff;
    padding:12px;
    text-align:center;
    font-weight:bold;
    position:relative;
    z-index:9999;
}
</style>

@endif

This banner only appears when the plugin detects a development environment.

Understanding APP_ENV

Laravel uses the APP_ENV variable inside your .env file.

APP_ENV=local

or

APP_ENV=development

Typical values include:

APP_ENV=local
APP_ENV=development
APP_ENV=staging
APP_ENV=production

Our plugin only displays the warning banner when APP_ENV matches either local or development.

Optional Configuration File

Let’s make the plugin customizable.

<?php

return [

    'enabled' => true,

    'environments' => [
        'local',
        'development',
    ],

    'message' => '⚠ DEVELOPMENT ENVIRONMENT DETECTED',

];

Now anyone using your package can customize it without modifying source code.

Registering the Plugin

Open your Filament panel provider and register the plugin.

use KodeSmart\DevBanner\DevBannerPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            DevBannerPlugin::make()
        );
}

Once registered, the plugin becomes part of your Filament application lifecycle.

Testing the Plugin

Set the environment:

APP_ENV=local

Refresh your Filament panel.

You should see:

⚠ DEVELOPMENT ENVIRONMENT DETECTED

Switch back to:

APP_ENV=production

The banner should disappear.

Next Steps

This plugin is intentionally simple, but now you have a reusable foundation.

Some possible improvements include:

• Custom colors per environment
• Display current Git branch
• Hostname and server information
• Dismissible alerts
• Admin-only visibility
• Position controls
• Dark mode support
• Custom icons and branding

Final Thoughts

The goal of this tutorial wasn’t the banner itself.

The real objective was understanding how a Filament plugin is structured, how Laravel packages work, and how Filament integrates with them.

Once you’re comfortable with this architecture you’ll be ready to build widgets, resources, custom components, navigation extensions and complete open-source Filament packages.

Download ZIP