Starter Kit Easy Laravel Package

Getting Started

This kit is a Filament layer that pulls in a curated set of packages (the quick-action dock, anselmokossa/filament-sentinel, mike-bronner/laravel-model-caching), publishes their views/translations, and serves its own copies of some front-end bundles from public/js/kit/. It also ships its own test suite under tests/Kit/, which doubles as the upgrade safety net.

Minimal path to first value:

1. Install the package and run the kit's install/publish command (the counterpart to kit:update), then php artisan migrate if Sentinel's tables aren't already in place.
2. Put a dock on a Filament panel. Register it in the panel provider and point it at the kit's served script rather than the vendor's asset — that is the whole point of DockDeAtalhos::servirScriptCorrigido(). Copying the vendor's quick-action-dock.js directly reintroduces the viewport bug fixed in v0.51.2.
3. Open a panel page in a desktop Chrome window and confirm the bottom-center dock stays put. Resize the window and trigger a Livewire round-trip (poll a widget, submit a form) — those are the two repaint triggers that used to push it off-screen.

Where to look first:

• public/js/kit/ — the served bundles. Read them, never edit them.
• wikis/specs/ — the kit keeps a spec per fix; wikis/specs/fix/dock-altura-do-viewport/ explains the v0.51.2 correction end to end.
• tests/Kit/ — your regression harness, including the PSR-4 fixture check added in this release.

Implementation Patterns

Dock registration. Register the dock once per panel in the panel provider and let the kit serve the script. The kit's patched bundle measures viewport height with documentElement.clientHeight instead of window.innerHeight; the width measurement was already clientWidth, so the fix is symmetric and covers positioning, the menu's opening direction, and first paint. You get all of that for free as long as the kit's script is the one on the page.

Upgrade workflow. This is the pattern worth internalizing:

composer update
php artisan kit:update        # refreshes public/js/kit/ and republishes Sentinel views/translations
php artisan test --testsuite=<kit suite>

Run the kit suite after composer update of the dock package specifically — it detects a stale public/js/kit/quick-action-dock.js and prints the command that regenerates it. Treat the suite as a gate, not an afterthought.

Deployment. public/js/kit/ is application-served static content. Make sure it is committed (or at least emitted by your build) and actually present in the deployed artifact. A directory that exists locally but is excluded from the release tarball means production keeps serving last month's script while your tests pass on your machine. Bump your asset version / clear the CDN cache after kit:update so browsers pick up the new bundle.

Sentinel 403s. v0.51.3's Sentinel 1.3.0 makes the 403 page say when the user does hold the page permission and the refusal came from somewhere else (policy, tenancy, middleware). That turns the page into a triage tool: a support ticket saying "it says I'm not allowed" now distinguishes "genuinely lacks the permission" from "permission granted, blocked elsewhere."

Model caching. mike-bronner/laravel-model-caching 13.2.0 is in the stack; use it behind read-heavy Filament tables and dashboard widgets. Nothing in this release changes its config, so existing Cacheable traits keep working.

Gotchas and Tips

• The served script is a fork. public/js/kit/quick-action-dock.js is the vendor bundle with one measurement swapped. After any composer update of hoceineel/filament-quick-action-dock, the copy is stale — the kit suite flags it with the regeneration command. Never hand-edit it; your edit dies at the next regeneration.
• Symptom recognition. The dock "appears then disappears a few seconds later" on desktop Chrome is this bug. Moving the button by hand only masks it, because every resize and every Livewire poll repositions it. If you see it post-upgrade, open devtools and compare window.innerHeight with document.documentElement.clientHeight — a gap (e.g. 867 vs 780) means you're still loading the unpatched bundle.
• Check the network tab first. Confirm the page requests js/kit/quick-action-dock.js and not the vendor path. A custom FilamentAsset::register() or a copied blade view can silently bypass servirScriptCorrigido().
• Published Sentinel views are raw upstream copies, deliberately unedited. Keep your customizations in your own views or in the Sentinel config that drives those views, not in the published files — a republish will overwrite them. The release notes declare this as debt: those raw copies may be dropped in a future version, at which point the package serves its own.
• PSR-4 warnings are gone (#170). If composer install --optimize-autoloader still emits does not comply with psr-4, the offending classes are yours: the kit now ships tests/Kit/FixturesComNamespaceTest.php, which fails on any named class declaration in tests/ that lacks a namespace or violates PSR-4. That test is a lint you get for free.
• No migration, no config change for v0.51.2. The only action item is refreshing public/js/kit/ via kit:update and redeploying the asset.
• Don't strip the published Sentinel files to "clean up." Removing them changes what the kit installs, and kit:update will not delete them from projects that already ran it — you'd end up with divergent installs across your environments.