Download the PHP package joseftraxler/laravel-money without Composer

Laravel Money

A lightweight Laravel package for working with money values, currencies, formatting, arithmetic operations, and Eloquent casts.

Laravel Money provides a small immutable Money value object with currency-aware precision handling and convenient integration for Laravel applications.

Features

• Immutable Money value object
• ISO 4217-style currency code validation
• Currency-specific precision support
• Decimal and cents-based factory methods
• Arithmetic operations powered by moneyphp/money
• Human-readable formatting using PHP intl
• Eloquent casts for decimal and cents database columns
• Support for fixed currency and currency-column casts
• Laravel auto-discovery
• Publishable configuration

Requirements

• PHP 8.4+
• Laravel 12+
• PHP intl extension

Installation

Install the package via Composer:

The service provider is registered automatically through Laravel package discovery.

Configuration

The package works without publishing configuration. If you want to customize default currency or precision settings, publish the config file:

This publishes: config/money.php

Example configuration:

Basic usage

In Blade:

Currency codes are strict ISO 4217-style codes. They must contain exactly three letters.

Currency precision

Precision is resolved in this order:

1. money.currencies.{CODE}.precision
2. money.default_precision
3. package-detected default precision

Precision values are validated and cached per currency for performance.

⚠️ When a decimal string value contains more fractional digits than the currency precision allows, the value is truncated to the configured precision. Float values are instead rounded to the configured precision, which compensates for binary floating-point representation (e.g. the float 1.15 is stored as 1.1499999…, so truncation would yield "1.14").

Creating money values

From decimal

From cents

Numeric strings are recommended

The package accepts integers, floats, and numeric strings for convenience:

For exact monetary input, prefer numeric strings:

Using custom currency class/enum

You can also use a custom currency class/enum that implements JosefTraxler\LaravelMoney\Contracts\Currencyable:

or some model e.g.:

Arithmetic

Money values support common arithmetic operations.

Arithmetic operations are currency-aware and delegated to moneyphp/money.

Comparisons

Predicates are also available:

Formatting

In Laravel Blade, money values are automatically formatted according to the current locale.

For example, in en_US, this may render as €12.35:

Formatting uses PHP NumberFormatter, so the intl extension is required.

You can specify a custom locale:

For cs_CZ, this may render as 12,34 €.

Eloquent casts

Laravel Money provides casts for storing money values as decimal or cents.

Cast definitions are specified by:

• currency code source
  • fixed: defined by a three-letter uppercase currency code
  • dynamic: defined by a currency column name
• amount source
  • decimal: amount in major units
  • cents: amount in minor units

Fixed currency decimal cast

Use this when the database column stores only the decimal amount and the currency is fixed:

Usage:

⚠️ When using a fixed currency cast, assigning a Money instance with a different currency throws MoneyMismatchCurrencyException.

Dynamic currency column

Use this when the amount and currency are stored in separate columns:

Usage:

When using a dynamic currency column, the package stores the currency code automatically.

When assigning null to a money attribute using a dynamic currency column, only the amount column is set to null. The currency column is preserved intentionally, because the same currency column may be shared by multiple money attributes.

Cents storage

If you store money as cents, pass cents as the second-cast argument:

The example below stores 1999 in amount_in_cents and "EUR" in currency:

When retrieving the value, the package automatically converts cents to Money using Money::fromCents().

Design notes

Strict currency codes

Currency codes are validated as three-letter ISO 4217-style codes. Whitespace is not trimmed automatically. This is intentional: invalid or unnormalized input should be handled before creating a currency value.

Precision caching

Currency precision is resolved from configuration and cached per currency code. This keeps the package efficient when many money objects are created during a request.

Decimal normalization

Money amounts are normalized according to currency precision:

Testing

Run the test suite:

Run static analysis:

Check code style:

Fix code style:

Contributing

Contributions are welcome.

Before opening a pull request, please ensure:

• tests pass: composer test
• code style passes: composer cs
• static analysis passes: composer stan

License

MIT License © Josef Traxler

See the LICENSE file for details.

Support

• Issues: GitHub Issues
• Source: GitHub Repository