Filament Rail Laravel Package

Getting Started

filament-rail adds a rail-style navigation element to Filament panels. v1.0.0 is the first stable release, so the API should now be treated as semver-stable — pin ^1.0 rather than tracking dev-main.

1. Install and confirm the version constraint. The 0.9.5 → 1.0.0 jump lands you on a stable line; check composer show koassi-akakpo/filament-rail resolves to 1.0.x and that your filament/filament constraint is in the range the package declares (this is the single most common install failure for Filament plugins).
2. Read the upgrade delta as a rename list, not a diff. The changelog link is the only artefact in the release notes, so open https://github.com/KoassiAkakpo/filament-rail/compare/v.0.9.5...v1.0.0 and scan specifically for: namespace moves (0.x plugins frequently relocate from Vendor\Package to Vendor\Package\Filament), config key renames, and removed fluent methods. Those are the three that break silently.
3. Look here first, in order: README.md → config/filament-rail.php (once published) → src/ for the plugin class and any Rail facade-ish entry point → resources/views/ for the Blade surface you can override → src/Http/Livewire or src/Pages for anything stateful.
4. First use case: register the plugin on a single non-production panel and verify the rail renders alongside the existing sidebar/topbar without layout conflict. A rail is a layout-level concern, so validate it visually against your densest resource page before wiring it into every panel.

If you are already on 0.9.5, the pragmatic first step is a throwaway upgrade branch: bump the constraint, run php artisan vendor:publish --tag=filament-rail-config --force and --tag=filament-rail-views --force into git, then diff the published files against your overrides. That diff is your upgrade guide when the release notes are just a compare URL.

Implementation Patterns

Panel-scoped registration. Register the plugin in app/Providers/Filament/AdminPanelProvider.php via ->plugin(RailPlugin::make()) rather than globally in a service provider. Filament plugins are panel-scoped by design; registering globally causes the rail to leak into auth pages and any secondary panels you didn't intend to touch.

Treat it as layout, not navigation source. The cleanest pattern is to let Filament keep owning navigation (resources, pages, clusters) and let the rail be a presentation/entry layer over it. If v1.0.0 exposes a ->navigation() or items API, prefer declaring fewer rail items than sidebar items — a rail is a glanceable surface, and cramming every resource into it is where these designs fall apart.

Config-first customisation. Publish the config file and make changes there for anything static (position, width, collapse behaviour, visibility predicate). Reserve view publishing for structural changes. Once you publish a view you own it forever, and every minor release can silently desync it — keep an overrides file listing exactly which package views you've forked.

Compose with custom Filament themes. If you have a compiled Tailwind theme in resources/css/filament/admin/theme.css, add the package's view path to your theme's @source directives. Filament plugin classes in v3+ ship their own CSS via FilamentAsset, and unpublished vendor views are not scanned by your theme build by default. Skipping this is the classic "rail renders unstyled" symptom.

Testing. Assert on the rendered panel rather than the plugin object: a Pest/Livewire test that hits /admin as an authenticated user and assertSee()s a rail marker catches registration, auth-gating, and asset-loading regressions in one shot. Add it before you upgrade next time.

Multi-panel setups. If the rail only belongs on the admin panel, keep it out of the app/user panel provider entirely. When you do want it in both, prefer a shared trait or base provider method over copy-pasting registration, so a 1.x config key rename is a one-line fix.

Gotchas and Tips

• The release notes are a compare link only. There is no migration guide for 0.9.5 → 1.0.0 in the notes. Read the compare diff yourself, and pin the exact version ("1.0.0") until you've done so — otherwise a future 1.0.1 can move under you while you're still discovering what 1.0.0 changed.
• Config cache. After publishing config or changing plugin options, php artisan config:clear and php artisan filament:optimize-clear. Filament panels cache component and asset registries aggressively; a "my change does nothing" report is almost always stale cache, not a bug.
• Asset registration. Run php artisan filament:assets (or filament:upgrade on 3.x) after the upgrade. Major versions commonly change asset IDs, and a stale manifest yields a rail that renders but lacks styles or JS.
• Namespaces moved. Very likely at 1.0.0. If your AdminPanelProvider or a custom page imports KoassiAkakpo\FilamentRail\... directly, re-check each import against src/ — IDE autocompletion will happily fail silently on a use that resolves to nothing until instantiation.
• Auth and visibility predicates. Verify the rail respects Filament's canAccessPanel() / canViewAny() gates. A layout component registered at panel level can bypass resource-level authorisation if it enumerates items itself — check whether the package honours shouldRegisterNavigation() and canAccess() on the resources it surfaces.
• Responsive behaviour is the risk area. Rails typically collapse to icons or hide on mobile. Test at sm/md breakpoints against a page with a long title and a page with breadcrumbs; these are where fixed-width layout chrome overlaps content.
• Dark mode and RTL. Toggle Filament's dark mode and, if you ship an RTL locale, check the rail flips. Filament ships RTL support; third-party layout components routinely don't.
• Extension points to prefer: visibility predicates and config flags over view overrides; a custom Filament theme over inline style attributes; and Filament's own getNavigationItems() overrides over reimplementing item lists. Anything you can express as config survives a minor bump; anything expressed as a forked Blade view does not.
• Exit hatch. Because this is layout chrome, keep it behind a config/env flag (FILAMENT_RAIL_ENABLED) for one release cycle. If 1.0.0 turns out to have a layout regression on your densest page, you flip a flag instead of hotfixing on a Friday.