Formatting

Overview

Laravel Brick Money provides powerful formatting capabilities to display money values in different formats, locales, and styles. You can use simple formatting or advanced locale-aware formatting with full NumberFormatter customization.

Basic Formatting

The format() method provides simple, currency-aware formatting:

use Devhammed\LaravelBrickMoney\Money;

$usd = Money::of(1000, 'USD');
echo $usd->format(); // "$1,000.00"

$eur = Money::of(1000, 'EUR');
echo $eur->format(); // "€1.000,00"

$jpy = Money::of(1000, 'JPY');
echo $jpy->format(); // "¥1,000"

Format Configuration

The basic format() method uses currency-specific settings:

Symbol Position

Automatically positions symbol before or after the amount based on currency conventions

Symbol Spacing

Adds space between symbol and amount when appropriate (e.g., “EUR 100,00”)

Decimal Separator

Uses . for USD, , for EUR, etc.

Thousands Separator

Uses , for USD, . for EUR, etc.

Whole Number Formatting

You can optionally hide decimal places for whole numbers:

$price = Money::of(100, 'USD');

echo $price->format(); // "$100.00"
echo $price->format(allowWholeNumber: true); // "$100"

$decimal = Money::of(100.50, 'USD');
echo $decimal->format(allowWholeNumber: true); // "$100.50" (still shows decimals)

Locale-Aware Formatting

The formatLocale() method uses PHP’s NumberFormatter for internationalized formatting:

Basic Locale Formatting

$price = Money::of(1234.56, 'USD');

// Different locales
echo $price->formatLocale('en_US'); // "$1,234.56"
echo $price->formatLocale('de_DE'); // "1.234,56 $"
echo $price->formatLocale('fr_FR'); // "1 234,56 $US"
echo $price->formatLocale('ja_JP'); // "$1,234.56"

Default Locale

Set a default locale for all formatting:

Money::locale('de_DE');

$price = Money::of(1000, 'EUR');
echo $price->formatLocale(); // Uses 'de_DE' locale

Set in a service provider:

namespace App\Providers;

use Devhammed\LaravelBrickMoney\Money;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Money::locale(config('app.locale'));
    }
}

Locale with Whole Numbers

$price = Money::of(100, 'USD');

echo $price->formatLocale('en_US'); // "$100.00"
echo $price->formatLocale('en_US', allowWholeNumber: true); // "$100"

NumberFormatter Customization

You can customize the NumberFormatter with a callback for advanced formatting needs:

Custom Number Format Attributes

Accounting Format
No Grouping
Custom Decimals
Padding

$price = Money::of(-1000, 'USD');

$formatted = $price->formatLocale('en_US', callback: function ($formatter) {
    // Show negative numbers in parentheses
    $formatter->setTextAttribute(
        NumberFormatter::NEGATIVE_PREFIX, 
        '('
    );
    $formatter->setTextAttribute(
        NumberFormatter::NEGATIVE_SUFFIX, 
        ')'
    );
});

echo $formatted; // "($1,000.00)"

$price = Money::of(1000000, 'USD');

$formatted = $price->formatLocale('en_US', callback: function ($formatter) {
    // Remove thousands separator
    $formatter->setAttribute(
        NumberFormatter::GROUPING_USED, 
        0
    );
});

echo $formatted; // "$1000000.00"

$price = Money::of(100, 'USD');

$formatted = $price->formatLocale('en_US', callback: function ($formatter) {
    // Force 4 decimal places
    $formatter->setAttribute(
        NumberFormatter::MIN_FRACTION_DIGITS, 
        4
    );
    $formatter->setAttribute(
        NumberFormatter::MAX_FRACTION_DIGITS, 
        4
    );
});

echo $formatted; // "$100.0000"

$price = Money::of(42, 'USD');

$formatted = $price->formatLocale('en_US', callback: function ($formatter) {
    // Pad with zeros to 10 characters
    $formatter->setAttribute(
        NumberFormatter::FORMAT_WIDTH, 
        10
    );
    $formatter->setTextAttribute(
        NumberFormatter::PADDING_CHARACTER, 
        '0'
    );
});

echo $formatted; // "$000042.00"

Practical Formatting Examples

Price Display Component

use Devhammed\LaravelBrickMoney\Money;

class PriceDisplay
{
    public function __construct(
        private Money $price,
        private string $locale = 'en_US'
    ) {}
    
    public function format(): string
    {
        return $this->price->formatLocale($this->locale);
    }
    
    public function formatCompact(): string
    {
        return $this->price->formatLocale(
            $this->locale, 
            allowWholeNumber: true
        );
    }
    
    public function formatAccounting(): string
    {
        return $this->price->formatLocale(
            $this->locale,
            callback: function ($formatter) {
                $formatter->setTextAttribute(
                    NumberFormatter::NEGATIVE_PREFIX, 
                    '('
                );
                $formatter->setTextAttribute(
                    NumberFormatter::NEGATIVE_SUFFIX, 
                    ')'
                );
            }
        );
    }
}

Multi-Currency Invoice

