jeffersongoncalves/helpdeskkitv4
A Laravel/PHP helpdesk toolkit for adding support ticket and customer service features to your application, with tools for managing tickets, conversations, and support workflows in one package.
helpdeskkitv4 is a Filament v4 helpdesk kit for Laravel — a panel plus the ticket/agent/category domain, wired so you can drop it into a fresh Laravel app and start triaging tickets.
As of 4.14.0, "getting started" changed shape. The release moves user/admin models, resources, and the login flow out to the author's separate user/admin packages. If you are installing fresh, expect to pull in more than one package:
composer require jeffersongoncalves/helpdeskkitv4:^4.14 (plus the user/admin packages it now depends on — check the generated composer.json diff rather than assuming).php artisan vendor:publish --tag=helpdesk-config / --tag=helpdesk-migrations (verify tag names with php artisan vendor:publish and pick interactively first time).php artisan migrate then the seeder for demo tickets/agents.PanelProvider (or use the shipped provider if the kit is a full starter app).php artisan filament:assets and build your frontend assets./admin (or whatever path the panel registers) as the seeded admin.Where to look first: the panel provider (navigation, tenancy, plugin registration), then the Tickets resource — it is the centre of gravity and the file you will fork most often. Read the config file before writing any code; most "how do I change X" questions are answered by config, not by overriding classes.
First use case: a single-department internal helpdesk. Ticket list → assign agent → status transitions → comments. Get that loop working end-to-end on defaults before touching roles or SLAs.
Extend, don't vendor-edit. With models and resources now living in upstream packages, subclass the resource and model and register your subclass in the panel. Anything you patch inside vendor/ disappears at the next composer update — which is the exact failure mode 4.14.0 will trigger for people who edited the in-tree User model or login page.
Resource extension via the fluent API. Override form(), table(), and getPages() on a subclassed resource, calling parent:: and then adjusting. For light touch-ups prefer Filament's ->modifyForm() style hooks if available in your version over wholesale copies.
Ticket lifecycle as state machine. Do not scatter status logic across actions. Centralise transitions (open → pending → resolved → closed) in one service or a TicketStatus enum with canTransitionTo(), and have notification/audit listeners hang off model events. This keeps Filament actions thin and makes tests possible without the panel.
Agents and assignment. Treat "agent" as a role/scoping concern, not a separate model. With the user/admin split, the agent is an admin-package user with helpdesk-side permissions — implement via policies (TicketPolicy, TicketCommentPolicy) and a Gate::before for super-admins. Register policies in your app's AuthServiceProvider, not in the package.
Multitenancy / departments. If you need department isolation, use Filament's panel tenancy (->tenant(Department::class)) and scope the Ticket query by department_id through a global scope. Retrofitting tenancy later is painful, so decide before writing resources.
Notifications and queues. Ticket-created / comment-added notifications should be queued mailables dispatched from a listener, never from inside a Filament action closure. That keeps request latency flat as ticket volume grows and makes retries safe.
Integration surface. For external intake (email-to-ticket, Slack, monitoring alerts), do not POST into the Filament routes. Create tickets through the model/service layer behind an API route, then let a TicketCreated event fan out to notifications and assignment. The panel becomes a consumer of the domain, which is the right direction.
Upgrade rhythm. Because the kit tracks Filament releases closely (this release is literally "bump Filament to v4.14.0"), pin the kit and Filament together in composer.json and upgrade them in the same PR. Also align your CI to PHP 8.4 — the release adds static analysis on 8.4, so that is the version the package is actually validated against.
The 4.14.0 change is a likely breaking change, not a version bump. "Use user/admin packages for models, resources and login" means:
App\Models\User may no longer be the helpdesk's user model — imports, relationships ($ticket->agent), and factory references need checking.LoginResponse, redirect logic, 2FA) now lives in the admin package. Your overrides will silently stop applying.Migrate by diffing your published files against 4.13.4, not by re-publishing over them blindly.
Stale caches after upgrade. Run php artisan optimize:clear, php artisan filament:clear-cached-components and re-run filament:assets. Filament caches component discovery aggressively; a "class not found" after a bump is usually this, not a genuine missing class.
Migration ordering. Package migrations typically use loadMigrationsFrom and carry timestamps that may sort before your own users table migration after the user/admin split. If migrate:fresh fails with an FK error, publish and rename the offending migration rather than disabling FKs.
Permissions are not free. The kit ships the scaffolding, not your access model. Without explicit policies, agents can usually see each other's tickets. Verify as a non-admin agent before you ship — this is the single most common helpdesk bug.
Debugging the panel. php artisan about plus /admin route listing (php artisan route:list | grep admin) tells you fast whether the panel registered at all. For action-level misbehaviour, ->dd() / ->dump() inside a Filament action is more informative than a dump in the model.
Extension points to prefer, in order: config file → panel plugin registration → resource/model subclass → service binding via container → patch. Anything at step 5 will break on the next release.
CI hygiene is now packaged for you. Dependabot and test-workflow standardisation in this release only affects the upstream repo — do not copy their workflows into your application expecting them to run, and do not read the dependabot noise as a signal of application-level change. The two entries that matter for you are the Filament bump and the user/admin extraction; the rest is housekeeping.
Watch the PHP 8.4 requirement creep. Static analysis on 8.4 does not force you onto it, but the maintainer is no longer validating older minors in CI. Plan the upgrade before a future release makes it mandatory mid-sprint.
Pin the minor version in production. Given the pace of Filament bumps here, ^4.14.0 risks surprise upgrades. Lock to 4.14.* and review changelogs on your schedule.
How can I help you explore Laravel packages today?