Laravel Toman Laravel Package

Product Decisions This Supports

• Localized pricing for the Iranian market. Whether you display prices in Rial or Toman, with correct separators and locale-aware formatting, is a recurring product question for any Iran-facing storefront, subscription flow, or invoicing feature. This package centralizes that decision in one place instead of scattering number formatting across Blade templates.
• Build vs. buy on money handling. Currency formatting looks trivial until rounding, thousand separators, and Rial↔Toman conversion (a factor-of-10 trap) start producing off-by-10x pricing bugs. Adopting a small, focused package is usually cheaper than owning this logic in-house — but it is a narrow dependency, not a payments abstraction.
• Roadmap sequencing for Laravel upgrades. v4.1.0 adds Laravel 12 support. That directly informs when the framework upgrade becomes unblocked, and whether this dependency sits on the critical path of a Laravel 11→12 migration. If your roadmap has a framework upgrade in the next two quarters, this release removes one blocker.
• Scope boundary for multi-currency work. This package solves Iranian Toman/Rial presentation. It does not solve FX rates, multi-currency carts, tax jurisdictions, or payment gateway settlement. If multi-currency is on the roadmap, treat this as one locale-specific adapter, not the foundation.
• Use cases it fits: Iranian e-commerce catalogs, subscription pricing pages, invoice/receipt rendering, admin dashboards needing human-readable amounts, and API responses that must return consistently formatted price strings.

When to Consider This Package

Adopt when:

• You ship a Laravel application with an Iranian user base and need consistent Toman/Rial formatting and conversion in one API.
• You are on (or moving to) Laravel 11 or 12 — v4.1.0 explicitly supports Laravel 12, so the compatibility argument is current rather than aspirational.
• Your team would otherwise hand-roll formatting helpers and repeatedly get Rial/Toman magnitude conversions wrong.
• You want a single, swappable formatting layer so that a future pivot to a broader money library is a contained refactor rather than a codebase-wide hunt.

Look elsewhere when:

• You need real money semantics. Arithmetic-safe value objects, arbitrary precision, currency arithmetic, and multi-currency support belong to a dedicated money library (e.g. brick/money) — this package is a presentation/formatting convenience.
• Iran is not a target market. There is no value here for other locales; you would be adding a dependency with zero coverage of your use case.
• Your app is not on a supported Laravel/PHP matrix. Verify the PHP floor and Laravel constraints in composer.json before committing; framework support is the package's main maintenance signal.
• You require a large, actively-staffed dependency. This is a small, single-maintainer package with a narrow surface. That is acceptable for a formatting helper, but it argues for wrapping it behind your own interface so replacement is cheap.
• You need regulated or audit-grade monetary calculation. Formatting helpers are not a control for financial correctness.

How to Pitch It (Stakeholders)

For executives: This is a small, low-risk utility that makes Iranian Toman pricing display correct and consistent across our product surface, and it removes a dependency blocker for adopting Laravel 12. Cost of adoption is near zero; cost of not adopting is recurring pricing-display defects and duplicated formatting logic that we would otherwise maintain ourselves. It is a formatting layer, not a payments or ledger system — it does not change how we charge customers.

For engineering: v4.1.0 is a compatibility release adding Laravel 12 support; no breaking changes are indicated, so the upgrade from 4.0.x is a routine composer update. The dependency is narrow in scope and small in footprint, which is exactly what we want for a formatting concern. Recommended posture: adopt behind a thin internal service or facade (e.g. PriceFormatter) so call sites never depend on the package directly, pin the version, and keep the Rial↔Toman conversion and rounding behavior covered by our own tests — those are the failure modes that actually reach customers. Treat the Laravel 12 support as the trigger to schedule the framework upgrade work it was blocking.