Laravel Polymorphic Settings Filament Laravel Package

Technical Evaluation

Architecture fit

• sitesource/laravel-polymorphic-settings-filament is a thin adapter between the core polymorphic settings store and Filament's form layer. Its job is narrow: mount from the settings store, render fields, persist on save. That is the right shape — the version-specific surface stays in the adapter rather than leaking into the settings core.
• The v0.2.0 design change is a template-method inversion: the base class no longer declares form(), so the subclass supplies the version-appropriate signature and Filament's existing form discovery picks it up. This is what makes one package work across three majors, but it moves the version-specific contract into consumer code. The package is now version-agnostic; our subclasses are not.
• Auto-detection at runtime with zero consumer configuration is a strong ergonomic choice and decouples package upgrades from Filament upgrades.

Integration feasibility

• composer require sitesource/laravel-polymorphic-settings-filament with no config, no service provider wiring described, no published assets. Integration cost is effectively one line plus whatever subclasses we already own.
• Requires a host on Laravel 12/13, PHP 8.3–8.5, and any of Filament 3.x/4.x/5.x. Only one Filament major can be installed per project, so "auto-detection" is in practice "detect which single major is present" — a low-ambiguity problem.
• Migration from v0.1.x on Filament 3 is a genuine no-op per the notes, which makes adoption low-risk and independently schedulable from any Filament upgrade.

Technical risk

• Silent misconfiguration is the top risk. With no abstract form() and no declared return contract on the base class, a subclass with the wrong signature for the installed major produces no compile-time or boot-time error — it produces a form that doesn't render. That failure is discovered by an admin user, not by CI. We should assume this becomes our most common self-inflicted incident.
• Duck-typed introspection over framework internals. FormIntrospector accepting "whichever container Filament resolves" is deliberate decoupling, but it is coupled to runtime shape rather than a published interface. A Filament patch/minor that changes that shape breaks every settings form in the panel, and can block us from taking a Filament security patch.
• Tested matrix is a point sample, not a range. Filament 3.3.50, 4.11.1, 5.6.1 are specific builds. Nothing in the notes states a supported constraint range or a policy for later minors in the same major. Filament 5.x is the newest and least battle-tested of the three.
• Secrets at rest depend on a field-level behaviour. TextInput->password() doing the encryption means the guarantee holds only for values written through that field. Any write through the settings API directly, any later switch of the field type, or any key rotation puts secrets in scope. This is a data-handling decision, not a UI decision, and needs an explicit answer.
• No documented escape hatch. Zero-config auto-detection is good until it guesses wrong; the notes describe no way to force a version, no artisan diagnostic, and no stated behaviour when detection fails.
• Assessment basis caveat: this review is derived from release notes only — no code audit, no dependency manifest, no prior assessment. The compatibility and encryption claims are vendor claims as of this release.

Key questions

1. What exactly does runtime detection key on, and what happens if it cannot resolve a version — loud exception or silent default? Is there a doctor/diagnostic command?
2. Why is form() intentionally unenforced? Can it be backed by an interface, a @method annotation, or a boot-time assertion so failures are loud?
3. Which cipher and key does the password() encryption path use — Laravel's encrypted cast, or something package-local? What is the key-rotation story, and does a masked field blank or re-populate its value on re-render?
4. What Filament constraint range does composer.json declare — exact tested patches or a caret range? What is the stated support window for Filament 3, and will dropping it be a major bump?
5. Which version of the core laravel-polymorphic-settings package does this require, and is that constraint aligned with what we already run?
6. Is any v0.1.x public API deprecated or removed beyond the form() relocation?
7. Laravel 13 and PHP 8.5 are listed as tested — are those GA targets, and do our other dependencies support them?

Integration Approach

Stack fit

• Fits a Filament admin panel where settings belong to a model (tenant, team, user) rather than to the application — which is the whole point of the polymorphic core. If our settings are strictly global, the core package plus config is sufficient and this adapter adds little.
• Best fit where we already have Filament panels and settings pages; worst fit if our admin surface is custom Blade/Livewire, since the value here is form discovery integration.

Migration path

• v0.1.x → v0.2.0 on Filament 3: no code change. Treat as a routine patch-level upgrade and take it early — it removes the package from the critical path for the later Filament upgrade.
• Filament 3 → 4/5: this is the substantive work, and it is Filament's migration, not the package's. Every subclass of the settings form base class needs its form() signature changed to Schema and ->schema([...]) replaced with ->components([...]). Effort scales linearly with the number of settings form classes we own — inventory that count before committing to a date.
• No automated migration is offered for subclass signatures; expect a mechanical but manual sweep, plus a diff review per class.

