Filament Simple Pages Laravel Package

Getting Started

• If you are on 0.x, stop and read the upgrade guide first. v1.0.0 ships a changed database schema, and the 0.x → 1.x path is documented in the README. Treat that guide as the entry point, not the install instructions.
• Fresh install: composer require the package, publish its config/migrations (php artisan vendor:publish --tag=...), then php artisan migrate.
• Register the plugin on your Filament panel in the panel provider (->plugin(YourPlugin::make())) — this is still the default path for existing panels.
• First use case to validate: load the registered page inside your panel, confirm it appears in navigation, and confirm authorization behaves as expected for a non-admin user. That single check exercises registration, routing, policies, and the schema change together.
• New in v1.0.0: the page can be registered outside a Filament panel. If you have a non-panel Laravel app, or want the page on a standalone route, start from that section of the README rather than wiring the plugin into a panel you don't have.

Implementation Patterns

• Panel-scoped registration (default). Keep plugin registration in each PanelProvider where the page belongs. Use ->plugin() conditionally on panel ID when you run multiple panels (e.g. admin vs app) so the page doesn't leak into every surface.
• Standalone registration (v1 feature). For apps without a Filament panel, or for a single route outside panel middleware, use the documented non-panel registration. This is the cleanest fit for "one admin-ish page in an otherwise plain Laravel app" — you avoid standing up a full panel just to host one page.
• Upgrade workflow for existing installs:
  1. Branch and snapshot the database.
  2. Read the README upgrade guide end to end before running migrations — schema changes in a major version often include data backfill steps that are not part of migrate.
  3. Re-publish config and views, then diff against your published copies; merge rather than overwrite.
  4. php artisan config:clear && php artisan route:clear && php artisan view:clear.
  5. Run the app's test suite plus one manual pass of the page as each relevant role.
• Deployment pipeline. Treat the v1 migration as a deploy-phase step, not an afterthought: run it before new code serves traffic, and gate the deploy on it succeeding. If you roll back code, verify the schema is still compatible.
• Testing. Use Filament's page/livewire test helpers against the registered page. Add at least one test for the non-panel registration path if you adopt it, since it bypasses panel middleware and is easy to break silently.

Gotchas and Tips

• The schema change is the headline risk. Major-version schema bumps are frequently not reversible via migrate:rollback alone, and may require a data migration the package can't infer. Back up first, and rehearse the upgrade on a production-like copy — not on a fresh local DB where the migration trivially passes.
• "Outside a Filament panel" means no panel middleware. You lose the panel's auth guard, tenant scoping, and middleware stack. If you use the new registration option, wire up authentication and authorization yourself; don't assume the page is protected because it was protected inside a panel.
• Clear caches after upgrading. Stale config and route caches cause the most confusing post-upgrade symptoms (page 404s, old config values). Clear all three before debugging anything else.
• Republish, then diff. Config and view stubs change in majors. Blindly re-publishing overwrites your customizations; blindly skipping means you miss new required keys. Always diff.
• Pin the version during rollout. Constrain to ^1.0 deliberately and avoid floating constraints across the upgrade window so you don't mix 0.x and 1.x assumptions between environments.
• Debugging order when the page misbehaves: (1) is the plugin registered on the panel you're actually hitting, (2) did migrations run, (3) are caches cleared, (4) is authorization rejecting you quietly. That sequence resolves most "page disappeared after upgrade" reports.
• Extension points. If you had subclassed or overridden the page in 0.x, re-verify those overrides against the v1 class — major releases commonly change method signatures and view names. The improved docs are the fastest way to confirm the current contract before you patch.