Filament Environment Indicator Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require pxlrbt/filament-environment-indicator
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Pxlrbt\FilamentEnvironmentIndicator\FilamentEnvironmentIndicatorServiceProvider" --tag="filament-environment-indicator-config"
   

2. Register the Widget Add the widget to your Filament dashboard in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->widgets([
               \Pxlrbt\FilamentEnvironmentIndicator\Widgets\EnvironmentIndicator::class,
           ]);
   }
   

3. First Use Case Place the widget in your Filament dashboard sidebar. It will automatically display the current environment (e.g., local, staging, production) with a color-coded badge.

Implementation Patterns

Customization

• Override Default Styling Extend the widget’s view (resources/views/vendor/filament-environment-indicator/widgets/environment-indicator.blade.php) or use CSS overrides in your Filament theme.

• Dynamic Environment Logic Modify the environment detection in config/filament-environment-indicator.php:

  'environments' => [
      'local' => ['color' => 'danger', 'label' => 'Local (Dev)'],
      'staging' => ['color' => 'warning', 'label' => 'Staging'],
      'production' => ['color' => 'success', 'label' => 'Production'],
  ],
  

  Or override the getEnvironment() method in a custom widget class.

• Conditional Visibility Hide the widget in production by extending the widget:

  class CustomEnvironmentIndicator extends EnvironmentIndicator
  {
      public static function canAccess(): bool
      {
          return app()->environment(['local', 'staging']);
      }
  }
  

Integration Workflows

• Pair with Filament Notifications Use the environment in notifications (e.g., show a warning in local):

  if (app()->environment('local')) {
      Notification::make()->warning()->title('Local Environment')->send();
  }
  

• Combine with Filament Spies Log environment-specific actions:

  FilamentSpies::spy('model.created', function ($model) {
      if (app()->environment('staging')) {
          Log::info("Staging: Created {$model->getMorphClass()}");
      }
  });
  

• Environment-Specific Widgets Dynamically load widgets based on the environment:

  ->widgets(fn () => [
      app()->environment('local') ? DebugBar::class : null,
      EnvironmentIndicator::class,
  ])
  

Gotchas and Tips

Pitfalls

• Caching Headaches If using Filament’s cache, clear it after changing the environment in config/filament.php:

  php artisan filament:cache-clear
  

• Environment Mismatch The widget uses Laravel’s app()->environment()—ensure your .env is correctly loaded (e.g., avoid .env.local conflicts).

• Widget Not Updating If the environment badge doesn’t refresh, check:

  • The widget is registered in AdminPanelProvider.
  • No JavaScript errors (inspect the Filament dashboard console).

Debugging Tips

• Log the Environment Add a temporary check in routes/web.php:

  Route::get('/env', function () {
      return ['env' => app()->environment()];
  });
  

• Override Environment Detection For testing, mock the environment in phpunit.xml:

  <env name="APP_ENV" value="testing"/>
  

Extension Points

• Add Custom Environments Extend the config or widget to support custom environments (e.g., demo):

  'environments' => [
      'demo' => ['color' => 'info', 'label' => 'Demo Server'],
  ],
  

• Localize Labels Override the widget’s __() method for translations:

  public function getEnvironmentLabel(): string
  {
      return __('filament-environment-indicator::widgets/environment-indicator.labels.' . $this->environment);
  }
  

• Hook into Filament Events Trigger actions based on the environment:

  Filament::registerWidget(
      EnvironmentIndicator::class,
      fn (EnvironmentIndicator $widget) => $widget->environment === 'local'
          ? $widget->setColor('dark')
          : null
  );