Progress Stepper Laravel Package

Technical Evaluation

Architecture fit

• aureuserp/progress-stepper is a Filament panel UI component (a visual step indicator), not infrastructure. It sits at the presentation layer of a Laravel + Filament admin app; it has no bearing on domain logic, persistence, or queues.
• Value is proportional to how much of our admin surface is built on Filament wizards/forms. Outside Filament panels, this package has no application.
• The v1.0.2 fix reveals the component is coupled to Filament internals: ProgressStepper::size() collided with the size() API ToggleButtons gained in Filament 5.9, producing a fatal error. That implies inheritance from (or signature conformance to) a Filament base class rather than composition. That is the single most important architectural fact about this dependency — it inherits upstream's method surface and therefore inherits upstream's breaking potential at the patch/minor level, not just majors.

Integration feasibility

• Low effort: composer require aureuserp/progress-stepper, register the plugin in the panel provider, optionally publish views. No migrations, no config surface of consequence, no service providers of ours to write.
• Blast radius of installation is small and reversible (composer remove + revert panel provider).
• Estimated integration effort: under a day for a developer already fluent in Filament; the API surface (steps, current step, size) is small enough to read in full before adopting.

Technical risk

• Upstream signature drift (high). A Filament minor (5.9) caused a PHP fatal. Signature-incompatibility fatals are raised at class-declaration/link time, cannot be caught by try/catch, and will 500 any request that loads the class — potentially the entire panel if the component is referenced from a shared layout or the panel provider, not just the one page using the stepper. This is a recurring class of risk, not a one-off, unless v1.0.2 changed the inheritance strategy (the notes suggest it did not — it widened the signature instead).
• Bus factor (high). Single-maintainer, pre-2.0 OSS package. No SLA, no security policy stated, unknown CI matrix.
• Silent input coercion (medium). "Unsupported sizes fall back to md" trades a loud failure for a quiet visual regression. A typo ('lg'/'large') will render at medium with no diagnostic. Acceptable for a cosmetic component, but it removes the cheapest signal we have that our usage has drifted.
• Evidence limits (explicit). This assessment is derived from the v1.0.2 release notes only; there is no prior assessment, no repository inspection, no dependency audit, and no usage telemetry. Confidence is moderate on integration cost, low on maintenance health.

Key questions

1. Does composer.json constrain Filament to ^5.0 (allowing the minor that broke it) or pin a tested range? What is the constraint today?
2. Is there a CI matrix running the test suite against multiple Filament minor versions, and does v1.0.2 add a regression test for the size() signature (Size enum, null, string, invalid string)?
3. Does the component extend a Filament class or compose one? If it extends, is there a roadmap to decouple before Filament 6?
4. Will referencing Filament\Support\Enums\Size in the signature break installs still on Filament < 5.9 where that enum may not resolve? (Union types resolve lazily in PHP, so this is likely safe, but it needs a test on the oldest supported Filament.)
5. How long was the fatal live before 1.0.2 shipped — i.e., what is the maintainer's observed time-to-fix on a hard breakage?
6. What is the licence, and are we permitted to fork and vendor it internally if maintenance stalls?

Integration Approach

Stack fit

• Requires Laravel + Filament 5.x (PHP 8.2+ typical). Fit is clean if the admin surface is Filament-native; otherwise do not adopt — a plain Blade/Tailwind stepper is a few hours of work and carries zero upstream coupling.
• Complements, does not overlap, existing Filament form/wizard components. No conflict with our own domain packages.

Migration path

• From nothing: add the dependency, register the plugin, replace any bespoke step markup. No data migration, no schema change, no backfill — the cheapest possible class of change.
• On existing installs: v1.0.2 is a drop-in patch (bugfix only, no API removal). Bump the constraint to ^1.0.2 as a floor; anything below that is unsafe on Filament 5.9+.
• Exit path is cheap: the component is small enough to reimplement or vendor-fork. Write that down as the contingency now, not after an incident.

Compatibility

• Hard requirement: v1.0.2 if and only if the panel runs Filament 5.9+. On Filament < 5.9, v1.0.2 should be harmless but is unverified (see question 4) — validate in a throwaway branch before relying on it.
• No PHP extension, database, or queue implications.
• Verify per-panel: a multi-panel Filament app can run different Filament constraints per panel only if isolated by separate composer roots; if everything shares one vendor tree, one Filament upgrade gates the whole estate.

Sequencing

1. Pin the current Filament version per panel and record the tested pair (Filament X ↔ progress-stepper Y) in the dependency register.
2. Adopt ^1.0.2 in a branch; if already installed below 1.0.2 and running Filament 5.9+, treat this as a hotfix, not a routine bump.
3. Regression pass on every screen embedding the stepper — specifically the rendered size of the stepper, since the fallback-to-md behaviour can change appearance without erroring.
4. Add the package to the Filament-upgrade checklist so future Filament minors are tested against it before rollout.
5. Set a decision review at Filament 6 planning or at the next upstream breakage, whichever comes first; fork/vendor if time-to-fix degrades.

Operational Impact

Maintenance

• Zero steady-state runtime maintenance; no background jobs, no storage, no config drift.
• The real recurring cost is upgrade coupling: every Filament minor is a potential hard break. Budget a smoke test per Filament upgrade rather than assuming patch-level safety — v1.0.2 is direct evidence that patch-level safety does not hold here.
• Small ongoing tax: track releases manually; the package is unlikely to appear in automated security/dependency alerting with meaningful signal.

Support

• Community OSS with a single maintainer and no SLA. Internal ownership must be assigned to one Laravel/Filament developer who can read the source and patch a signature — the codebase is small enough that this is realistic.
• Escalation path is effectively "fix it ourselves." Confirm licence permits that before adoption.

Scaling

• No scaling concerns. Purely presentational, server-rendered, negligible per-request cost, no state, no external calls. It will not be a bottleneck at any realistic admin user count.

Failure modes

• Fatal on class load (observed, highest severity): a Filament minor bump takes down any request rendering the component, possibly the whole panel, with no graceful degradation and no try/catch recourse. Detection depends entirely on our own upgrade testing or on production 500s.
• Silent size fallback (medium): invalid or renamed size values render at md with no error — visual inconsistency ships quietly.
• Abandonment (medium): no further releases; the next Filament break becomes permanently ours. Mitigated by the small surface area and the fork contingency.
• Constraint drift (low): a permissive Filament constraint lets a composer update reintroduce the fatal without any code change on our side.

Ramp-up

• Hours, not days: one developer, one sitting to read the component source and the Filament panel-provider registration pattern.
• No specialist knowledge required beyond standard Filament plugin wiring and Tailwind conventions.
• Recommend the adopting developer write a two-paragraph internal note covering the tested Filament/package version pair, the silent-fallback behaviour, and the fork contingency — that note is the entire operational runbook for this dependency.