README

Table of Contents

• Introduction
• Features
• Installation
• Configuration
• Storing Money in the Database
• Usage
  • Casting with a Column as Currency (Recommended)
  • Casting with a Defined Currency
  • Parsing Values to Money Instances
  • Validation Rule
• Testing
• Changelog
• Contributing
• Security
• Credits
• License

Introduction

This package provides a seamless integration of Brick/Money with Laravel, allowing you to handle monetary values efficiently within your application.

Features

• MoneyCast: Cast model attributes to Brick\Money\Money.
• MoneyParse: Convert various data types into Brick\Money\Money instances.
• ValidMoney: Implement money validation rules.

Installation

Install the package via Composer:

composer require elegantly/laravel-money

Configuration

To customize the default settings, publish the configuration file:

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

The default configuration file (config/money.php) contains:

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

Storing Money in the Database

The recommended way to store money in the database is to use a bigInteger column for the amount and a string column for the currency. This ensures precision and avoids floating-point errors. Store the amount in the smallest unit of currency (e.g., cents for USD, centimes for EUR). This approach prevents rounding issues and maintains accuracy in calculations.

Example migration:

Schema::create('invoices', function (Blueprint $table) {
    $table->id();
    $table->bigInteger('amount'); // Store in cents
    $table->string('currency', 3); // ISO currency code
    $table->timestamps();
});

Usage

Casting with a Column as Currency (Recommended)

If your database stores both the amount and the currency in separate columns, you can specify the currency column like this:

use Elegantly\Money\MoneyCast;

/**
 * @property ?Money $amount
 * @property ?string $currency
 **/
class Invoice extends Model {
    /**
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'amount' => MoneyCast::class . ':currency'
        ];
    }
}

Casting with a Defined Currency

You can also define a specific currency for money casting instead of referencing a column:

use Elegantly\Money\MoneyCast;

/**
 * @property ?Money $price
 * @property ?Money $cost
 **/
class Invoice extends Model {
     /**
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'cost' => MoneyCast::class . ':EUR',
            'price' => MoneyCast::class . ':USD'
        ];
    }
}

Parsing Values to Money Instances

Convert strings, integers, or floats into Brick\Money\Money instances using MoneyParser:

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 in 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 in Form Requests

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

Run the package tests with:

composer test

Changelog

Refer to the CHANGELOG for details on recent updates and modifications.

Contributing

Contributions are welcome! See CONTRIBUTING for guidelines.

Security

If you discover any security vulnerabilities, please review our security policy to report them responsibly.

Credits

• Quentin Gabriele
• All Contributors

License

This package is released under the MIT License. See LICENSE.md for details.