Filament Kanban Laravel Package

Getting Started

This package adds a help desk (tickets + a kanban-style board) to a Filament panel. For 2.0.1, start by confirming your panel is registered and the plugin is attached:

composer require jeffersongoncalves/filament-help-desk
php artisan filament:assets   # publishes/links the package stylesheet (2.0.1+)

// app/Providers/Filament/AdminPanelProvider.php
use JeffersonGoncalves\FilamentHelpDesk\HelpDeskPlugin;

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

Look first at:

1. vendor/jeffersongoncalves/filament-help-desk/config/ — publish with php artisan vendor:publish --tag="filament-help-desk-config" for table names, ticket statuses, priorities, and navigation labels.
2. The package migrations — run php artisan migrate before touching the UI; the board is empty without the tickets/columns tables.
3. The plugin class — it's where resources, pages, and (as of 2.0.1) the FilamentAsset stylesheet registration live. That's the file to read if the board looks wrong.

First use case: a support inbox. Create a ticket (subject, requester, priority, assignee), drag it across status columns on the board, and verify a status change persists. If the board renders as a flat unstyled list rather than columns, you're on < 2.0.1 or your assets aren't published — see Gotchas.

Implementation Patterns

Panel scoping. Register the plugin only on the panel that should own the help desk. Internally-facing admin panels and customer-facing panels usually want different ticket visibility; the cleanest pattern is two panels, with the plugin on both but authorization gates on the Ticket model deciding what each role sees.

Gate the resources, not the plugin. Rather than conditional plugin registration, keep the plugin registered and use Filament's canViewAny/canCreate on the generated resources (extend them in app/Filament/... and swap them in via ->resources([...]) on the plugin). This keeps policy logic in one place and survives package upgrades better than forking vendor resources.

Board as a triage surface, table as the audit surface. Day-to-day flow that works well: use the board page for status transitions and assignment, and the resource table for filtering by requester, date, or SLA breach. Don't try to make the board do filtering — kanban pages are poor at it.

Status columns as config, not code. Drive board columns from the published config (or a TicketStatus enum your app owns) so adding an "Escalated" column is a config change. If the package reads board columns from a DB table, seed it in a seeder so local/staging/production stay aligned.

Notifications and events. Hook ticket creation and status changes through model observers or the package's events rather than editing vendor code:

Ticket::observe(TicketObserver::class); // notify assignee, fan out to Slack, etc.

Multi-tenancy. If tickets belong to a customer/team, scope the plugin's queries via a global scope on the Ticket model or Filament's tenancy (->tenant(Team::class)), then verify the board respects it — kanban queries are the usual place tenancy leaks slip through.

Testing. Use Livewire::test() against the plugin's board page in a feature test that asserts a status transition. Keep one such test even if you don't test the rest — it catches asset/route regressions after upgrades.

Gotchas and Tips

The 2.0.1 stylesheet fix — and what it means for you. Before 2.0.1 the board shipped raw Tailwind utility classes in vendor views. Host apps never add vendor/ paths to their Tailwind content array, so production builds purged every board class and the board rendered as an unstyled flat list (issue #98). Fixed in 2.0.1 by shipping a prebuilt stylesheet registered through FilamentAsset. Consequences:

• Run php artisan filament:assets (and clear caches) after upgrading, or you'll keep the old broken asset in public/.
• If you added a workaround — a content entry pointing at ./vendor/jeffersongoncalves/filament-help-desk/resources/views/**/*.blade.php, or hand-copied classes into your own CSS — remove it. It's now dead weight and will mask future package styling changes.
• If you'd forked the vendor views to fix styling, diff against 2.0.1 before keeping the fork; upstream may now cover your case.

"Board is a flat list" triage order: (1) php artisan filament:assets, (2) hard-refresh / check the built CSS contains the package's classes, (3) confirm the plugin is registered on that panel, (4) check for a stale vendor:publish'd view overriding the package's.

Cache clears are not optional. After any upgrade: php artisan filament:clear-cached-components, php artisan view:clear, php artisan config:clear. Filament caches component registrations aggressively and stale caches produce confusing "class not found" or missing-page errors that look like broken installs.

Published views shadow vendor views. Once you vendor:publish views, package updates to those views silently stop applying. Publish only config and migrations unless you actively intend to maintain a fork; if you must publish views, note the package version in a comment at the top of each file.

Version pinning. This is a 2.x line with a styling/asset-registration change already in the patch stream. Pin to ^2.0.1 rather than ^2.0 — 2.0.0 has the purged-CSS bug in production builds and it will not reproduce in npm run dev, which makes it a nasty thing to discover after deploy.

Extension points to prefer over forking: plugin ->navigationGroup(), ->navigationLabel(), and resource overrides; model observers and events; config-published table/column names. Forking vendor resources is the highest-maintenance path and the one most likely to break on the next asset or Filament-minor change.

Filament version alignment. Verify the package's Filament constraint in its composer.json matches your panel's major version. Filament 3→4 asset registration and page APIs differ, and a mismatched pair typically surfaces as a blank page or a missing-stylesheet symptom that looks identical to the 2.0.1 bug.