README

A thin Laravel integration for leancaptain/money.

leancaptain/lara-money brings the framework-agnostic Money value object into Laravel with Eloquent casting, container integration, configurable defaults, and support for application-defined currencies.

The core money implementation remains in leancaptain/money. This package only provides the Laravel integration layer.

Requirements

PHP 8.4+
Laravel 13+
leancaptain/money 0.0.x

Installation

Install the package via Composer:

composer require leancaptain/lara-money

The service provider is discovered automatically by Laravel.

No configuration needs to be published for the package to work.

Configuration

The package provides a sensible default configuration:

use LeanCaptain\Money\Currency;
use LeanCaptain\Money\RoundingMode;

return [
    'currency' => Currency::USD,
    'rounding_mode' => RoundingMode::REJECT,
];

The default currency is used whenever a money cast does not specify a currency attribute.

The default rounding mode is used when monetary input needs to be parsed through the configured MoneyFactory.

Publishing the configuration

Publishing is optional.

If you want to customize the package configuration:

php artisan vendor:publish --tag=lara-money-config

This publishes:

config/money.php

MoneyFactory

The package registers LeanCaptain\Money\MoneyFactory as a singleton in Laravel's service container.

You can resolve it normally:

use LeanCaptain\Money\MoneyFactory;

$factory = app(MoneyFactory::class);

$money = $factory->of('125.50');

The factory uses the currency and rounding mode configured in config/money.php.

Constructor injection works as expected:

use LeanCaptain\Money\MoneyFactory;

final class InvoiceService
{
    public function __construct(
        private MoneyFactory $money,
    ) {}
}

Eloquent Money Cast

MoneyCast stores monetary values as integer minor units while exposing them as immutable Money value objects in your application.

For a currency with two minor-unit decimal places:

125.50 → 12550

No floating-point representation is used for monetary storage or parsing.

Using the default currency

If your model does not need a currency column, use the cast directly:

use LeanCaptain\LaraMoney\Casts\MoneyCast;

protected function casts(): array
{
    return [
        'amount' => MoneyCast::class,
    ];
}

If the database contains:

amount = 12550

and the configured currency is BDT, reading:

$model->amount;

returns a Money representing:

BDT 125.50

No currency column is required.

This is useful for applications or models that operate in a single known currency.

Per-record currencies

For multi-currency models, pass the currency attribute name to the cast:

protected function casts(): array
{
    return [
        'amount' => MoneyCast::class.':currency',
    ];
}

Given:

amount   = 12550
currency = USD

the cast returns a Money using Currency::USD.

The currency attribute name is configurable:

protected function casts(): array
{
    return [
        'amount' => MoneyCast::class.':currency_code',
    ];
}

For example:

amount        = 12550
currency_code = EUR

When a currency attribute is explicitly configured, it must contain a valid currency code. The cast does not silently fall back to the application's default currency when the explicit currency is missing or invalid.

Assigning monetary values

The cast accepts:

Money
integer major-unit values
decimal strings
null

Decimal strings

$model->amount = '125.50';

For a two-decimal currency, the database stores:

Integers

Integers follow the semantics of leancaptain/money and represent major units:

$model->amount = 125;

For a two-decimal currency, this stores:

If you need to work explicitly with minor units, construct a Money value first:

use LeanCaptain\Money\Currency;
use LeanCaptain\Money\Money;

$model->amount = Money::fromMinor(
    12550,
    Currency::BDT,
);

Money values

You can assign a Money object directly:

use LeanCaptain\Money\Currency;
use LeanCaptain\Money\Money;

$model->amount = Money::of(
    '125.50',
    Currency::BDT,
);

The cast persists its integer minor-unit representation.

Null

Nullable monetary attributes remain nullable:

$model->amount = null;

is stored as:

NULL

null is not converted to zero money.

Floats

Floating-point monetary input is intentionally not supported:

$model->amount = 125.50; // rejected

Use a decimal string instead:

$model->amount = '125.50';

This preserves the strict monetary semantics of leancaptain/money and avoids floating-point ambiguity.

Currency safety

The cast does not perform currency conversion.

If a model uses the default currency, assigning a Money object with another currency is rejected.

For example, if the configured currency is BDT:

$model->amount = Money::of('100', Currency::USD);

is invalid.

Likewise, for a multi-currency model:

currency = USD

assigning EUR money is rejected rather than silently changing the currency or treating EUR minor units as USD.

Currency conversion and foreign-exchange behavior are intentionally outside the scope of this package.

Custom currencies

leancaptain/money supports application-defined currencies through CurrencyContract.

lara-money preserves that extensibility.

For a single/default custom currency, configure any implementation of:

use LeanCaptain\Money\Contracts\CurrencyContract;

interface CurrencyContract
{
    public function code(): string;

    public function minorUnit(): int;
}

as the application's default currency.

For multi-currency models using stored currency codes, lara-money provides a CurrencyResolver extension point.

The default resolver supports the currencies built into leancaptain/money.

If your application stores additional currencies, provide your own resolver:

use LeanCaptain\LaraMoney\Contracts\CurrencyResolver;
use LeanCaptain\Money\Contracts\CurrencyContract;

final class AppCurrencyResolver implements CurrencyResolver
{
    public function resolve(string $code): CurrencyContract
    {
        return AppCurrency::from($code);
    }
}

Then replace the default binding in your application's service provider:

use LeanCaptain\LaraMoney\Contracts\CurrencyResolver;

$this->app->singleton(
    CurrencyResolver::class,
    AppCurrencyResolver::class,
);

This allows applications to define their own currency domain without requiring changes to either leancaptain/money or leancaptain/lara-money.

Built-in currencies

The built-in currencies come from leancaptain/money:

BDT
USD
EUR
GBP
JPY

The built-in list is deliberately small.

Applications that need additional currencies can implement CurrencyContract rather than requiring the core package to maintain an exhaustive currency catalog.

Rounding

Rounding behavior comes directly from leancaptain/money.

Supported modes include:

RoundingMode::REJECT
RoundingMode::HALF_UP
RoundingMode::DOWN

The default is:

RoundingMode::REJECT

This package does not introduce separate Laravel-specific rounding semantics.

Design Philosophy

lara-money is intentionally a thin adapter.

The dependency direction is:

Laravel application
        ↓
leancaptain/lara-money
        ↓
leancaptain/money

The core package remains completely framework-agnostic.

This package aims to:

store money using integer minor units
avoid floating-point monetary input
preserve explicit rounding behavior
prevent silent currency mismatches
support single and multi-currency applications
support consumer-defined currencies
keep Laravel-specific concerns out of the core package
avoid unnecessary facades, helpers, and abstractions

For the underlying Money API, arithmetic, comparisons, rounding behavior, exceptions, and currency contracts, see leancaptain/money.

Testing

Run the package test suite with:

composer test

License

Lara Money is open-source software licensed under the MIT License.

leancaptain / lara-money

Maintainers

Package info

Statistics

Security