Download the PHP package leancaptain/lara-money without Composer

Lara Money

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:

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:

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:

This publishes:

MoneyFactory

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

You can resolve it normally:

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

Constructor injection works as expected:

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:

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

Currency resolution

MoneyCast resolves the currency for a money attribute using a three-layer strategy, checked in this order:

1. Explicit currency attribute — A column name passed to the cast constructor.
2. Auto-detected currency column — A column named currency on the model, used automatically.
3. Application default — The default currency from config('money.php').

The first match wins. This means a model with a currency column will use it automatically without any explicit configuration.

Using the default currency

If your model does not have a currency column and does not need a per-record currency, use the cast directly:

If the database contains:

and the configured currency is USD, reading:

returns a Money representing:

No currency column is required.

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

Auto-detecting a currency column

If your model has a column named currency, MoneyCast detects it automatically:

Given:

the cast returns a Money using Currency::EUR without any explicit currency attribute configuration.

This works because MoneyCast checks for the presence of a currency key in the model's attributes and uses it when no explicit attribute is specified.

Explicit currency attribute

For multi-currency models where the column is not named currency, pass the attribute name to the cast:

For example:

the cast returns a Money using Currency::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.

Currency resolution flow

Assigning monetary values

The cast accepts:

• Money
• integer major-unit values
• decimal strings
• null

Decimal strings

For a two-decimal currency, the database stores:

Integers

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

For a two-decimal currency, this stores:

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

Money values

You can assign a Money object directly:

The cast persists its integer minor-unit representation.

Null

Nullable monetary attributes remain nullable:

is stored as:

null is not converted to zero money.

Floats

Floating-point monetary input is intentionally not supported:

Use a decimal string instead:

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:

is invalid.

Likewise, for a multi-currency model:

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:

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:

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

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:

The built-in list is deliberately curated.

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:

The default is:

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

Design Philosophy

lara-money is intentionally a thin adapter.

The dependency direction is:

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:

License

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