Tiles Laravel Package

Getting Started

This release is a major-version bump (3.0.0) whose only stated change is Filament 5 support. Treat it as a platform-alignment release rather than a feature release: the plugin's public surface is likely unchanged, but its Filament version constraint has moved.

1. Check the version matrix first. Before touching code, read the package README/composer.json to confirm which line targets which Filament major. The practical rule: pin the package major that matches your Filament major, and don't mix them across projects.
2. Look at the service provider and plugin class. Filament plugins are almost always registered through a plugin object added to a PanelProvider. That file (and the package's config file, if it publishes one) is where day-to-day behaviour is configured — not in your own models or controllers.
3. First use case: upgrade a single non-critical panel to Filament 5 + package ^3.0, register the plugin in the panel provider, boot the panel, and exercise the main screen the package provides. That one loop (install → register → render the primary page/resource) is the fastest way to confirm compatibility before rolling out to other panels or apps.

Implementation Patterns

Register at the panel level, not globally. Add the plugin to the PanelProvider that owns the UI. If you run multiple panels (admin, tenant, customer), register per panel deliberately — a plugin registered globally will affect panels whose Filament version assumptions you haven't validated.

Pin the major, allow the minor. Use a constraint like ^3.0 against Filament 5, and commit the lockfile. In a monorepo or multi-app estate, keep a short compatibility table (app → Laravel version → Filament major → plugin major) so an upgrade in one place doesn't silently drag another app across a major boundary.

Upgrade in an isolated branch. The migration path is:

• bump Filament to 5 and the plugin to ^3.0 together in the same commit;
• composer update the pair, not the whole tree, so you can attribute failures;
• clear cached config/views/routes and republish any package assets;
• run the panel's test suite plus a manual smoke test of every screen the plugin touches.

Use Filament's testing helpers. Livewire/Filament component tests catch the majority of major-version breaks (changed method signatures, renamed schema/component classes) far faster than clicking through the UI. Even a handful of tests covering the plugin's primary page and form is worth the setup cost.

Keep overrides thin and isolated. If you customise views, themes, or extend the plugin's classes, centralise those overrides (a single theme CSS entry point, a small set of subclasses). Broad overrides are what make Filament major upgrades expensive; narrow ones mean the 3.0 bump is just a constraint change.

Roll out panel by panel. Because the change is version alignment, you can migrate one panel to F5 + plugin ^3.0 while others remain on the previous major, provided they don't share a single composer.json — if they do, treat it as one atomic upgrade.

Gotchas and Tips

• A major bump with one line of notes means the notes are incomplete. "Support Filament 5" says nothing about dropped support for older Filament majors. Verify in composer.json whether 3.0.0 still allows Filament 4; if it doesn't, this is a hard breaking change for anyone not yet on F5.
• Peer-plugin deadlock. The usual blocker isn't this package — it's other Filament plugins in the same panel that haven't shipped Filament 5 support. Resolve the whole set before bumping, or you'll bounce between conflicting constraints.
• Symptoms of a version mismatch are typically Class not found, "declaration must be compatible with" signature errors, or a panel that renders blank after boot. Check the Filament/plugin version pairing before debugging your own code.
• Stale caches after upgrade. Run php artisan optimize:clear (and filament:assets / asset publishing where applicable). A cached config or compiled view from the previous major can make a correct upgrade look broken.
• Published config drift. If the package publishes config or migrations, diff the new stub against your published copy before overwriting — vendor:publish --force will discard local customisation. Prefer copying new keys across manually.
• Extension points to prefer: the plugin object's fluent configuration methods and Filament's own hooks/macros. Prefer these over subclassing internals — internals are the most likely thing to shift between Filament majors.
• Test the upgrade path, not just a fresh install. Install ^3.0 cleanly in a scratch app to confirm it works at all, then do the in-place upgrade in your real app; the two fail differently.
• Watch the changelog for 3.0.x. A major that exists purely to track a framework release often gets rapid patch releases for missed compatibility fixes — pin to a specific patch you've verified rather than floating immediately.