elegantly/laravel-money

Use Brick/Money in your Laravel app

v2.1.0 2024-10-21 14:29 UTC

README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

Easily use Brick/Money in your Laravel app.

Features

  • MoneyCast: Cast your model attributes to Brick\Money\Money
  • MoneyParse: Parse strings and other types to Brick\Money\Money
  • ValidMoney: Money validation rule

Upgrading to V2

Breaking cahnge

The namespace has been updated: from Finller\Money to Elegantly\Money. You can simply do a search+replace.

Installation

You can install the package via Composer:

composer require elegantly/laravel-money

You can publish the config file with:

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

This is the content of the published config file:

return [
    'default_currency' => 'USD',
];

Usage

Casting Using a Column as Currency (Recommended)

If you store the currency in a table column alongside the amount value, you can specify the column name like this:

use Elegantly\Money\MoneyCast;

/**
 * @property ?Money $price
 * @property ?string $currency
 **/
class Invoice extends Model {

    protected $casts = [
        'price' => MoneyCast::class . ':currency'
    ];

}

Casting Using a Defined Currency

You can cast your money to a specific currency using the currency code instead of the column name.

use Elegantly\Money\MoneyCast;

/**
 * @property ?Money $price
 * @property ?Money $cost
 **/
class Invoice extends Model {

    protected $casts = [
        'cost' => MoneyCast::class . ':EUR',
        'price' => MoneyCast::class . ':USD'
    ];

}

Parsing a Value to a Money Instance

You can parse any string/int/float to a money instance using MoneyParser.

Here are some examples of the expected behavior:

use Elegantly\Money\MoneyParser;

MoneyParser::parse(null, 'EUR'); // null

MoneyParser::parse(110, 'EUR'); // 110.00€
MoneyParser::parse(100.10, 'EUR'); // 100.10€

MoneyParser::parse('', 'EUR'); // null
MoneyParser::parse('1', 'EUR'); // 1.00€
MoneyParser::parse('100.10', 'EUR'); // 100.10€

Validation Rule

Using ValidMoney within Livewire:

namespace App\Livewire;

use Elegantly\Money\Rules\ValidMoney;
use Illuminate\Foundation\Http\FormRequest;

class CustomComponent extends Component
{
    #[Validate([
        new ValidMoney(nullable: false, min: 0, max: 100)
    ])]
    public ?int $price = null;
}

Using ValidMoney within a form request:

namespace App\Http\Requests;

use Elegantly\Money\Rules\ValidMoney;
use Illuminate\Foundation\Http\FormRequest;

class CustomFormRequest extends FormRequest
{
    public function rules()
    {
        return [
            'price' => [
                new ValidMoney(
                    nullable: false,
                    min: 0,
                    max: 100
                )
            ],
        ];
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.