devhammed/laravel-brick-money

Laravel Brick Money Integration

1.0.0 2025-12-03 18:09 UTC

Requires

• php: ^8.2
• brick/money: ^0.10.0
• illuminate/contracts: ^10.0||^11.0||^12.0
• spatie/laravel-package-tools: ^1.13.0

Requires (Dev)

• ext-intl: *
• larastan/larastan: ^2.0||^3.0
• laravel/pint: ^1.14
• livewire/livewire: ^3.0
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^8.22.0||^9.0.0||^10.0.0
• pestphp/pest: ^2.0||^3.0||^4.0
• pestphp/pest-plugin-arch: ^2.0||^3.0||^4.0
• pestphp/pest-plugin-laravel: ^2.0||^3.0||^4.0
• pestphp/pest-plugin-livewire: ^2.0||^3.0||^4.0
• phpstan/extension-installer: ^1.3||^2.0
• phpstan/phpstan-deprecation-rules: ^1.1||^2.0
• phpstan/phpstan-phpunit: ^1.3||^2.0

Suggests

• ext-intl: Required to format Money objects.
• livewire/livewire: Required to use Livewire Synthesizers.

MIT

• Hammed Oyedele

• money
• laravel
• brick

README

Table of Contents

• Introduction
• Installation
• Configuration
• Usage
  • Available Methods
  • Eloquent
    • IntegerMoneyCast
    • DecimalMoneyCast
    • CurrencyCast
  • HTTP
    • Request Macros
    • Validation Rules
  • Helpers
  • Views
    • Components
    • Directives
  • Extensions
    • Macros
    • Mixins
• Testing
• Changelog
• Security
• Credits
• License

Introduction

This package provides the Laravel integration of Brick/Money.

Installation

Install via Composer:

composer require devhammed/laravel-brick-money

Configuration

Publish the configuration file if you need to customize defaults:

php artisan vendor:publish --tag="brick-money-config"

You can view the contents of the default configuration in config/brick-money.php

Usage

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Currency;

echo Money::of(100); // '$100.00'

echo Money::of(100, Currency::of('EUR')); // '€100,00'

echo Money::of(100, 'USD'); // '$100.00'

echo Money::ofMinor(100); // '$1.00'

echo Money::ofMinor(100, 'EUR'); // '€1,00'

Available Methods

The package has tried to wrap as many brick/money package methods as possible but if you encounter a method that we haven't wrapped yet, you can get the underlying instance by calling ->getMoney() on Money or ->getCurrency() on Currency and call it directly:

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Currency;

$usd = Currency::of('USD');
$eur = Currency::of('EUR');
$total = Money::of(1000, $usd);
$tax = Money::of(100, $usd);

// Money methods
$total->getCurrency(); // Devhammed\LaravelBrickMoney\Currency{}
$total->getMoney(); // Brick\Money\Money{}
$total->getContext(); // Brick\Money\Context\DefaultContext{}
$total->getAmount(); // Brick\Math\BigDecimal{}
$total->getMinorAmount(); // Brick\Math\BigDecimal{}
$total->getUnscaledAmount(); // Brick\Math\BigInteger{}
$total->getSign(); // 1
$total->isZero(); // false
$total->isNegative(); // false
$total->isNegativeOrZero(); // false
$total->isPositive(); // true
$total->isPositiveOrZero(); // true
$total->compareTo($tax); // 1
$total->isEqualTo($tax); // false
$total->isLessThan($tax); // false
$total->isLessThanOrEqualTo($tax); // false
$total->isGreaterThan($tax); // true
$total->isGreaterThanOrEqualTo($tax); // true
$total->plus($tax); // $1,100
$total->minus($tax); // $900
$total->multipliedBy(2); // $2,000
$total->dividedBy(2); // $500
$total->allocate(1, 2, 3);
$total->split(2); // [$500, $500]
$total->splitWithRemainder(3); // [$33.33, $33.33, $33.33, $0.01]
$total->abs(); // $1,000
$total->negated(); // -$1,000
$total->format(); // "$1,000"

# Currency methods
$usd->getCode(); // "USD"
$usd->getName(); // "US Dollar"
$usd->getNumericCode(); // 840
$usd->getSymbol(); // $
$usd->isSymbolFirst(); // true
$usd->isSymbolSpaced(); // false
$usd->getDecimalPlaces(); // 2
$usd->getDecimalSeparator(); // "."
$usd->getThousandSeparator(); // ","
$usd->getPrefix(); // "$"
$usd->getSuffix(); // ""
$usd->getCurrency(); // Brick\Money\Currency{}
$usd->is($eur); // false

Eloquent

This package provides Model casts to help with money and currency storage in the database.

There are currently two supported storage cast types, and each of them support either storing in a single JSON column or separate amount and currency columns:

IntegerMoneyCast (Recommended)

This stores the amount in the currency's minor unit.

Example Model:

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Casts\IntegerMoneyCast;

/**
 * @property Money $amount
 * @property string $currency
 * @property Money $tax
 */
