Dosh Laravel Package

Technical Evaluation

Architecture fit. Dosh is a presentation-layer utility: a thin wrapper over PHP's intl NumberFormatter exposed through a Laravel service provider, facade, helper functions, and Blade directives. That scope is intentionally narrow — it formats currency values for display and does not model money. It is not a substitute for moneyphp/money or brick/money; there are no value objects, arithmetic, allocation, rounding-policy, or FX conversion primitives. Architecturally this is a good fit for the view boundary of a Laravel app (Blade partials, mail templates, PDF invoices, Inertia props) and a poor fit for domain or persistence layers. The correct framing for stakeholders is "localized currency rendering," not "payments infrastructure."

Integration feasibility. Low friction. Standard Composer install, Laravel package auto-discovery, publishable config, and an ext-intl requirement that is the only meaningful environmental prerequisite. Any Laravel application on a conventional PHP-FPM or Octane runtime can adopt it in a single sprint slice. There is no database surface, no queue worker, no scheduled job, and no auth interaction — the blast radius of a bad rollout is cosmetic, not transactional. That makes it a low-ceremony adoption candidate.

Technical risk. Three risks dominate. (1) Bus factor: 21 stars and a single-vendor origin (Blue Bay Travel) imply a small maintainer pool and limited external battle-testing; the October 2026 release date is a positive maintenance signal but does not by itself prove a support commitment. (2) ICU/environment drift: output is a function of the installed ICU data version, not just the package version — dev containers, CI runners, and production images with different intl builds can emit different whitespace, symbol placement, and separators for the same input. (3) Precision hygiene: a formatter accepts whatever numeric type it is handed, so float inputs can surface artifacts or silently round; without an enforced boundary (integer minor units or decimal strings) the package can mask upstream money bugs rather than reveal them. Secondary risks: undocumented rounding-mode control, locale-resolution behavior, and SemVer discipline across majors.

Key questions. What numeric types are accepted and how are floats and high-precision decimals handled? Is rounding mode configurable, and what is the default? How is locale resolved — app locale, per-call override, or config — and what is the fallback chain? Are NumberFormatter instances cached or re-instantiated per call? What is the supported matrix of PHP, Laravel, and ICU versions, and is that stated in CI? Is formatting strictly display-only, or does the package expose any conversion or arithmetic? What is the test coverage and the maintainers' policy on breaking changes? Does the config survive config:cache, and are any runtime mutations relied upon?

Integration Approach

Stack fit. Strong for server-rendered Blade and mail/notification templates, where a directive-style API removes repeated number_format() plus hardcoded symbol concatenation. Acceptable for JSON APIs if responses are explicitly presentation-shaped, but for public APIs I would prefer returning minor units plus an ISO 4217 code and letting clients localize — server-side formatting bakes locale into cached payloads and CDN layers. For Inertia/SPA front ends, decide once whether formatting is server-owned or client-owned; mixing both produces inconsistent output across surfaces.

Migration path. Adopt incrementally rather than as a flag-day refactor. Inventory current formatting call sites (number_format, sprintf('£%s'), ad-hoc helpers, existing money-library formatters). If the codebase already uses moneyphp/money, do not layer Dosh on top by default — that library ships its own formatter, and a second formatter creates two sources of truth. Where Dosh is chosen, wrap it behind an in-house PriceFormatter contract (or a Blade component) so the vendor package is an implementation detail and remains swappable if the project is abandoned or the API diverges. Sequence: introduce the wrapper and one pilot surface, validate rendered output across locales, then migrate call sites behind the wrapper.

Compatibility. Verify ext-intl present in every image (common gap in slim/alpine bases), pin the ICU version or assert formatted-output snapshots in CI to catch drift, and confirm the package's Laravel and PHP constraints against the target app version before committing. Dependency conflicts are unlikely given the package's small footprint, but run composer why-not during evaluation. If the app targets Octane, confirm no per-request state leakage in the facade/config layer — expected to be fine for a stateless formatter, but worth a boot-time check.

Sequencing. (1) Spike: install in a branch, format a representative matrix of currencies, locales, zero/negative/large values, and record actual output. (2) Pin the version and lock ext-intl in composer.json platform requirements. (3) Add CI assertions on formatted snapshots and composer audit. (4) Introduce the internal PriceFormatter abstraction and migrate a single high-traffic template. (5) Roll out, then delete legacy formatting helpers to prevent reversion. (6) Record the decision as an ADR, including the explicit position that Dosh is display-only and money arithmetic lives elsewhere.

Operational Impact

Maintenance. The package itself is small and slow-moving; ongoing cost is near zero. The real maintenance obligation is the abstraction layer and the snapshot tests around it — those are what make a low-star dependency safe. MIT licensing means the fallback of forking or vendoring is always available, which materially reduces the risk of an unmaintained upstream. Budget a periodic review of the upstream repository (release cadence, open issues, PHP version support) as part of routine dependency hygiene.

Support. Documentation is thin relative to first-party Laravel packages, and the community is small — expect GitHub issues to be answered on the maintainer's schedule, not the product's. Internal ownership must be explicit: one engineer or team accountable for the wrapper, the locale matrix, and the upgrade path. Do not assume Stack Overflow coverage for edge cases; the snapshot suite is the de facto specification.

Scaling. Runtime cost is negligible at typical request volumes; the only optimization worth measuring is NumberFormatter instantiation if formatting is called in loops (e.g., rendering a 500-row invoice or a large export). If profiling shows allocation pressure, memoize formatter instances by (locale, currency, style) inside the wrapper. No impact on horizontal scaling, caching topology, or queue throughput.

Failure modes. Missing or mismatched intl → hard failure at boot or first format call; treat as a deploy-time gate, not a runtime surprise. ICU version skew → silent output divergence between environments, the most insidious failure here because it passes tests written on one machine and fails visual review on another. Numeric type misuse → displayed values that disagree with ledger values, typically discovered by finance rather than engineering. Locale fallback errors → correct number rendered with the wrong symbol or separator. config:cache interactions if any code mutates currency config at runtime. Blade view-cache staleness after an upgrade of directive-providing packages. Each maps to a cheap mitigation: platform requirement checks, output snapshots, a strict input contract, and a cache-clear step in the deploy pipeline.

Ramp-up. A mid-level Laravel developer is productive in under a day; the API surface is a handful of methods and directives. The non-obvious knowledge is environmental (ICU, locale matrix) and contractual (what the package does not do), both of which belong in the ADR and onboarding notes rather than in tribal memory. Net assessment: low-risk, low-cost adoption for display formatting, contingent on wrapping it, pinning the environment, and being explicit that it is not a money-handling library.