Compatibility

• Backward compatible for Filament 3 consumers; forward compatible across 4 and 5 through the same package version. That means a Filament major upgrade no longer requires a coordinated package bump — a real reduction in coupling.
• Constraint risk sits on Filament, not on us: we must confirm our composer.json Filament constraint and the package's declared range intersect cleanly, and that no transitive dependency pins us to a single major.

Sequencing

1. Inventory: current Filament major, current core settings package version, and every class extending the package's base form.
2. Upgrade to package v0.2.0 while staying on Filament 3. Verify no behavioural change. This is the cheap de-risking step and should be done regardless of Filament plans.
3. In a branch, raise Filament to the target major and update each subclass's form() signature and schema() → components() in the same PR, so the two changes are never separated.
4. Smoke-test every settings page: mount, edit, save, re-mount, and a secret round-trip (set, reload, confirm masked, confirm the stored value is not plaintext).
5. Only then remove the Filament 3 branch and update internal docs/templates for new subclasses.
6. Mirror the vendor matrix in our own CI for the one Filament major we actually run — do not attempt to run all three in application CI.

Operational Impact

Maintenance

• The package now carries three Filament majors in one branch. That is a benefit to consumers and a cost to the maintainer: CI runs the full suite across 3 Filament × 3 PHP × 2 Laravel × 2 OS. Sustainability depends on the maintainer's appetite for that indefinitely, and Filament 3 will reach end of life before the others.
• Duck-typed internals mean maintenance effort is reactive — Filament changes surface as consumer bug reports, not as clean interface breaks the maintainer can compile against.
• Our ongoing maintenance is low but non-zero: any new settings form we write must target the installed major's signature. Codify this in the template/snippet used by the team, or the wrong signature will be copy-pasted.

Support

• Triage will be version-sensitive: the same symptom has different causes per Filament major. Require Filament, Laravel, PHP, and package versions in every ticket.
• Expect a recurring class of ticket — "settings form is blank" — caused by a signature mismatch with no error message. Cheapest mitigation is a small internal check (a base-class boot assertion or a test that instantiates each form and asserts discovery) rather than training people to spot it.
• Vendor responsiveness is unproven from the notes: no stated issue policy, no LTS commitment per Filament major.

Scaling

• The adapter itself is not a scaling concern; it runs on form mount and form save, not on request hot paths. Per-render introspection cost is negligible but worth confirming it is memoized rather than re-resolved per field.
• Real scale characteristics come from the core settings store: read volume on mount, cache strategy, and the width of the polymorphic lookup. If settings are read on every admin page render, the core package's caching is the thing to evaluate, not this one.
• Secret encryption adds per-save crypto cost only — irrelevant at admin-panel volumes.

Failure modes

• Silent form non-render (wrong or missing form() signature): highest likelihood, discovered by users, no error signal. Mitigate with a discovery test per form class.
• Introspection break on a Filament patch: panel-wide, affects all settings pages at once, and can block a security upgrade. Mitigate by pinning Filament to tested patches and treating Filament bumps as reviewed changes, not automatic.
• Secret exposure or loss: a field type change, a write bypassing the form, or a key rotation can store a secret in plaintext or blank it on next save. Mitigate with an explicit runbook and a round-trip test in the smoke suite.
• Detection misresolution: undocumented behaviour on an ambiguous or unresolvable install. If there is no fail-loud path, a broken deploy could look like a working one until someone opens a settings page.
• Composer deadlock: if the package's Filament range lags a Filament release we need, we are stuck between a security patch and a working panel. Confirm the declared range is wide, not pinned to the three tested builds.

Ramp-up

• Low for any developer already fluent in Filament. The only new concept is "use the signature your Filament major expects," and the release notes carry a working example for both shapes.
• The gap is documentation: no per-major guide page, no upgrade diff, no statement of what happens on a missing form(). Two pages — one "which signature do I use," one "upgrading Filament majors" — would eliminate most of the ramp-up and support load.
• Recommend a short internal note recording our Filament major, the subclass inventory, and the secret round-trip check, so the next person to touch a settings form does not rediscover this release's constraints.