Filamentboot Oss Laravel Package

Getting Started

This package is a satellite of filamentboot/filamentboot and ships on a lockstep version track — v0.5.3 contains no code changes and exists purely to align its version number with the main package. That single fact should shape how you onboard it.

1. Read the main package docs first. Because this repo has no independent changelog of substance, the authoritative source of behaviour, config keys, and upgrade notes is filamentboot/filamentboot. Treat this package's README as an index, not a manual.

2. Install both packages at the same version. In practice:

   composer require filamentboot/filamentboot:^0.5 filamentboot/<this-package>:^0.5
   

   Never let the two float independently — a ^0.4 here against a ^0.5 there is the most likely source of "class not found" or silently ignored config.

3. Check whether the package auto-discovers. Filament ecosystem packages usually register a service provider via extra.laravel.providers and expose a plugin object for panel registration. Confirm in vendor/filamentboot/<this-package>/composer.json before writing any manual registration.

4. Publish and diff config before touching it. Run php artisan vendor:publish --tag=<package>-config (verify the tag in the service provider) and commit the published file. Do not edit the vendor copy.

5. First use case. The realistic day-one win is enabling the plugin on a panel and letting the main package's defaults drive the UI:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(\Filamentboot\...\...Plugin::make());
   }
   

   Get a panel booting with defaults before customising anything. If the panel renders, the lockstep pairing is correct.

Implementation Patterns

Pin in lockstep, upgrade in lockstep. The healthiest pattern is a single version constant applied to the whole family, preferably via a Composer constraint shared across both requirements, or a composer bump step in CI that moves every filamentboot/* package together. A partial upgrade is the failure mode this release cadence is designed to prevent.

Register through the plugin object, not the service provider. Filament panels expect configuration to flow through the plugin's make()/configure() chain so that multi-panel apps can vary behaviour per panel. Keep provider-level editing to a minimum, since anything set globally in the provider will be invisible to readers of your PanelProvider and will surprise the next developer.

Treat config as the integration surface. For satellite packages like this, the durable API is usually the config array plus a handful of published views/translations. Prefer overriding config keys and re-publishing views over subclassing internals; subclassing couples you to a package that ships frequently and, by its own admission, sometimes ships nothing at all but a version bump.

Version-gated feature detection. If you support a range of 0.5.x releases, guard optional behaviour rather than assuming it exists:

if (class_exists(SomeNewClass::class)) { /* ... */ }

This is especially relevant given the lockstep scheme — a 0.5.0 and a 0.5.3 of this package are byte-identical in code, so any behavioural difference lives entirely in the main package.

CI hygiene. Add a matrix entry that installs filamentboot/filamentboot and this package at matching minor versions, and run composer update --prefer-lowest on the pair. Because this package's own code never changes within a patch line, a green build against the satellite tells you nothing — the build against the main package is what actually covers you.

Upgrade workflow for releases like this one. Since v0.5.3 changes no code, the correct response is: bump both constraints, run the test suite, and skim the main package's v0.5.3 notes for the real changes. Do not spend time bisecting this package — there is nothing to bisect.

Gotchas and Tips

• Empty release ≠ empty risk. This package's v0.5.3 is a no-op, but the main package's v0.5.3 may not be. Reading only this changelog and concluding "nothing changed" is the trap; always open the filamentboot/filamentboot release alongside it.
• Lockstep versioning can produce misleading semver expectations. A 0.5.2 → 0.5.3 bump here carries zero code delta, so you cannot infer the severity of the real change from this package's version number. Assess risk from the main package's diff, not this one's.
• Changelog noise. Expect many releases whose entire body reads "version alignment". Don't let that desensitise you into auto-merging Dependabot PRs for this package alone; the PR is only meaningful in combination with the main package bump.
• Config cache is the usual culprit. After bumping, run php artisan config:clear && php artisan filament:optimize-clear (or optimize:clear) before debugging. Most "my config change did nothing" reports in Filament packages trace back to a stale cached config in a local or CI environment.
• Asset and view publishing does not auto-refresh. If you published views or compiled assets from an earlier 0.5.x, re-publish and diff after upgrades even when the changelog says "no changes" — the main package may have altered a view this package extends. Keep published files in version control so the diff is visible.
• Debugging path. When something breaks, check composer show filamentboot/* first to confirm matched versions, then composer why-not filamentboot/filamentboot 0.5.3 to find the constraint holding you back. Only then look at code.
• Extension points. Rather than patching vendor files, look for the package's published config, Filament plugin hooks, or event/listener bindings. If the package offers none, file an issue upstream — and note that changes there will land in the main package, not here.
• Watch for the graduation point. A satellite package that only ever version-bumps is a candidate for absorption into the main package. If that consolidation happens, this package will likely be abandoned or archived — pin explicitly and keep an eye on the main package's composer requirements for signs of a merge.