Filament Announcements Laravel Package

Getting Started

1. Install via Composer: composer require hasanyagout/filament-announcement
2. Publish and run migrations: php artisan vendor:publish --tag="filament-announcement-migrations" then php artisan migrate
3. Optionally publish the config: php artisan vendor:publish --tag="filament-announcement-config"
4. Register the plugin in your Filament panel provider (e.g. AdminPanelProvider):

   ->plugins([
       \HasanYagout\FilamentAnnouncement\FilamentAnnouncementPlugin::make(),
   ])
   

5. Look first at the AnnouncementResource in your Filament admin panel — it provides CRUD for announcements. Create your first announcement there, then visit the panel dashboard to see it rendered (typically as a banner or widget, depending on config).

First use case: publish a maintenance notice or feature update to all admin users. Create an announcement with a title and body, set it active, and confirm it appears on the dashboard.

Implementation Patterns

• Basic CRUD via the resource: Use the built-in AnnouncementResource to create, edit, and delete announcements. Fields typically include title, body, active flag, and optional start/end dates.
• Scoping to active announcements: Query the Announcement model directly for custom display logic:

  Announcement::query()
      ->where('is_active', true)
      ->where(fn ($q) => $q->whereNull('starts_at')->orWhere('starts_at', '<=', now()))
      ->where(fn ($q) => $q->whereNull('ends_at')->orWhere('ends_at', '>=', now()))
      ->latest()
      ->get();
  

• Custom widget or banner: Create a Filament widget that fetches active announcements and renders them. Register the widget in your panel or dashboard. Use the package's model and scopes to avoid duplicating logic.
• Scheduling: Populate starts_at / ends_at (if provided by the package) to schedule announcements. Combine with a scheduled command or the widget's canView() method to avoid showing inactive items.
• Targeting by user or role: If the package supports audiences, use the resource to assign announcements to specific roles or users. For custom targeting, extend the model or add a global scope in a service provider.
• Integration with notifications: Listen for the Announcement model's created event to send a notification or broadcast an event. Keep the announcement itself as the source of truth.
• Overriding the resource: Extend AnnouncementResource and register your subclass in the plugin to add custom form fields, table columns, or policies.

Gotchas and Tips

• Removed deprecated methods (v1.0.3): If you previously called deprecated methods on the resource or its pages (e.g. custom actions or table helpers), they are now gone. Check your overrides and custom pages for calls to methods that no longer exist; replace them with the current API (often ->defaultSort('created_at', 'desc') for ordering).
• Table ordering fix: v1.0.3 fixes the default table order to descending. If you had a custom getTableQuery() or table() override that relied on the old ascending order, verify your expected ordering still holds.
• Migrations must run before the resource works: The resource depends on the announcements table. If you see "table not found" errors, publish and run migrations.
• Panel registration is required: The plugin does not auto-register. If announcements don't appear, confirm the plugin is listed in your panel provider's plugins() array and that you're using the correct panel.
• Config caching: After publishing the config, run php artisan config:clear in development. In production, remember php artisan config:cache.
• Custom resource overrides: When extending the resource, do not remove the parent's table() or form() methods entirely — call parent::table($table) / parent::form($form) first, then modify.
• Debugging visibility: If announcements aren't showing, check the is_active flag and any date constraints. Use ->toSql() on the query to inspect the generated SQL.
• Extension points: The model, resource, and plugin class are the primary extension points. Prefer publishing the config and overriding the resource over editing vendor files. For custom display logic, create a dedicated widget rather than modifying the package's views.
• Upgrade path: v1.0.3 is a patch release with no breaking changes beyond removed deprecations. If you were not using the deprecated methods, a composer update is safe. Always run your test suite after upgrading.