class Transaction extends Model
{
    protected function casts(): array
    {
        return [
            'amount' => IntegerMoneyCast::make('currency'),
            'tax' => IntegerMoneyCast::make(),
        ];
    }
}

Example Migration:

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;

Schema::create('transactions', function (Blueprint $table) {
    $table->id();

    $table->bigInteger('amount');   // e.g., 1000 = $10.00,
    $table->string('currency');  // currency code e.g. USD
    $table->json('tax'); // {"amount": "2345", "currency": "TRX"}

    $table->timestamps();
});

Some cryptocurrencies, particularly those with very high precision (e.g., ETH uses 18 decimal places) will exceed the limit of ->bigInteger() so it is recommended to use ->string() in this case when you are using the separate columns mode.

DecimalMoneyCast

This stores the amount in the currency's major unit.

Example Model:

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Casts\DecimalMoneyCast;

/**
 * @property Money $amount
 * @property string $currency
 * @property Money $tax
 */
class Transaction extends Model
{
    protected function casts(): array
    {
        return [
            'amount' => DecimalMoneyCast::make('currency'),
            'tax' => DecimalMoneyCast::make(),
        ];
    }
}

Example Migration:

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;

Schema::create('transactions', function (Blueprint $table) {
    $table->id();

    $table->decimal('amount', 36, 18);  // e.g., 10.00 = $10.00,
    $table->string('currency');  // currency code e.g. USD
    $table->json('tax'); // {"amount": "23.45", "currency": "TRX"}

    $table->timestamps();
});

The reason for using DECIMAL(36, 18) in the separate column example is to accommodate cryptocurrencies with very high precision like ETH that uses 18 decimal places, you can reduce or increase the scale and precision to match your project requirements.

CurrencyCast

This is useful for casting currency columns to Currency.

Example Model:

use Devhammed\LaravelBrickMoney\Currency;
use Devhammed\LaravelBrickMoney\Casts\CurrencyCast;

/**
 * @property Currency $currency
 */
class Transaction extends Model
{
    protected function casts(): array
    {
        return [
            'currency' => CurrencyCast::make(),
        ];
    }
}

Example Migration:

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;

Schema::create('transactions', function (Blueprint $table) {
    $table->id();
    $table->string('currency');  // currency code e.g. USD
    $table->timestamps();
});

This can also be used in conjunction with the currency column of the amount casts explained above.

HTTP

This package provides request macros and validation rules to work with money/currency in HTTP Requests.

Request Macros

request()->currency('currency'); // Devhammed\LaravelBrickMoney\Currency{}

request()->money('price'); // Devhammed\LaravelBrickMoney\Money{}

request()->money('price', currency: 'EUR', minor: true); // Devhammed\LaravelBrickMoney\Money{}

Validation Rules

namespace App\Http\Requests;

use Devhammed\LaravelBrickMoney\Rules\MoneyRule;
use Devhammed\LaravelBrickMoney\Rules\CurrencyRule;
use Illuminate\Foundation\Http\FormRequest;

class CreateProductRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'price' => [
                'required',
                new MoneyRule(
                    min: 0,
                    max: 1000,
                ),
            ],
            'currency' => [
                'required',
                new CurrencyRule(),
            ],
        ];
    }
}

Helpers

money(100) // $100.00

money(100, minor: true) // $1.00

money(100, 'EUR') // €100,00

currency('USD') // USD

Views

This package provides helpers to work with money and currency in Blade templates.

Components

<x-money amount="100"/> <!-- $100.00 -->

<x-money amount="100" currency="USD"/> <!-- $100.00 -->

<x-money amount="100" currency="USD" minor/> <!-- $1.00 -->

<x-currency currency="USD"/> <!-- USD -->

Directives

@money(100) // $100.00

@money(100, minor: true) // $1.00

@money(100, 'EUR') // €100,00

@currency('USD') // USD

Extensions

The Money and Currency classes implements the Laravel Macroable trait, allowing you to add custom functionalities through macros and mixins.

Macros

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Currency;

Money::macro('zero', fn(Currency|string $currency) => Money::of(0, $currency));

Money::macro('withPercentage', function (float $percentage): Money {
    return $this->multipliedBy(1 + ($percentage / 100));
});

Money::zero()->plus(100)->withPercentage(10); // $110

Mixins

And with mixins, you can achieve the same thing using a dedicated class:

use Devhammed\LaravelBrickMoney\Money;
use Devhammed\LaravelBrickMoney\Currency;

class MoneyExtensions
{
    public static function zero(Currency|string $currency): Money
    {
        return Money::of(0, $currency);
    }
    
    public function withPercentage(float $percentage): Money
    {
        return $this->multipliedBy(1 + ($percentage / 100));
    }
}

Money::mixin(new MoneyExtensions());

Money::zero()->plus(100)->withPercentage(10); // $110

Testing

Run the test suite:

composer test

Changelog

See the CHANGELOG for a full history of updates.

Security

If you discover a security vulnerability, please refer to the security policy.

Credits

• Hammed Oyedele
• All Contributors

License

This package is open-source software released under the MIT License.

See LICENSE.md for details.