Filament World Clock Laravel Package

Getting Started

• Confirm your panel runs Filament ^5.3 before installing. This release hard-requires it in composer.json; on 5.0–5.2 Composer will either fail resolution or leave you on the previous plugin major.
• Install with composer require <vendor>/<package>:^3.0 and run php artisan filament:upgrade (or php artisan optimize:clear) to flush cached panel/route manifests.
• Look first at the package's service provider and any Page/Resource subclasses — the v3 change is entirely about the new PageConfiguration argument passed into Page::routes(), so custom pages that override routing are where you'll spend your time.
• First use case: register the plugin on a panel in your PanelProvider (->plugin(PackagePlugin::make())), boot the panel, and open the page it exposes. If it renders, your Filament version and route signatures line up.
• If you maintain a custom page extending the package's page class, re-check its routes() signature immediately — that's the one method this release touches indirectly.

Implementation Patterns

• Panel-scoped registration. Keep plugin registration inside the relevant PanelProvider rather than a global service provider, so multi-panel apps (admin vs. tenant portal) get independent configuration.
• Route customization. When overriding Page::routes(), accept the PageConfiguration parameter in the signature and pass it through to the parent. This is the pattern the ^5.3 bump exists to support; hard-coding your own route registration defeats the new configuration object.
• Slug and route key changes. Drive page slugs/paths from config rather than literals, then vary them per panel — useful when the same page must live at /admin/reports and /portal/reports.
• Composer constraint pinning. In application composer.json, pin filament/filament to a known-good minor (^5.3) alongside the plugin. Upgrading Filament independently of the plugin is the most common source of breakage in this ecosystem.
• CI matrix. Test against 5.3 plus the latest 5.x in your pipeline so the next minor Filament bump surfaces route-signature breaks before production.
• Upgrade workflows. For existing v2 installs: bump Filament first, run composer update "filament/*" in isolation, verify panels boot, then bump the plugin. Doing both in one composer update makes attribution of failures much harder.

Gotchas and Tips

• Hard version floor, not a soft hint. The ^5.3 requirement is a breaking change for anyone on Filament 5.0–5.2. Composer messages can look like a generic dependency conflict; check your Filament version before debugging the plugin itself.
• Cached routes and manifests. After upgrading, stale cached panel routes frequently produce "method not found" or missing-route errors. Always run php artisan filament:upgrade and php artisan route:clear before concluding the upgrade failed.
• Signature mismatch errors. If you see an argument-count or type error mentioning PageConfiguration, a custom page is overriding routes() with the old signature. Add the parameter and forward it to parent::routes(...).
• Lock file drift. If composer.lock pins Filament below 5.3, composer update <vendor>/<package> will refuse or silently keep the old plugin major. Update Filament explicitly in the same transaction.
• Downgrade path. Rolling back to the previous plugin major requires also rolling Filament back, which may not be possible if other packages have moved to 5.3. Snapshot the lock file before upgrading.
• Multi-panel route collisions. Overlapping slugs across panels are a recurring issue; verify each panel's route names with php artisan route:list --path=admin after changing page configuration.
• Extension point. Subclass the package's page and override getRouteName()/slug methods rather than editing vendor code — vendor changes are wiped on the next composer update.
• Watch upstream. The PageConfiguration parameter originates in filamentphp/filament#19225; follow that PR and subsequent Filament minors for further signature changes that will force another plugin major.