Filamentloginscreen Laravel Package

Getting Started

Treat this package as a view-swap for Filament's login page, not a full auth system. It gives you pre-built login layouts so you don't have to fork Filament's Login page class yourself.

1. Install into an app that already has a working Filament panel (v3 era — see Gotchas):

composer require solutionforest/filamentloginscreen

2. Publish what you need (tag names follow the package's README; the usual suspects):

php artisan vendor:publish --tag="filamentloginscreen-config"
php artisan vendor:publish --tag="filamentloginscreen-views"

3. Look first at two places: the published config file (config/filamentloginscreen.php or similarly named) to pick a design, and the published Blade views under resources/views/vendor/ to see what you're actually rendering.

4. First use case: swap the stock Filament login for a branded split-screen. Set the design key in config, add your logo/background, then log out and hit /admin/login. That's your feedback loop — the login page is a single route, so iterating is fast (php artisan view:clear between edits).

If your panel provider already overrides ->login(...) with a custom page class, resolve that conflict before doing anything else — the plugin won't render if Filament is pointed at a different page.

Implementation Patterns

Config-first, views-second. Start by selecting a bundled design via config. Only publish and fork the Blade view when you need structural changes (extra column, marketing copy, testimonial block). Forking early means you inherit maintenance burden for zero benefit.

Fork into the vendor view path, never into the package. Published views live at resources/views/vendor/{package}/... and Laravel's view resolution prefers them automatically. You get full control while keeping the package updatable.

Brand assets belong in public/, referenced via asset(). Backgrounds and logos hardcoded to /images/... break when the app is served from a subdirectory. Prefer asset('images/login-bg.jpg') and keep the asset names in config so non-devs can swap them.

Compose with Filament's own panel API rather than fighting it. ->brandLogo(), ->brandName(), ->colors(), ->darkMode() all still apply to the surrounding layout. Use them for colour and branding; use the plugin only for layout structure.

Add fields with render hooks, not forks. If you need "remember me" toggles, tenant selectors, or SSO buttons, a PanelsRenderHook::AUTH_LOGIN_FORM_BEFORE/AFTER hook is less brittle than editing the published view — hooks are stable API; view internals aren't.

Multi-panel apps: each panel resolves its own login page. If two panels need different looks, don't try to make one config serve both — publish two views and point each panel at its own page class extending the plugin's, or accept one shared design.

Smoke-test the route in CI. A trivial test that GETs the login route and asserts 200 catches the most common failure mode (view or asset missing after deploy):

it('renders the login screen', function () {
    $this->get('/admin/login')->assertOk();
});

Gotchas and Tips

• Version compatibility is the biggest risk. Last release was May 2024, squarely in the Filament v3 window. Check the composer.json constraint against your Filament version before installing; Filament v4 moved login page internals around and this package likely predates that. Pin the package and test upgrades deliberately.
• Config and view caches mask changes. After publishing or editing config/views in a cached environment, run php artisan config:clear && php artisan view:clear. Most "the design didn't change" reports are this.
• Publishing with --force overwrites your customisations. Never run publish commands in a deploy pipeline that targets these tags.
• Silent shadowing. If your PanelProvider calls ->login(SomePage::class), the plugin's page is ignored with no error. Verify with php artisan route:list | grep login and confirm which class handles it.
• Asset paths in bundled views may assume a root-domain install. Audit every asset() / url() call in the published Blade before shipping to a subdirectory or CDN-fronted deployment.
• Dark mode and small viewports are under-tested in small packages — check both. Login screens are the first thing users see on mobile.
• Accessibility regressions are common with custom designs: keep <label for> associations, don't remove focus rings, and preserve the autocomplete="email|current-password" attributes so password managers work.
• Extension points, in order of preference: config → published view → render hooks → your own page class extending the package's. Move down that list only when the tier above genuinely can't do it.
• If the package stalls, the escape hatch is cheap: copy the published view into your own App\Filament\Pages\Auth\Login returning that view, delete the dependency, and keep full ownership. For a 30-star package that's often the right long-term call.