Laravel Money Laravel Package

Getting Started

• Install with composer require finller/laravel-money. The package wraps brick/money, so ext-bcmath is required in local, CI, and production environments.
• Publish and inspect the config first: php artisan vendor:publish --tag="laravel-money-config". Set default_currency and default_context explicitly; do not rely on implicit defaults across environments.
• Read these files before writing app code: the package Money class, the Eloquent casts, the validation rules, and config/laravel-money.php. Because the package is thin, also keep the Brick/Money docs open for rounding, contexts, and formatting behavior.
• The quickest useful integration is an Eloquent cast plus a validated form request:

// config/laravel-money.php
return [
    'default_currency' => 'USD',
    'default_context' => Brick\Money\Context\DefaultContext::class,
];

use Finller\Money\Casts\AsMoney;

class Order extends Model
{
    protected $casts = [
        'total' => AsMoney::class,
    ];
}

use Finller\Money\Money;

$order = Order::create([
    'total' => Money::of('19.99', 'USD'),
]);

$order->total->formatTo('en_US'); // "$19.99"

That covers the first day-to-day use case: store a monetary value, retrieve it as a value object, and render it without floats.

Implementation Patterns

• Parse only at boundaries. Accept raw strings from HTTP, CSV, or admin input, convert immediately with the package parser, and keep Money objects inside the domain. Do not pass request strings through several layers.

use Finller\Money\Money;

$money = Money::parse($request->input('total'), 'USD');

• Validate before conversion. Use the package rule in form requests, then convert. This avoids duplicate parsing logic in controllers.

use Finller\Money\Rules\MoneyRule;

$validated = $request->validate([
    'total' => ['required', new MoneyRule()],
]);

$order->total = Money::of($validated['total'], 'USD');

• Use casts as the persistence boundary. AsMoney keeps model attributes as value objects and handles serialization. If the app supports multiple currencies per record, use the package’s money-bag cast where available, or store a currency column and construct Money explicitly.
• Prefer Brick operations over manual arithmetic. plus(), minus(), multipliedBy(), and allocate() are immutable and context-aware. Use isEqualTo(), isGreaterThan(), etc. instead of loose comparisons.
• Set the context deliberately. DefaultContext allows fractional minor units; CashContext rounds to cash increments. Pick one per currency and keep it consistent between writes and reads.
• Format in the presentation layer, not in the database. Use formatTo($locale) in Blade/API resources, or use Brick’s IntlMoneyFormatter when you need full control. Return a string and, if needed, a minor-unit integer in APIs—never a float.
• Test with explicit config. In tests, set the default currency/context in phpunit.xml or TestCase setup so behavior does not depend on a developer’s local .env.
• Wrap the package lightly. Keep a small application-level adapter for parsing, formatting, and persistence if you expect to change money libraries later. The package is small and young; an adapter limits lock-in.

Gotchas and Tips

• ext-bcmath is non-negotiable. Missing bcmath is the most common install-time failure. Add it to Docker images and CI setup.
• Never construct money from floats. Money::of(0.1 + 0.2, 'USD') produces the wrong amount. Use strings like '0.30' or integer minor units.
• Context mismatch changes values. Writing with DefaultContext and reading with CashContext can round or throw. Configure one default and use it everywhere.
• Default currency drift is dangerous. If persisted rows do not carry a currency, changing default_currency silently reinterprets historical data. Store currency explicitly for anything multi-currency.
• Cast serialization is a schema decision. Confirm how AsMoney writes to the column—typically a string such as "USD 19.99". Treat that format as part of your database contract; changing cast versions or serialization requires a backfill.
• Parsing and validation may not agree. Test round-trips for inputs like "1,234.56", "1.234,56", "$10", and negative values. Locale-dependent parsing is ambiguous; prefer ISO currency codes and machine-readable amounts.
• Formatting is locale-sensitive. formatTo('en_US') and formatTo('de_DE') produce different separators. Do not format once and parse the formatted string back.
• Immutability surprises. $money->plus($tax) returns a new object; it does not mutate $money. Reassign the result.
• Money bags need explicit currency access. When summing mixed currencies, retrieve per-currency amounts rather than assuming a single total.
• Pin the version and check compatibility. The package has low adoption and a small surface area. Pin a known tag, confirm Laravel/PHP/Brick version constraints, and read the cast and rule source before relying on edge-case behavior.
• Keep validation messages user-friendly. The package rule validates money shape; add custom messages for currency and amount errors so API clients get actionable feedback.
• Debug by dumping the value object, not the cast attribute. dd($model->total) shows the Money object; inspect (string) $model->total, getAmount(), getCurrency(), and getContext() when persistence looks wrong.