Filament Currency Laravel Package

Technical Evaluation

Architecture fit. filament-currency is a presentation-layer plugin for Filament panels: it supplies a currency-aware form input (masked/parsed entry) and a table column that renders a stored numeric value using a configured locale and currency. It does not own money semantics — no wallets, no FX conversion, no ledger, no rounding policy. That makes it a narrow, low-coupling dependency that sits at the UI boundary and can be replaced by a custom field/column formatter without touching domain code. Good fit for admin/back-office panels where amounts are single-currency per record and formatting consistency matters. Not a fit if the product needs multi-currency arithmetic, policy-driven rounding, or audit-grade monetary types — those belong in the domain layer (integer minor units or a decimal money type), with this package only rendering the result.

Integration feasibility. Composer-installable, registered as a Filament plugin, config published for default currency and locale. Typical effort is hours, not days: install, publish config, replace existing TextInput/TextColumn usages, verify formatting against real data.

Technical risk. 3.0.2 is a single-line patch on the v3 branch: it stops the currency mask echoing programmatic updates back into Livewire state. No new APIs, no deprecations, no migration steps. The risks remain structural, and this release sharpens two of them:

• Branch drift. The assessment was written against 2.1.0 on v2, which described v3 as "evidently existing." v3 now has a live 3.0.x line receiving fixes. That makes v2 the trailing branch in practice, with the support window still unstated. Adopting 2.1.0 knowingly means adopting a branch that is receiving less attention than the one being actively patched.
• The fix is v3-only (as far as the notes go). The Livewire programmatic-update echo bug is a real data-integrity-adjacent defect for edit forms — a programmatic $state change (recalculation, currency switch, import hydration) gets pushed back through the mask and can re-trigger Livewire updates or round-trip the value. It was flagged in the prior assessment's failure modes. It is now fixed on v3 and, per the notes, not announced for v2. That is a functional argument for v3 beyond the compatibility argument.
• The Laravel constraint behaviour of the v2→v3 jump is still unverified for us; a v3 major riding a Filament major likely means a Filament constraint change, and the v2 illuminate/* question from the prior review is now moot if we move to v3.
• Precision and rounding are ours, not the package's. It formats what you store; a float column displays correctly and still drifts.
• Maintainer concentration: still effectively a single-primary-maintainer package, though 3.0.2 comes from a first-time external contributor, which is a mild positive for bus factor and for the health of the issue pipeline.
• Locale output depends on PHP intl/ICU data, which varies by base image. Same code, different container, different symbol or separator.

Key questions.

• What Filament and Laravel majors does 3.0.x target, and is there a documented upgrade guide from v2? This is now the primary decision input, not a footnote.
• Is the PR #58 mask/echo fix backported to v2, and is v2 now security-only or fully frozen? If it is frozen, the edit-form echo defect is permanent for v2 users.
• What is the stored representation contract — decimal column, integer minor units, or float? Where does rounding happen?
• Multi-currency: is a per-record currency supported through the field's currency argument, or is it global config only?
• Does input parsing respect locale separators (1.234,56 vs 1,234.56), and how are negative and parenthesised amounts handled?
• Is ext-intl a hard requirement, and is it present and version-pinned in our runtime images?
• Does the echo fix change the Livewire round-trip contract — i.e. does it introduce a debounce/deferral behaviour that our edit-form tests would need to account for?

Integration Approach

Stack fit. Filament + Livewire + Blade. No new infrastructure, no queue, no external service, no package-owned migrations beyond config. Fits our panel stack, but the target has moved: evaluate against whichever Filament major 3.0.x supports, not the one 2.1.0 supported.

Migration path. Two decisions, not one, and they should be separated rather than chained:

• Stay on v2: composer update ariaieboy/filament-currency, re-run the panel suite. Cheap, but you forgo the mask/echo fix and accept a trailing branch.
• Move to v3: treat as a major upgrade. Read the 3.0.0 upgrade notes (not in this changelog — go to the repo), diff composer.json for the Filament and illuminate/* constraints, then convert one resource at a time. The 3.0.2 patch should land as part of that move, not as a standalone step, since it only matters once you are on v3.

Compatibility. Verify the matrix explicitly by diffing composer.json between the version we run and 3.0.2: Filament major, PHP 8.2–8.4, Laravel 11/12/13, ext-intl. Pin the version and record the verified matrix in an ADR. Our CI should gate on the Filament/Laravel ceiling, since that is the constraint class that has moved twice now.

Sequencing. (1) Diff composer.json between our current pin and 3.0.2 to establish the real Filament/Laravel delta. (2) Decide v2-stay vs v3-move; write the decision down with the branch support-window caveat. (3) If moving to v3, land 3.0.2 on a branch and run the panel suite plus formatting snapshot tests over representative amounts and locales, with an explicit test for the edit-form echo case PR #58 fixes. (4) Deploy to staging on the production container image so ICU parity is exercised. (5) Production, single panel first. (6) If staying on v2, open an issue asking whether the echo fix will be backported, and set a review date against the next Filament major.

Operational Impact

Maintenance. Near-zero ongoing: a config file and component usage. Budget roughly one short upgrade per Filament major. The 3.0.2 patch is a good signal — the active line is being maintained and now accepts outside contributions — but it also confirms attention has shifted off v2, so the maintenance budget for a v2 pin should include the cost of carrying an unfixed edit-form defect.

Support. Single-maintainer OSS with growing community contribution, support through GitHub issues, no vendor SLA. Acceptable for a UI formatter; not acceptable as the sole owner of money semantics. Mitigation unchanged and still worth doing: keep thin in-house wrapper components around the package's field and column so a swap, a fork, or a cherry-picked backport is a one-file change.

Scaling. Effectively free — formatting happens per render. The only watch item is wide table pages: hundreds of formatted currency cells per request adds measurable render time, so paginate and avoid on-the-fly formatting in exports and PDF generation. If the echo fix defers state updates, confirm it does not add a round trip per keystroke in large edit forms.

Failure modes. Missing or mismatched ext-intl/ICU data, producing wrong separators or throwing at render; float storage hiding cent-level drift behind correct-looking output; locale-dependent parsing turning 1.234,56 into 1.23; Livewire rehydration of formatted state on edit forms — partially retired on v3 by 3.0.2, still live on v2; and package abandonment across a Filament major, which blocks panel upgrades. Guards: an ICU-pinned base image, decimal columns, parse regression tests, an explicit echo/recalculation test on edit forms, and wrapper components that bound the blast radius.

Ramp-up. Under a day for a Laravel developer, most of it spent on configuration conventions and money-storage decisions rather than on the package itself.

Verdict. 3.0.2 is a safe patch, but it is not the release to reason about — it is evidence. It tells us v3 is the maintained line and that a known edit-form defect is fixed there and not (announced) on v2. Reopen the v2-vs-v3 decision rather than absorbing 3.0.2 into the existing 2.1.0 assessment: confirm the v3 compatibility matrix, then either move to v3 on a planned schedule or consciously accept v2 as frozen. This is now an ADR entry with a decision date, not a one-line note.