Laravel Toman Laravel Package

Technical Evaluation

Architecture fit. evryn/laravel-toman is a narrow-scope utility package: it wraps Toman-denominated currency formatting, conversion, and validation helpers into Laravel's service container, Blade, and validator layers. That is a shallow integration surface — a service provider, helper functions, a facade, and a handful of validation rules. It does not own domain state, persist data, or intercept the request lifecycle. For any application selling to the Iranian market, this replaces hand-rolled number_format() calls scattered across views and controllers with a single tested convention, which is the real architectural value: it centralises a formatting policy that otherwise drifts.

Integration feasibility. Composer-only, package auto-discovery, no schema changes, no queue or cache dependencies. A competent Laravel developer can wire it in within an afternoon, including replacing existing ad-hoc formatting. The v4.1.0 release adds Laravel 12 support via a single external contribution — a low-risk, additive change with no migration steps implied.

Technical risk. The technical risk is low; the organisational risk is moderate. This is a single-maintainer, single-purpose package in a niche ecosystem. It sits directly in the money path of the UI, where a defect manifests as a wrong price shown to a customer, not a stack trace. Two risks deserve explicit attention: (1) the Toman/Rial distinction is a factor-of-ten boundary and is the single most likely source of silent error; (2) Laravel 12 requires PHP 8.2+, so this bump may have quietly raised the package's floor and dropped older framework constraints — a routine but real compatibility break for anyone on PHP 8.1 or Laravel 10.

Key questions.

• Did v4.1.0 raise the minimum PHP version or drop support for Laravel 10/11 in composer.json, even though the changelog only mentions an addition?
• Is the v4.0.0 → v4.1.0 diff confined to CI matrix and constraint changes, or does it touch formatting/rounding logic?
• What is the package's test coverage, and does CI exercise Laravel 12 against the full PHP matrix?
• Is the maintainer responsive? One new contributor on a compatibility PR is a positive signal but not a bus-factor fix.
• Are documented examples and any locale/config defaults written for Toman or Rial, and are they unambiguous?
• Does the package expose rounding mode and negative-value handling explicitly, or does it inherit PHP's default?

Integration Approach

Stack fit. Targets Laravel 10/11/12 with PHP 8.1+ (verify the 12.x floor). No conflicts with standard application stacks; the main friction is indirect — pulling Laravel 12 support elsewhere in the dependency graph is usually the hard part, not this package.

Migration path. For an existing v4.0.0 consumer, this is a composer update with no code changes. For anything on v3.x, treat it as a major-version upgrade and read the v4 upgrade guide before touching constraints. For greenfield adoption, install, publish config if offered, and standardise on the helper API in a single place (a Blade component or a Price value object) rather than calling the helper ad hoc throughout views — that keeps any future swap cheap.

Compatibility. Because this release only widens framework support, it is safe to take on Laravel 12 and this package together. Do not, however, assume the inverse: if v4.1.0 dropped Laravel 10 constraints, teams on 10 must pin to v4.0.x and plan a framework upgrade rather than a package upgrade.

Sequencing. (1) Confirm composer.json constraints and PHP floor from the tagged release, not the changelog. (2) Update in a feature branch, run the full suite. (3) Add a golden-file test asserting formatted output for representative amounts — including zero, negatives, and a boundary case over one million — so a future silent formatting regression fails CI. (4) Replace legacy inline formatting incrementally, view by view, verifying rendered output against current production behaviour. (5) Ship to staging, spot-check price-displaying pages, then release.

Operational Impact

Maintenance. Low steady-state cost: no migrations, no background work, no data to reconcile. The real maintenance obligation is version-tracking — budget a review on each major Laravel release, since framework compatibility is this package's principal churn driver.

Support. Community-only, GitHub issues, no commercial backing or SLA. Acceptable for a formatting utility; unacceptable to depend on without an internal fallback. Mitigate by keeping a thin internal PriceFormatter wrapper so the package is replaceable in an afternoon.

Scaling. Negligible. Formatting is CPU-only arithmetic and string work with no I/O; it does not meaningfully affect throughput or latency even at high page volumes. There is no horizontal-scaling consideration.

Failure modes. Ranked by likelihood and blast radius: (1) Toman/Rial confusion producing a 10× price error — the highest-severity failure and the one to test explicitly; (2) rounding-mode mismatch producing off-by-one unit discrepancies at checkout; (3) incorrect handling of negative values (refunds, adjustments); (4) constraint drift leaving the package pinned to an unsupported Laravel branch, creating a security-patch dead end; (5) abandonment of the upstream project, mitigated by the wrapper abstraction above. None of these surface as exceptions — they surface as wrong numbers on a page, so detection depends on tests you write, not on monitoring.

Ramp-up. Hours for a Laravel developer familiar with Composer and Blade; the API is small enough to read in one sitting. Confirm whether documentation is primarily Persian — that is not a blocker but affects onboarding for non-Persian-speaking team members and should be paired with a short internal usage note.