Filament Announce Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rupadana/filament-announce
   php artisan make:notifications-table  # Laravel 11+
   php artisan migrate
   

2. Register the Plugin: Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Rupadana\FilamentAnnounce\FilamentAnnouncePlugin::make(),
           ]);
   }
   

3. First Use Case: Create an announcement via TALLY:

   php artisan make:filament-announce --name="Welcome Back" --message="New features are live!"
   

   Or manually via the Filament UI (accessible under the configured navigation group).

Implementation Patterns

Core Workflows

1. Creating Announcements:

   • Use the CLI for bulk creation or TALLY for one-off messages.
   • Leverage the Filament UI for manual entry (customizable via can_access middleware).

   // Programmatic creation (e.g., in a service)
   \Rupadana\FilamentAnnounce\Models\Announce::create([
       'title' => 'Breaking News',
       'message' => 'API updates scheduled for tomorrow.',
       'is_published' => true,
   ]);
   

2. Displaying Announcements:

   • Global Banner: Automatically renders in the Filament header if is_published = true.
   • Targeted Users: Use the user_id field to show announcements to specific users.
   • Conditional Logic: Extend the Announce model to add custom visibility rules (e.g., role-based):

     public function isVisibleTo(User $user)
     {
         return $user->hasRole('premium') && $this->is_published;
     }
     

3. Integration with Filament Pages:

   • Embed announcements in custom pages using the AnnounceResource:

     use Rupadana\FilamentAnnounce\Resources\AnnounceResource;
     
     public static function getPages(): array
     {
         return [
             'index' => Pages\ListAnnounces::route('/'),
             'create' => Pages\CreateAnnounce::route('/create'),
             // ...
         ];
     }
     

4. Scheduling:

   • Use Laravel’s schedules to auto-publish announcements:

     $schedule->call(function () {
         \Rupadana\FilamentAnnounce\Models\Announce::where('scheduled_at', now())
             ->update(['is_published' => true]);
     })->daily();
     

Advanced Patterns

• Localization: Publish views and override the blade template (resources/views/vendor/filament-announce/announce.blade.php) for multi-language support.
• API Endpoints: Expose announcements via a custom API resource:

  Route::get('/api/announcements', function () {
      return \Rupadana\FilamentAnnounce\Models\Announce::published()->get();
  });
  

• Webhooks: Trigger announcements via external events (e.g., Stripe subscription updates):

  event(new \Rupadana\FilamentAnnounce\Events\AnnounceCreated($announce));
  

Gotchas and Tips

Common Pitfalls

1. Navigation Group Misconfiguration:

   • If the announcement link doesn’t appear, verify the navigation.group in config/filament-announce.php matches your Filament panel’s sidebar group.
   • Fix: Set group to an existing sidebar group (e.g., 'content').

2. Permission Denied:

   • The can_access middleware defaults to super_admin. Override in config or extend the AnnouncePolicy:

     // app/Policies/AnnouncePolicy.php
     public function viewAny(User $user)
     {
         return $user->hasRole(['admin', 'editor']);
     }
     

3. Migration Conflicts:

   • Running notifications:table twice may cause errors. Delete the notifications table manually if needed.
   • Tip: Use --force with migrations cautiously; back up first.

4. Stale Cache:

   • Announcements may not update immediately due to Filament’s cache. Clear it:

     php artisan filament:cache-clear
     

Debugging Tips

• Log Announcement Visibility: Add a debug method to the Announce model:

  public function debugVisibility(User $user)
  {
      return [
          'is_published' => $this->is_published,
          'user_match' => $user->id === $this->user_id,
          'custom_rules' => $this->isVisibleTo($user),
      ];
  }
  

• SQL Queries: Enable Laravel’s query logging to inspect announcement retrieval:

  DB::enableQueryLog();
  $announces = \Rupadana\FilamentAnnounce\Models\Announce::published()->get();
  dd(DB::getQueryLog());
  

Extension Points

1. Custom Fields: Add fields to the announces table via a migration:

   Schema::table('announces', function (Blueprint $table) {
       $table->string('color')->default('#4CAF50');
       $table->boolean('is_urgent')->default(false);
   });
   

   Then extend the AnnounceResource to include these fields.

2. Event Listeners: Listen for announcement creation to trigger side effects (e.g., Slack notifications):

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Rupadana\FilamentAnnounce\Events\AnnounceCreated::class => [
           \App\Listeners\NotifySlack::class,
       ],
   ];
   

3. Testing: Use Filament’s testing helpers to assert announcement visibility:

   $this->actingAs($user)
       ->get('/admin/announces')
       ->assertSee('Welcome Back');
   

Configuration Quirks

• Default Sorting: Announcements are ordered by created_at DESC by default. Override in the AnnounceResource:

  public static function getSortableFields(): array
  {
      return [
          'priority' => fn (Announce $record) => $record->priority ?? 0,
      ];
  }
  

• View Publishing: Always publish views after installing the package to avoid missing template errors:

  php artisan vendor:publish --tag="filament-announce-views" --force