Laravel Toman Laravel Package

Getting Started

1. Install the package

   composer require evryn/laravel-toman
   

   v4.1.0 adds Laravel 12 support — this is the only change since v4.0.0, so no API or config changes are required when upgrading from v4.x. If you are on Laravel 11 or older, 4.1.0 still works; Laravel 12 is now simply allowed by the constraint.

2. Publish the config

   php artisan vendor:publish --tag=toman-config
   

   This lands config/toman.php. Review it before writing any formatting code — prefix/suffix, separator, decimals, and locale here drive every formatted output in the app.

3. First use case — display prices Prices in Iranian commerce are typically stored in Rial, but users expect Toman (Rial ÷ 10). Convert at the presentation boundary:

   toman(1500000); // 150000  (Rial -> Toman)
   

   In Blade:

   @toman($product->price_rial)
   

4. Where to look first

   • README helper/facade table (the whole public surface is small).
   • config/toman.php — formatting behaviour.
   • The toman validation rule and Blade directive — these are the two integrations you'll reach for most.

Implementation Patterns

• Store Rial, render Toman. Treat Rial as the canonical unit in the database and convert only at the view/API layer. Centralise the conversion in one place so you never divide twice or forget to divide.
• Model accessor for readability. Expose a derived attribute rather than calling the helper everywhere:

  public function getPriceTomanAttribute(): string
  {
      return toman($this->price_rial);
  }
  

• Blade directive over manual formatting. Use @toman(...) instead of number_format($price / 10). It keeps separators, decimals, and suffix consistent across every view and picks up config changes automatically.
• Facade in services / API resources. When you need the value outside a view, resolve the Toman facade (or the helper) in a dedicated presenter/resource rather than in the controller.
• API responses. Return both values so clients can choose:

  return [
      'price_rial'   => $order->price_rial,
      'price_toman'  => toman($order->price_rial),
  ];
  

• Validation. Use the package's toman validation rule when accepting user-entered amounts in Toman (forms, admin panels) so input matches your display unit. If the field is Rial, validate as numeric instead and convert downstream.
• Feature tests. Assert against the helper's output rather than a hard-coded string, so a config change (e.g. suffix) doesn't break every test:

  $response->assertSee(toman(1500000));
  

• Laravel 12 integration tip. No code changes needed, but if you maintain a package matrix, bump your dev dependency to laravel/framework: ^12.0 and re-run the suite to confirm nothing relies on removed framework APIs.

Gotchas and Tips

• Rial vs Toman confusion is the #1 bug. The helper divides by 10 by default. If a value is already in Toman and you pass it through again, you'll silently under-charge by 10×. Name columns explicitly (price_rial, price_toman) and never rely on context.
• Validation rule is Toman-scoped. The toman rule validates/parses a Toman input, not Rial. Mixing units across validation and persistence is a common source of off-by-10 bugs.
• Config is global. Prefix, suffix, separator, and decimals affect all output. Changing them in one environment and not another produces inconsistent tests — run php artisan config:cache in production and clear it after edits.
• Locale & numerals. Persian vs English digits and thousand separators differ. Confirm what the configured locale produces before shipping to a Persian audience; assert against the actual localized string in tests.
• Blade escaping. The directive emits a formatted string. If your formatted value contains a suffix and you need it raw in an attribute, be deliberate about {{ }} vs {!! !!} — double-escaping HTML entities in suffixes is a nuisance.
• Decimals. Iranian Toman is typically shown without decimals; if you handle fractional Rial (e.g. for unit prices), make sure round-trip conversion (Rial → Toman → Rial) is lossless or documented.
• Upgrade note (4.1.0). Only the Laravel 12 constraint was widened — no breaking changes, no deprecations. Pin ^4.1 if you're on Laravel 12; otherwise ^4.0 remains safe.
• Extension points. Publish the config first and avoid editing vendor files. If you need bespoke formatting (e.g. word-form Toman, or Persian digit conversion), wrap the helper in your own presenter class rather than forking the package.