Filament Greeter Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require oriondevelops/filament-greeter
   

   Publish the config (if needed) with:

   php artisan vendor:publish --provider="Orion\FilamentGreeter\FilamentGreeterServiceProvider"
   

2. Register the Plugin: Add the plugin to your PanelProvider (e.g., AdminPanelProvider):

   return $panel
       ->plugins([
           \Orion\FilamentGreeter\GreeterPlugin::make(),
       ]);
   

3. First Use Case: Customize the greeting message in config/filament-greeter.php:

   'welcome_message' => 'Welcome back, {name}! Ready to conquer today?',
   

   Then trigger a cache refresh:

   php artisan filament:cache-reset
   

Implementation Patterns

Core Workflows

1. Dynamic Greetings: Override the welcome message dynamically via middleware or a service provider:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       \Orion\FilamentGreeter\Facades\FilamentGreeter::extendWelcomeMessage(
           fn ($user) => "Hello, {$user->first_name} {$user->last_name}!"
       );
   }
   

2. Custom Actions: Attach a custom action (e.g., "Profile Setup") to the greeter widget:

   GreeterPlugin::make()
       ->actions([
           Action::make('profile-setup')
               ->label('Complete Profile')
               ->url(fn () => route('filament.admin.resources.profiles.edit', auth()->user())),
       ]),
   

3. Conditional Rendering: Disable the greeter for specific users (e.g., admins):

   GreeterPlugin::make()
       ->visible(fn () => !auth()->user()->is_admin),
   

4. Avatar Customization: Override the avatar URL or disable it entirely:

   GreeterPlugin::make()
       ->avatarUrl(fn ($user) => $user->avatar_url ?? null)
       ->showAvatar(false),
   

Integration Tips

• Localization: Extend the config for multi-language support:

  'messages' => [
      'en' => 'Welcome back!',
      'es' => '¡Bienvenido de nuevo!',
  ],
  

  Use a language switcher to toggle dynamically.

• Theming: Match the greeter to your Filament theme by overriding CSS:

  /* resources/css/filament-greeter.css */
  .filament-greeter {
      background: #f0f0f0;
      border-radius: 8px;
  }
  

• Testing: Mock the greeter in unit tests:

  $this->actingAs($user)
       ->withGlobalFilamentGreeterPlugin(
           GreeterPlugin::make()
               ->welcomeMessage('Test Greeting')
       );
  

Gotchas and Tips

Pitfalls

1. Cache Dependencies:

   • Changes to the greeter config or plugin registration require a cache reset:

     php artisan filament:cache-reset
     

   • Debug Tip: Clear the view cache if the greeter doesn’t update:

     php artisan view:clear
     

2. Action Conflicts:

   • Custom actions must have unique keys to avoid duplication:

     Action::make('unique-key-here')->label('Action Name'),
     

3. Avatar Fallbacks:

   • Always provide a fallback avatar URL or disable the avatar if null:

     ->avatarUrl(fn ($user) => $user->avatar_url ?? asset('images/default-avatar.png')),
     

4. Middleware Interference:

   • If the greeter doesn’t render, check for middleware (e.g., auth) that might block the widget’s visibility.

Debugging

• Log User Data: Temporarily log the user object to debug dynamic values:

  \Orion\FilamentGreeter\Facades\FilamentGreeter::extendWelcomeMessage(
      fn ($user) => \Log::info($user->toArray()) ?: "Fallback"
  );
  

• Inspect Plugin Registration: Verify the plugin is registered in the correct PanelProvider and not overridden elsewhere.

Extension Points

1. Custom Views: Override the greeter blade template:

   // config/filament-greeter.php
   'view' => 'filament-greeter::custom-template',
   

   Publish the view first:

   php artisan vendor:publish --tag="filament-greeter-views"
   

2. Dynamic Data Fetching: Extend the greeter to fetch real-time data (e.g., notifications):

   GreeterPlugin::make()
       ->extend(function ($widget) {
           $widget->notifications = auth()->user()->unreadNotifications()->count();
       }),
   

   Then display it in your custom view:

   @if($widget->notifications > 0)
       <span class="badge">{{ $widget->notifications }}</span>
   @endif
   

3. Event Listeners: Trigger actions on greeter events (e.g., GreeterRendered):

   // app/Providers/EventServiceProvider.php
   public function boot()
   {
       \Orion\FilamentGreeter\Events\GreeterRendered::listen(function ($widget) {
           // Log or modify widget data here
       });
   }
   

4. Multi-Panel Support: Register the plugin in all PanelProviders if using multiple Filament panels:

   // AdminPanelProvider.php
   ->plugins([GreeterPlugin::make()]),
   
   // TenantPanelProvider.php
   ->plugins([GreeterPlugin::make()->welcomeMessage('Tenant Dashboard')]),