Money Formatter Laravel Package

Getting Started

Install via Composer:

composer require nwidart/money-formatter

Because this predates package auto-discovery, register the service provider manually in config/app.php:

'providers' => [
    // ...
    Nwidart\MoneyFormatter\MoneyFormatterServiceProvider::class,
],

'aliases' => [
    // ...
    'MoneyFormatter' => Nwidart\MoneyFormatter\Facades\MoneyFormatter::class,
],

Publish the config file — this is the first place you should look, because the per-currency format rules live there, not in code:

php artisan vendor:publish --provider="Nwidart\MoneyFormatter\MoneyFormatterServiceProvider"

You'll get a config/money-formatter.php (or similarly named) file keyed by currency code, with symbol, symbol position, decimal count, thousands separator, and decimal separator. Read this file before writing any code — every behaviour you care about is data-driven from it.

First use case: you have a moneyphp/money Money object (or a raw minor-unit integer plus a currency code) and you want a human-readable string for a Blade view or API response:

use Money\Money;
use Money\Currency;

$price = new Money(123456, new Currency('USD'));

echo MoneyFormatter::format($price);       // $1,234.56
echo MoneyFormatter::format($price, 'USD'); // if formatting from a raw int

If the output is wrong, the config file is almost always the culprit before the code is.

Implementation Patterns

Format only at the edges. Never store formatted strings. Keep amounts as integers (minor units) in the database and as Money objects in your domain layer; call the formatter in Blade, in API resources, or in mail templates. This is the single most important discipline with this package.

Blade usage. Inject via the facade or a small view composer rather than calling the facade directly from templates if you want testability:

{{ MoneyFormatter::format($order->total) }}

API resources / presenters. Format once in an OrderResource and expose both a raw and a formatted value so clients aren't locked to your locale:

return [
    'total'         => $order->total->getAmount(),      // "123456"
    'total_display' => MoneyFormatter::format($order->total),
];

Per-request currency. If your app is multi-currency, set the currency on the Money object itself (that's how the package resolves which config row to use) rather than mutating global config. If you do need to override formatting at runtime, merge config before rendering:

config(['money-formatter.EUR.decimals' => 2]);

Add new currencies by editing config, not code. Adding JPY with zero decimals or BHD with three is a config edit. This is the package's real selling point — a single data file for formatting rules across dozens of currencies.

Pair with moneyphp/money for arithmetic. The formatter does not do math, allocation, or currency conversion. Use Money::add, Money::multiply, and Money::allocate for the logic, then hand the resulting Money to the formatter for output.

Testing. Because formatting is config-driven, snapshot-test a handful of currencies (USD, EUR, JPY, and one with a non-ASCII symbol) in a unit test. That's your regression net if you later swap the package out.

Gotchas and Tips

This package is effectively abandoned (last release March 2015, single-digit stars). That means: no PHP 8 compatibility work, no illuminate/support constraint bumps, and a service provider written against the Laravel 4/5 container API (watch for bindShared, which was removed in 5.4 — you may need to patch or fork). Treat it as a config-file-with-a-facade rather than infrastructure. If you're starting fresh, moneyphp/money's own formatters, brick/money, or PHP's intl NumberFormatter will serve you better; this package's only real value is the curated per-currency config table, which you can copy into your own code in an hour.

Verify the method signature against the source. The README is thin; check src/ for whether format() takes a Money object, a string currency code, or both before wiring it into templates.

Config caching. After editing the currency table, run php artisan config:clear in development. On production deploys with config:cache, a stale format table is the most common "why is my price formatted wrong" bug.

Missing currency key = silent fallback or exception. Decide which, and wrap calls in a helper that asserts the currency exists, so a typo in a currency code doesn't quietly render the wrong symbol.

Display ≠ storage ≠ rounding. Formatting rounds for display only. Do not feed formatted output back into calculations or comparisons.

Locale assumptions. Thousands/decimal separators come from your config table, not from setlocale() or Intl. If you need true locale-aware formatting (Arabic, Indian grouping, etc.), this package will not get you there.

Extension points. The formatter is bound in the service provider; rebind it in your own provider to swap in a wrapper class (useful for adding caching, logging, or a formatCents() convenience method). Extend the facade the same way. For anything non-trivial, subclass rather than editing the vendor directory.

Debugging checklist: (1) is the provider registered and the facade aliased? (2) does config('money-formatter') return the array you expect in php artisan tinker? (3) does the currency key exactly match the ISO code case used in your Money object? (4) is config cached? Work that list in order — it resolves nearly every issue with this package.