class Invoice
{
    private array $items = [];
    private string $locale;
    
    public function addItem(string $description, Money $price)
    {
        $this->items[] = [
            'description' => $description,
            'price' => $price,
        ];
    }
    
    public function render(): string
    {
        $output = "Invoice\n" . str_repeat('=', 50) . "\n\n";
        
        foreach ($this->items as $item) {
            $output .= sprintf(
                "%-30s %s\n",
                $item['description'],
                $item['price']->formatLocale($this->locale)
            );
        }
        
        return $output;
    }
}

$invoice = new Invoice();
$invoice->addItem('Product A', Money::of(99.99, 'USD'));
$invoice->addItem('Product B', Money::of(149.50, 'USD'));
echo $invoice->render();

Cryptocurrency Formatting

$btc = Money::of(0.00123456, 'BTC');

// Show all 8 decimal places for Bitcoin
$formatted = $btc->formatLocale('en_US', callback: function ($formatter) {
    $formatter->setAttribute(NumberFormatter::MIN_FRACTION_DIGITS, 8);
    $formatter->setAttribute(NumberFormatter::MAX_FRACTION_DIGITS, 8);
});

echo $formatted; // "₿0.00123456"

View Integration

Blade Directives

{{-- Basic formatting --}}
@money(100, 'USD') {{-- $100.00 --}}

{{-- With locale --}}
{{ money(1000, 'EUR')->formatLocale('de_DE') }} {{-- 1.000,00 € --}}

{{-- Whole number --}}
{{ money(100, 'USD')->format(true) }} {{-- $100 --}}

Blade Components

<x-money :amount="100" currency="USD" />

<x-money :amount="100" currency="USD" locale="de_DE" />

<x-money :amount="100" currency="USD" :whole-number="true" />

Comparison of Format Methods

Feature	format()	formatLocale()
Performance	Faster (uses number_format)	Slower (uses NumberFormatter)
Locale Support	Basic (currency settings)	Full (NumberFormatter)
Customization	Limited	Extensive (callback)
Best For	Simple display, APIs	User-facing interfaces

Use format() for APIs and simple displays. Use formatLocale() when you need proper internationalization or custom formatting rules.

Best Practices

Choose the Right Method

Use format() for consistent, fast formatting
Use formatLocale() when displaying to users in different locales
Use formatLocale() with callback for accounting or special formats

Performance Considerations

formatLocale() creates a new NumberFormatter instance on each call. For bulk formatting, consider caching the formatter:

$formatter = new NumberFormatter('en_US', NumberFormatter::CURRENCY);

foreach ($prices as $price) {
    // Reuse the same formatter
    echo $formatter->formatCurrency(
        $price->getAmount()->toFloat(), 
        $price->getCurrency()->getCode()
    );
}

Floating Point Precision

Both methods use toFloat() internally, which can introduce precision errors for very large amounts. For large values, consider custom formatting:

// For very large amounts, use string manipulation
$amount = (string) $money->getAmount();
$symbol = $money->getCurrency()->getSymbol();
echo "{$symbol}{$amount}";

Locale String Format

Always use underscores in locale strings (en_US), not hyphens (en-US). The package automatically converts hyphens:

Money::locale('en-US'); // Automatically converted to 'en_US'

Getting Started

Core Concepts

Eloquent Integration

HTTP Integration

Views

Advanced

API Reference

Overview

Basic Formatting

Format Configuration

Symbol Position

Symbol Spacing

Decimal Separator

Thousands Separator

Whole Number Formatting

Locale-Aware Formatting

Basic Locale Formatting

Default Locale

Locale with Whole Numbers

NumberFormatter Customization

Custom Number Format Attributes

Practical Formatting Examples

Price Display Component

Multi-Currency Invoice

Cryptocurrency Formatting

View Integration

Blade Directives

Blade Components

Comparison of Format Methods

Best Practices

Next Steps

Extensions

JSON Serialization

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Eloquent Integration

HTTP Integration

Views

Advanced

API Reference

Documentation Index

​Overview

​Basic Formatting

​Format Configuration

Symbol Position

Symbol Spacing

Decimal Separator

Thousands Separator

​Whole Number Formatting

​Locale-Aware Formatting

​Basic Locale Formatting

​Default Locale

​Locale with Whole Numbers

​NumberFormatter Customization

​Custom Number Format Attributes

​Practical Formatting Examples

​Price Display Component

​Multi-Currency Invoice

​Cryptocurrency Formatting

​View Integration

​Blade Directives

​Blade Components

​Comparison of Format Methods

​Best Practices

​Next Steps

Extensions

JSON Serialization

Build docs developers (and LLMs) love

Overview

Basic Formatting

Format Configuration

Whole Number Formatting

Locale-Aware Formatting

Basic Locale Formatting

Default Locale

Locale with Whole Numbers

NumberFormatter Customization

Custom Number Format Attributes

Practical Formatting Examples

Price Display Component

Multi-Currency Invoice

Cryptocurrency Formatting

View Integration

Blade Directives

Blade Components

Comparison of Format Methods

Best Practices

Next Steps