Laravel Money

https://github.com/cknow/laravel-money
Admin
Laravel Money is a PHP package that abstracts MoneyPHP, providing convenient ways to handle currency...
Tokens:74,673
Snippets:544
Trust Score:7.9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Run this command in your terminal to install the package.

```bash
composer require cknow/laravel-money
```

--------------------------------

### currency() usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Shows how to call currency() with no arguments to get the default currency, or with a currency code to get a specific currency.

```php
currency();      // \Money\Currency for the default currency
currency('USD'); // \Money\Currency('USD')
```

--------------------------------

### Usage Example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/rules.md

Shows how to use the Money rule directly with the Validator facade, including forced currency and locale examples.

```APIDOC
## Usage Example

### Description
Demonstrates using the Money rule directly with the Validator facade.

### Example
```php
use Cknow\Money\Rules\Money;

$validator = Validator::make([
    'money1' => '$10.00',
    'money2' => '€10.00',
    'money3' => 'R$10,00',
], [
    'money1' => new Money(),                    // any currency
    'money2' => new Money('EUR'),               // forced currency
    'money3' => new Money('BRL', 'pt_BR'),      // forced currency + locale
]);
```
```

--------------------------------

### formatByBitcoin() signature and usage

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-formatter-trait.md

The method signature and an example call for formatByBitcoin(). The example formats 41,000,000 satoshis as Ƀ0.41 with default settings.

```php
public function formatByBitcoin($fractionDigits = 2, ?Currencies $currencies = null)
```

```php
echo Money::XBT(41000000)->formatByBitcoin(); // Ƀ0.41
```

--------------------------------

### Example — using fromMoney()

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-factory.md

Shows how to wrap a raw MoneyPHP instance with Money::fromMoney, with comments about internal usage.

```php
$raw = new \Money\Money(500, new \Money\Currency('USD'));
$wrapped = Money::fromMoney($raw); // Cknow\Money\Money

// Used internally by Money::convert() (src/Money.php:231) and by every parser
// via MoneyParserTrait::convert.
```

--------------------------------

### Example — with locale and currencies

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-factory.md

Shows how to pass a locale and currencies to the currency constructor, with a comment about the formatted output in pt_BR.

```php
$real = Money::BRL(500, false, 'pt_BR');
$real = Money::BRL(500, false, 'pt_BR', Money::getCurrencies());
// Money::BRL(500) formatted in pt_BR → R$5,00
```

--------------------------------

### Aggregation helper usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Examples of using money_min, money_max, money_avg, and money_sum with money() helper. Each returns a Money instance with the specified currency and amount.

```php
money_min(money(100, 'USD'), money(200, 'USD')); // Money::USD(100)
money_max(money(100, 'USD'), money(200, 'USD')); // Money::USD(200)
money_avg(money(100, 'USD'), money(300, 'USD')); // Money::USD(200)
money_sum(money(100, 'USD'), money(300, 'USD')); // Money::USD(400)
```

--------------------------------

### money() usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Shows how to call money() with an amount and optional currency to create a Money instance.

```php
money(500);          // Money::USD(500) (default currency)
money(500, 'USD');   // Money::USD(500)
```

--------------------------------

### Example usage of ISOCurrencies

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/isocurrencies.md

Shows how to instantiate ISOCurrencies and use its methods: contains, subunitFor, numericCodeFor, and iteration over currencies.

```php
use Cknow\Money\Currencies\ISOCurrencies;

$currencies = new ISOCurrencies;

$currencies->contains(new \Money\Currency('USD')); // true
$currencies->subunitFor(new \Money\Currency('USD')); // 2
$currencies->numericCodeFor(new \Money\Currency('USD')); // 840

foreach ($currencies as $currency) {
    echo $currency->getCode(); // AED, AFN, ...
}
```

--------------------------------

### Basic usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currency-symbol-money-formatter.md

Shows how to use the formatter with Money::formatByFormatter(). Demonstrates default symbol placement, right placement, and locale-specific symbol.

```php
use Cknow\Money\Formatters\CurrencySymbolMoneyFormatter;
use Cknow\Money\Money;

echo Money::USD(500)->formatByFormatter(new CurrencySymbolMoneyFormatter());            // $5.00
echo Money::USD(500)->formatByFormatter(new CurrencySymbolMoneyFormatter(true));        // 5.00$
echo Money::USD(500)->formatByFormatter(new CurrencySymbolMoneyFormatter(false, 'pt_BR')); // R$5,00
```

--------------------------------

### format() usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-formatter-trait.md

Example usage of format() with default formatter and with NumberFormatter::DECIMAL style. The first call outputs $5.00, the second outputs 1,99.

```php
echo Money::USD(500)->format();        // $5.00
echo Money::USD(199)->format(null, null, \NumberFormatter::DECIMAL); // 1,99
```

--------------------------------

### formatByAggregate() signature and usage

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-formatter-trait.md

The method signature and an example call for formatByAggregate(). The example registers an IntlMoneyFormatter for USD and echoes the formatted amount.

```php
public function formatByAggregate(array $formatters)
```

```php
echo Money::USD(500)->formatByAggregate([
    'USD' => new \Money\Formatter\IntlMoneyFormatter(
        new \NumberFormatter('en_US', \NumberFormatter::CURRENCY),
        Money::getCurrencies()
    ),
]);
```

--------------------------------

### setLocale() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/locale-trait.md

Example showing how to set the locale to 'pt_BR' and format a BRL amount, resulting in 'R$5,00'.

```php
Money::setLocale('pt_BR');
echo Money::BRL(500); // R$5,00
```

--------------------------------

### money_parse() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Example of parsing a string '$5.00' to a Money instance. Returns Money::USD(500).

```php
money_parse('$5.00'); // Money::USD(500)
```

--------------------------------

### Example — basic currency constructors

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-factory.md

Shows basic usage of Money::USD, Money::EUR, and Money::XBT with comments indicating the resulting formatted values.

```php
use Cknow\Money\Money;

$usd = Money::USD(500);              // $5.00
$eur = Money::EUR(10, true);         // €10.00 (10 forced as decimals)
$btc = Money::XBT(41000000);         // Ƀ0.41 (bitcoin uses 8 minor units)
```

--------------------------------

### Common customizations in config/money.php

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/configuration.md

Example configuration file showing how to set locale, default currency, formatter, serializer, and currencies. The 'currencies' key includes 'iso', 'bitcoin', and 'custom' arrays.

```php
// config/money.php
return [
    'locale' => 'pt_BR',
    'defaultCurrency' => 'BRL',
    'defaultFormatter' => null,
    'defaultSerializer' => null,
    'currencies' => [
        'iso' => ['USD', 'EUR', 'BRL'],
        'bitcoin' => 'all',
        'custom' => [
            'MY1' => 2,
        ],
    ],
];
```

--------------------------------

### Example usage with string rule form

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/rules.md

Shows how to use the 'money' validation extension with string parameters.

```php
$validator = Validator::make([
    'money4' => '$10.00',
    'money5' => '€10.00',
    'money6' => 'R$10,00',
], [
    'money4' => 'money',
    'money5' => 'money:EUR',
    'money6' => 'money:BRL,pt_BR',
]);
```

--------------------------------

### Example usage with object rule

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/rules.md

Shows how to use the Money rule with the Validator, including forced currency and locale.

```php
use Cknow\Money\Rules\Money;

$validator = Validator::make([
    'money1' => '$10.00',
    'money2' => '€10.00',
    'money3' => 'R$10,00',
], [
    'money1' => new Money(),                    // any currency
    'money2' => new Money('EUR'),               // forced currency
    'money3' => new Money('BRL', 'pt_BR'),      // forced currency + locale
]);
```

--------------------------------

### parseByParser() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-parser-trait.md

Example using DecimalMoneyParser with parseByParser() to parse '1.00' as USD, returning Money::USD(100).

```php
$parser = new \Money\Parser\DecimalMoneyParser(Money::getCurrencies());
Money::parseByParser($parser, '1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### money_parse_by_intl_localized_decimal() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Example of parsing a localized decimal string. Returns Money::USD(100).

```php
money_parse_by_intl_localized_decimal('1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### setCurrencies() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currencies-trait.md

Example of configuring currencies with an array, including ISO subset, bitcoin all, and custom currencies. After setting, isValidCurrency() returns true for USD and false for JPY.

```php
Money::setCurrencies([
    'iso' => ['USD', 'EUR'],
    'bitcoin' => 'all',
    'custom' => ['MY1' => 2],
]);
Money::isValidCurrency('USD'); // true
Money::isValidCurrency('JPY'); // false (not in the configured subset)
```

--------------------------------

### __callStatic() usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Demonstrates the aggregation methods (min, max, avg, sum) and the factory method (USD) dispatched through __callStatic().

```php
// Aggregation (step 2)
Money::min(Money::USD(100), Money::USD(200));  // Money::USD(100)
Money::max(Money::USD(100), Money::USD(200));  // Money::USD(200)
Money::avg(Money::USD(100), Money::USD(300));  // Money::USD(200)
Money::sum(Money::USD(100), Money::USD(300));  // Money::USD(400)

// Factory (step 3)
Money::USD(500);   // new Money in USD
```

--------------------------------

### convert() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Shows how to wrap a raw MoneyPHP Money instance using Money::convert(). The result is a Cknow\Money\Money wrapping the same value.

```php
$raw = new \Money\Money(500, new \Money\Currency('USD'));
$wrapped = Money::convert($raw); // Cknow\Money\Money wrapping the same value
```

--------------------------------

### Money arithmetic, comparison, aggregation, formatting, and parsing examples

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Shows common Money operations: arithmetic (add, subtract, multiply, divide, mod, absolute, negative, ratioOf), comparisons (isSameCurrency, equals, greaterThan, etc.), aggregation (min, max, avg, sum), formatting (format, formatByBitcoin, formatByCurrencySymbol, etc.), and parsing (parse, parseByBitcoin, etc.). Each line includes the expected result as a comment.

```php
use Cknow\Money\Money;

Money::USD(500)->add(Money::USD(500)); // $10.00
Money::USD(500)->add(Money::USD(500), Money::USD(500)); // $15.00
Money::USD(500)->subtract(Money::USD(400)); // $1.00
Money::USD(500)->subtract(Money::USD(200), Money::USD(100)); // $2.00
Money::USD(500)->multiply(2); // $10.00
Money::USD(1000)->divide(2); // $5.00
Money::USD(830)->mod(Money::USD(300)); // $2.30 -> Money::USD(230)
Money::USD(-500)->absolute(); // $5.00
Money::USD(500)->negative(); // $-5.00
Money::USD(30)->ratioOf(Money::USD(2)); // 15
Money::USD(500)->isSameCurrency(Money::USD(100)); // true
Money::USD(500)->equals(Money::USD(500)); // true
Money::USD(500)->greaterThan(Money::USD(100)); // true
Money::USD(500)->greaterThanOrEqual(Money::USD(500)); // true
Money::USD(500)->lessThan(Money::USD(1000)); // true
Money::USD(500)->lessThanOrEqual(Money::USD(500)); // true
Money::USD(500)->isZero(); // false
Money::USD(500)->isPositive(); // true
Money::USD(500)->isNegative(); // false
Money::USD(500)->getMoney(); // Instance of \Money\Money
Money::isValidCurrency('USD'); // true
Money::isValidCurrency('FAIL'); // false
Money::getISOCurrencies(); // Load ISO currencies

// Aggregation
Money::min(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(100)
Money::max(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(300)
Money::avg(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(200)
Money::sum(Money::USD(100), Money::USD(200), Money::USD(300)); // Money::USD(600)

// Formatters
Money::USD(500)->format(); // $5.00
Money::USD(199)->format(null, null, \NumberFormatter::DECIMAL); // 1,99
Money::XBT(41000000)->formatByBitcoin(); // \xC9\x830.41
Money::USD(500)->formatByCurrencySymbol(); // $5.00
Money::USD(500)->formatByCurrencySymbol(true); // 5.00$
Money::USD(500)->formatByDecimal(); // 5.00
Money::USD(500)->formatByIntl(); // $5.00
Money::USD(199)->formatByIntl(null, null, \NumberFormatter::DECIMAL); // 1,99
Money::USD(500)->formatByIntlLocalizedDecimal(); // $5.00
Money::USD(199)->formatByIntlLocalizedDecimal(null, null, \NumberFormatter::DECIMAL) // 1.99

// Parsers
Money::parse('$1.00'); // Money::USD(100)
Money::parseByBitcoin("\xC9\x830.41"); // Money::XBT(41000000)
Money::parseByDecimal('1.00', 'USD'); // Money::USD(100)
Money::parseByIntl('$1.00'); // Money::USD(100)
Money::parseByIntlLocalizedDecimal('1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### Example error handling for subunitFor

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/isocurrencies.md

Shows how to catch UnknownCurrencyException when calling subunitFor with an invalid currency code.

```php
use Money\Exception\UnknownCurrencyException;

try {
    $currencies->subunitFor(new \Money\Currency('FAIL'));
} catch (UnknownCurrencyException $e) {
    // 'Cannot find ISO currency FAIL'
}
```

--------------------------------

### formatByCurrencySymbol() signature and usage

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-formatter-trait.md

The method signature and example calls for formatByCurrencySymbol(). The examples show the default left symbol placement and the $right=true placement.

```php
public function formatByCurrencySymbol($right = false, $locale = null, ?Currencies $currencies = null)
```

```php
echo Money::USD(500)->formatByCurrencySymbol();       // $5.00
echo Money::USD(500)->formatByCurrencySymbol(true);   // 5.00$
```

--------------------------------

### money_parse_by_bitcoin() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Example of parsing a Bitcoin amount string. Returns Money::XBT(41000000).

```php
money_parse_by_bitcoin("\xC9\x830.41"); // Money::XBT(41000000)
```

--------------------------------

### Macro registration example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Shows how to register instance and static macros on the Money class using Laravel's Macroable trait. The macros can then be called as methods.

```php
Money::macro('toBRL', function () {
    return $this->setCurrency('BRL');
});

Money::macro('half', fn () => Money::USD(50));

Money::USD(100)->toBRL(); // Money::BRL(100)
Money::half();            // Money::USD(50)
```

--------------------------------

### ArrayMoneySerializer usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-serializer.md

Shows the output of toArray() with and without attached attributes. The first example returns ['amount' => '500', 'currency' => 'USD', 'formatted' => '$5.00']; the second adds a 'note' attribute at the beginning.

```php
$money = Money::USD(500);
$money->toArray();
// ['amount' => '500', 'currency' => 'USD', 'formatted' => '$5.00']

$money->attributes(['note' => 'x']);
$money->toArray();
// ['note' => 'x', 'amount' => '500', 'currency' => 'USD', 'formatted' => '$5.00']
```

--------------------------------

### multiply() usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Examples of multiplying a Money instance by an integer and a float. The integer multiplication yields an exact result, while the float multiplication uses the default rounding mode.

```php
Money::USD(500)->multiply(2);        // Money::USD(1000)
Money::USD(500)->multiply(1.5);      // Money::USD(750)
```

--------------------------------

### getCurrencies() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currencies-trait.md

Shows how to retrieve the active currency list using Money::getCurrencies(), which returns a \Money\Currencies instance.

```php
$currencies = Money::getCurrencies(); // \Money\Currencies
```

--------------------------------

### attributes() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Shows attaching metadata to a Money instance, then echoing and JSON-encoding it. The attributes are merged into the serialized output.

```php
$money = Money::USD(500)->attributes(['source' => 'order-1']);
echo $money;                      // $5.00
json_encode($money);
// {"amount":"500","currency":"USD","formatted":"$5.00","source":"order-1"}
```

--------------------------------

### Examples of __call() usage

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

All these operations flow through __call() and return Cknow\Money\Money. They demonstrate add, subtract, mod, absolute, negative, and allocate methods.

```php
// All of these flow through __call() and return Cknow\Money\Money:
Money::USD(500)->add(Money::USD(500));              // Money::USD(1000)
Money::USD(500)->subtract(Money::USD(200), Money::USD(100)); // Money::USD(200)
Money::USD(830)->mod(Money::USD(300));              // Money::USD(230)
Money::USD(-500)->absolute();                       // Money::USD(500)
Money::USD(500)->negative();                        // Money::USD(-500)
Money::USD(500)->allocate([1, 1]);                  // [Money::USD(250), Money::USD(250)]
```

--------------------------------

### RuntimeException: ISO currencies file missing

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/errors.md

Thrown when the ISO currencies file is missing. The example shows the exception being thrown.

```php
throw new \RuntimeException('Failed to load currency ISO codes.');
```

--------------------------------

### Create custom Money formatter (MyFormatter)

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Defines a custom formatter class implementing \Money\MoneyFormatter and uses it with formatByFormatter(). The format() method must return a string; this example always returns 'My Formatter'.

```php
class MyFormatter implements \Money\MoneyFormatter
{
    /**
     * Formats a Money object as string.
     */
    public function format(\Money\Money $money): string
    {
        return 'My Formatter';
    }
}

Money::USD(500)->formatByFormatter(new MyFormatter()); // My Formatter
```

--------------------------------

### Custom formatter/serializer classes in config/money.php

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/configuration.md

Example configuration file showing how to set custom formatter and serializer classes. The 'defaultFormatter' expects a class implementing Money\MoneyFormatter, and 'defaultSerializer' expects an array with a class and optional parameters.

```php
// config/money.php
return [
    'defaultFormatter' => App\Money\MyFormatter::class,       // implements Money\MoneyFormatter
    'defaultSerializer' => [App\Money\MySerializer::class, ['param' => 1]], // implements MoneySerializer
];
```

--------------------------------

### setDefaultCurrency() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currencies-trait.md

Shows how to set the default currency to 'BRL' and then retrieve it. This affects all subsequent parses that don't specify a currency.

```php
Money::setDefaultCurrency('BRL');
Money::getDefaultCurrency(); // 'BRL'
```

--------------------------------

### getMoney() usage: retrieve underlying MoneyPHP instance

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Shows how to get the underlying \Money\Money instance and access its amount. The first line creates a Money object with USD 500, the second retrieves the raw MoneyPHP object, and the third gets the amount as a string.

```php
$raw = Money::USD(500)->getMoney();     // instance of \Money\Money
$amount = $raw->getAmount();            // '500'
```

--------------------------------

### Blade directives usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Example of using the Blade directives in a template. Shows @currency, @money, aggregation directives like @money_min and @money_sum, and parsing directives like @money_parse and @money_parse_by_decimal.

```blade
@currency()          {{-- default currency from config --}}
@currency('USD')

@money(500)          {{-- default currency from config --}}
@money(500, 'USD')

{{-- aggregation --}}
@money_min(@money(100, 'USD'), @money(200, 'USD'))   {{-- Money::USD(100) --}}
@money_sum(@money(100, 'USD'), @money(300, 'USD'))   {{-- Money::USD(400) --}}

{{-- parsing --}}
@money_parse('$5.00')          {{-- Money::USD(500) --}}
@money_parse_by_decimal('1.00', 'USD')  {{-- Money::USD(100) --}}
```

--------------------------------

### Custom default formatter configuration

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-formatter-trait.md

Configuration example for setting a custom default formatter in config/money.php. The formatter class must implement Money\MoneyFormatter. The usage line shows that format() will return whatever MyFormatter returns.

```php
// config/money.php
return [
    'defaultFormatter' => App\Money\MyFormatter::class, // implements Money\MoneyFormatter
];

// usage
echo Money::USD(500)->format(); // whatever MyFormatter returns
```

--------------------------------

### getDefaultCurrency() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currencies-trait.md

Shows how to call Money::getDefaultCurrency() to retrieve the default currency code, e.g., 'USD'.

```php
Money::getDefaultCurrency(); // e.g. 'USD'
```

--------------------------------

### StringMoneySerializer usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-serializer.md

Serializes Money::USD(500) with StringMoneySerializer, returning the string '$5.00'.

```php
Money::USD(500)->serializeBySerializer(new StringMoneySerializer()); // '$5.00'
```

--------------------------------

### getISOCurrencies() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currencies-trait.md

Shows how to retrieve the ISO currency map and access the entry for USD, which includes numericCode 840 and minorUnit 2.

```php
$map = Money::getISOCurrencies();
// ['USD' => ['numericCode' => 840, 'minorUnit' => 2], ...]
```

--------------------------------

### JSON encoding example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-serializer.md

Shows the JSON output of a Money object when serialized. The output is {"amount":"500","currency":"USD","formatted":"$5.00"}.

```php
$json = json_encode(Money::USD(500));
// {"amount":"500","currency":"USD","formatted":"$5.00"}
```

--------------------------------

### format() method implementation

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currency-symbol-money-formatter.md

Uses NumberFormatter to get the currency symbol and DecimalMoneyFormatter for the amount. Returns symbol concatenated with value, order based on $right.

```php
public function format(\Money\Money $money): string
{
    $numberFormatter = new NumberFormatter($this->locale, NumberFormatter::CURRENCY);
    $symbol = $numberFormatter->getSymbol(NumberFormatter::CURRENCY_SYMBOL);

    $formatter = new DecimalMoneyFormatter($this->currencies);
    $value = $formatter->format($money);

    return $this->right ? $value.$symbol : $symbol.$value;
}
```

--------------------------------

### Using DecimalMoneySerializer

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-serializer.md

Example of using the DecimalMoneySerializer to serialize a Money object to a decimal string. The output is "5.00".

```php
$money = Money::USD(500);
$money->serializeBySerializer(new \Cknow\Money\Serializer\DecimalMoneySerializer()); // "5.00"
```

--------------------------------

### formatByDecimal() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-formatter-trait.md

Outputs the decimal representation without currency symbol, e.g. 5.00 for 500 cents in USD.

```php
echo Money::USD(500)->formatByDecimal(); // 5.00
```

--------------------------------

### divide() usage: divide money amount

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Divides a Money amount by a divisor. The first example divides 1000 by 2 to get 500, the second divides by 3 with default rounding (ROUND_HALF_UP) to get 333.

```php
Money::USD(1000)->divide(2);   // Money::USD(500)
Money::USD(1000)->divide(3);   // Money::USD(333)  (ROUND_HALF_UP)
```

--------------------------------

### MoneyServiceProvider::boot()

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Performs three actions: config publishing, Blade directive registration, and validation extension registration.

```APIDOC
## MoneyServiceProvider::boot()

### Description
Performs three actions: config publishing, Blade directive registration, and validation extension registration.

### Method
boot

### Signature
public function boot()

### Parameters
None

### Returns
void

### Actions
1. **Config publishing** — when running in the console, registers the publishable config so `php artisan vendor:publish --provider="Cknow\Money\MoneyServiceProvider"` copies `config/config.php` to `config_path('money.php')`, tagged `config`.
2. **Blade directives** — after the `BladeCompiler` is resolved, calls `BladeExtension::register($blade)`.
3. **Validation extensions** — registers two `Validator` extensions:
   - `currency` → `new Rules\Currency()` passing `$attribute`, `$value`.
   - `money` → `new Rules\Money(...$parameters)` passing `$attribute`, `$value`, `$parameters`.

```

--------------------------------

### __toString() method signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Returns the formatted money string, equivalent to $this->format(). For example, echo Money::USD(500) prints $5.00.

```php
public function __toString()
```

--------------------------------

### Using the currency validation rule

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/rules.md

Example of using the `Currency` rule in object form and the string form 'currency' registered by the service provider. The first validator fails because 'currency2' is not a valid currency code.

```php
use Cknow\Money\Rules\Currency;

$validator = Validator::make(
    ['currency1' => 'USD', 'currency2' => 'NOT_A_CODE'],
    ['currency1' => new Currency(), 'currency2' => new Currency()]
);

$validator->fails(); // true — 'currency2' fails

// The string form is also registered by the provider:
$validator = Validator::make(
    ['currency1' => new \Money\Currency('BRL')],
    ['currency1' => 'currency']
);
```

--------------------------------

### money_parse_by_intl() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Example of parsing an internationalized string. Returns Money::USD(100).

```php
money_parse_by_intl('$1.00'); // Money::USD(100)
```

--------------------------------

### getLocale() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/locale-trait.md

Example call to Money::getLocale() returning a locale string like 'en_US'.

```php
Money::getLocale(); // e.g. 'en_US'
```

--------------------------------

### money_parse_by_decimal() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Example of parsing a decimal string with a fallback currency. Returns Money::USD(100).

```php
money_parse_by_decimal('1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### parseByIntlLocalizedDecimal() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-parser-trait.md

Example call to parseByIntlLocalizedDecimal() with a string '1.00' and currency 'USD', returning Money::USD(100).

```php
Money::parseByIntlLocalizedDecimal('1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### boot() method signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Signature of the boot method. It performs config publishing, Blade directive registration, and validation extension registration.

```php
public function boot()
```

--------------------------------

### parseByIntl() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-parser-trait.md

Example call to parseByIntl() with a locale-formatted string '$1.00'. The comment shows the expected result: Money::USD(100).

```php
Money::parseByIntl('$1.00'); // Money::USD(100)
```

--------------------------------

### parseByDecimal() usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-parser-trait.md

Example call to parseByDecimal() with a decimal string '1.00' and currency 'USD'. The comment shows the expected result: Money::USD(100).

```php
Money::parseByDecimal('1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### Full default config file (config/config.php)

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/configuration.md

The complete default configuration for the package. It sets the locale, default currency, formatter and serializer options, the ISO currencies path, and the currencies list. The 'custom' array is commented out by default.

```php
<?php

return [
    'locale' => config('app.locale', 'en_US'),
    'defaultCurrency' => config('app.currency', 'USD'),
    'defaultFormatter' => null,
    'defaultSerializer' => null,
    'isoCurrenciesPath' => is_dir(__DIR__.'/../vendor')
        ? __DIR__.'/../vendor/moneyphp/money/resources/currency.php'
        : __DIR__.'/../../../moneyphp/money/resources/currency.php',
    'currencies' => [
        'iso' => 'all',
        'bitcoin' => 'all',
        'custom' => [
            // 'MY1' => 2,
            // 'MY2' => 3
        ],
    ],
];
```

--------------------------------

### MoneyServiceProvider::register()

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Merges the package config into the 'money' config namespace so config('money.*') works before publishing.

```APIDOC
## MoneyServiceProvider::register()

### Description
Merges the package config (`src/../config/config.php`) into the `money` config namespace so `config('money.*')` works before publishing.

### Method
register

### Signature
public function register()

### Parameters
None

### Returns
void

```

--------------------------------

### Publish Configuration

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Run this Artisan command to publish the package configuration file to your config directory.

```bash
php artisan vendor:publish --provider="Cknow\Money\MoneyServiceProvider"
```

--------------------------------

### IntegerMoneySerializer usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-serializer.md

Serializes Money::USD(500) with IntegerMoneySerializer, returning the integer 500.

```php
Money::USD(500)->serializeBySerializer(new IntegerMoneySerializer()); // 500
```

--------------------------------

### DecimalMoneySerializer usage example

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money-serializer.md

Serializes Money::USD(500) with DecimalMoneySerializer, returning the string '5.00'.

```php
Money::USD(500)->serializeBySerializer(new DecimalMoneySerializer()); // '5.00'
```

--------------------------------

### Constructor signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currency-symbol-money-formatter.md

Constructor accepts $right, $locale, and $currencies parameters. $right controls symbol placement, $locale defaults to Money::getLocale(), and $currencies defaults to Money::getCurrencies().

```php
public function __construct($right = false, $locale = null, ?Currencies $currencies = null)
```

--------------------------------

### new Money($amount, $currency, $forceDecimals, $locale, $currencies)

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Creates a new Money instance. Accepts various amount formats and optional currency, decimal forcing, locale, and currency list parameters.

```APIDOC
## Constructor

### Description
Creates a new `Cknow\Money\Money` instance. The constructor delegates to `Money::parse(...)` with `$convert = false`, storing the underlying `Money\Money` in the protected `$money` property.

### Method
Constructor

### Signature
```php
public function __construct($amount = null, $currency = null, $forceDecimals = false, $locale = null, $currencies = null)
```

### Parameters
- `$amount` (mixed) - Optional - The monetary value. `null` is coerced to `0` (integer). Accepts an int (minor units), a float, a numeric string, a locale-formatted string (`'$1.00'`), a `Cknow\Money\Money`, or a `Money\Money`.
- `$currency` (\Money\Currency|string|null) - Optional - Currency code or `Money\Currency`. Falls back to the configured default currency.
- `$forceDecimals` (bool) - Optional - When `true`, integer amounts are treated as decimal values (e.g. `500` becomes `5.00`).
- `$locale` (string|null) - Optional - Locale used for parsing formatted strings; falls back to the configured locale.
- `$currencies` (\Money\Currencies|null) - Optional - Currency list used for parsing; falls back to the configured currencies.

### Return Type
`\Cknow\Money\Money` (the new instance).

### Throws
- `\InvalidArgumentException` - When `$amount` is a non-scalar value that is not a `Money` instance.
- `Money\Exception\ParserException` - When `$amount` is a string that no parser can interpret.

### Example — basic
```php
use Cknow\Money\Money;

$five = new Money(500);                 // $5.00 (default currency)
$fiveEur = new Money(500, 'EUR');       // €5.00
$forced = new Money(500, 'EUR', true);  // €500.00 (500 interpreted as decimals)
```

### Example — with error handling
```php
use Cknow\Money\Money;
use InvalidArgumentException;

try {
    $money = new Money(['not', 'a', 'scalar']);
} catch (InvalidArgumentException $e) {
    // "Invalid value [...]" — non-scalar amounts are rejected
}

// Null is accepted and treated as zero:
$zero = new Money(null); // Money::USD(0)
```
```

--------------------------------

### Global Helper Functions for Currency, Money, Aggregation, and Parsing

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Use these global PHP functions to create currency and money instances, perform aggregations, and parse monetary strings. The default currency is taken from config/money.php when not specified. Parsing functions handle different formats: money_parse for a general parser, money_parse_by_bitcoin for Bitcoin amounts, money_parse_by_decimal for decimal strings, money_parse_by_intl for Intl-based parsing, and money_parse_by_intl_localized_decimal for localized decimal parsing.

```php
currency() // To use default currency present in `config/money.php`
currency('USD');
money(500); // To use default currency present in `config/money.php`
money(500, 'USD');

// Aggregation
money_min(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(100)
money_max(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(300)
money_avg(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(200)
money_sum(money(100, 'USD'), money(200, 'USD'), money(300, 'USD')); // Money::USD(600)

// Parsers
money_parse('$5.00'); // Money::USD(500)
money_parse_by_bitcoin("\xC9\x830.41"); // Money::XBT(41000000)
money_parse_by_decimal('1.00', 'USD'); // Money::USD(100)
money_parse_by_intl('$1.00'); // Money::USD(100)
money_parse_by_intl_localized_decimal('1.00', 'USD'); // Money::USD(100)
```

--------------------------------

### Constructor signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/rules.md

The constructor accepts optional parameters for currency, locale, currencies, and bitcoin digits.

```php
public function __construct(
    $currency = null,
    $locale = null,
    $currencies = null,
    $bitCointDigits = null
)
```

--------------------------------

### BadMethodCallException: undefined method on Money

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/errors.md

Thrown when calling an undefined method on Money. The example shows catching the exception when calling someUndefinedMethod().

```php
if (! method_exists($this->money, $method)) {
    throw new BadMethodCallException(sprintf(
        'Call to undefined method %s::%s()',
        static::class,
        $method
    ));
}
```

```php
use BadMethodCallException;

try {
    Money::USD(500)->someUndefinedMethod();
} catch (BadMethodCallException $e) {
    // handle
}
```

--------------------------------

### __call($method, array $arguments)

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/money.md

Dynamic dispatch for arithmetic and comparison methods, converting arguments and results between Cknow\Money\Money and Money\Money.

```APIDOC
## __call($method, array $arguments)

### Description
Dynamic dispatch for arithmetic and comparison methods. It checks for macros, validates the underlying Money\Money method, converts arguments, and converts results back for a specific list of methods.

### Method
__call

### Signature
```php
public function __call($method, array $arguments)
```

### Parameters
- **$method** (string) - Required - The method name to call on the underlying Money\Money.
- **$arguments** (array) - Required - The arguments to pass, with Cknow\Money\Money instances converted to Money\Money.

### Throws
- **\BadMethodCallException** - When the underlying Money\Money does not define the requested method.

### Behavior
1. Returns a macro result if `static::hasMacro($method)`.
2. Throws `BadMethodCallException` if the underlying `Money\Money` has no such method.
3. Calls the method on the underlying `Money\Money` with arguments converted.
4. For the list `['add', 'subtract', 'multiply', 'divide', 'mod', 'allocate', 'allocateTo', 'absolute', 'negative']`, converts the result back to `Cknow\Money\Money` (arrays become arrays of `Money`).

### Examples
```php
Money::USD(500)->add(Money::USD(500));              // Money::USD(1000)
Money::USD(500)->subtract(Money::USD(200), Money::USD(100)); // Money::USD(200)
Money::USD(830)->mod(Money::USD(300));              // Money::USD(230)
Money::USD(-500)->absolute();                       // Money::USD(500)
Money::USD(500)->negative();                        // Money::USD(-500)
Money::USD(500)->allocate([1, 1]);                  // [Money::USD(250), Money::USD(250)]
```

```

--------------------------------

### MoneyServiceProvider class signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Shows the public methods of the MoneyServiceProvider class. The register method merges the package config, and boot performs config publishing, Blade directive registration, and validation extension registration.

```php
class MoneyServiceProvider extends ServiceProvider
{
    public function register();
    public function boot();
}
```

--------------------------------

### UnknownCurrencyException: ISO lookups

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/errors.md

Thrown when a currency is not found in the ISO map. The example shows catching the exception when calling subunitFor() with an unknown currency.

```php
throw new UnknownCurrencyException('Cannot find ISO currency '.$currency->getCode());
```

```php
use Money\Exception\UnknownCurrencyException;

try {
    (new \Cknow\Money\Currencies\ISOCurrencies)
        ->subunitFor(new \Money\Currency('FAIL'));
} catch (UnknownCurrencyException $e) {
    // handle
}
```

--------------------------------

### Basic Usage with Money Class

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Use the Money class to create and format currency amounts. The second parameter forces decimals.

```php
use Cknow\Money\Money;

echo Money::USD(500); // $5.00
echo Money::USD(500, true); // $500.00 force decimals
```

--------------------------------

### Add to composer.json

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Add this line to the require section of your composer.json file, then run composer update.

```bash
"cknow/laravel-money": "^8.0"
```

--------------------------------

### String Rule Form

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/rules.md

Shows how to use the 'money' string rule extension registered by the service provider, mapping string parameters to constructor arguments.

```APIDOC
## String Rule Form

### Description
The service provider registers the `money` validation extension, mapping string parameters to constructor arguments.

### Example
```php
$validator = Validator::make([
    'money4' => '$10.00',
    'money5' => '€10.00',
    'money6' => 'R$10,00',
], [
    'money4' => 'money',
    'money5' => 'money:EUR',
    'money6' => 'money:BRL,pt_BR',
]);
```

### Parameters
Parameters after the colon are passed positionally to the `Money` rule constructor: `money:currency,locale,currencies,bitcoinDigits`.
```

--------------------------------

### Composer autoload configuration for helpers

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Configures Composer to autoload the helpers.php file via the 'files' autoload entry.

```json
{
    "autoload": {
        "psr-4": { "Cknow\\Money\\": "src/" },
        "files": ["src/helpers.php"]
    }
}
```

--------------------------------

### isValidCurrency() usage examples

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/currencies-trait.md

Shows how to call isValidCurrency() with a valid currency code 'USD' returning true and an invalid code 'FAIL' returning false.

```php
Money::isValidCurrency('USD');  // true
Money::isValidCurrency('FAIL'); // false
```

--------------------------------

### Catch InvalidArgumentException for unknown currency code

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/errors.md

Example of catching the InvalidArgumentException thrown when setting an unknown currency code. The comment shows the expected exception message.

```php
use Cknow\Money\Money;
use InvalidArgumentException;

try {
    Money::setCurrencies(['iso' => ['NOT_A_CODE']]);
} catch (InvalidArgumentException $e) {
    // 'Unknown ISO currency code: NOT_A_CODE'
}
```

--------------------------------

### currency()

Source: https://github.com/cknow/laravel-money/blob/main/README.md

Returns a Currency object for the given currency code, or the default currency from config/money.php if no code is provided.

```APIDOC
## currency()

### Description
Returns a Currency object for the specified currency code, or the default currency if no code is given.

### Method
Helper function

### Parameters
- **currencyCode** (string) - Optional - The ISO currency code (e.g., 'USD'). If omitted, uses the default currency from `config/money.php`.

### Return Value
- **Currency** - The Currency object.

### Example
```php
currency(); // default currency
currency('USD');
```
```

--------------------------------

### composer.json auto-discovery configuration

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Configures Laravel package auto-discovery to register the MoneyServiceProvider via the extra.laravel.providers key.

```json
{
    "extra": {
        "laravel": {
            "providers": [
                "Cknow\\Money\\MoneyServiceProvider"
            ]
        }
    }
}
```

--------------------------------

### Catch InvalidArgumentException for unparseable cast value

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/errors.md

Example of catching the InvalidArgumentException thrown when assigning an unparseable value to a MoneyCast property. The comment shows the expected exception message.

```php
use InvalidArgumentException;

try {
    $model->price = 'not-a-number';
} catch (InvalidArgumentException $e) {
    // 'Invalid data provided for App\Models\Product::$price'
}
```

--------------------------------

### money() function signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/helpers.md

Defines the money() helper function that creates a Money instance with optional amount, currency, forceDecimals, locale, and currencies parameters.

```php
function money($amount = null, $currency = null, $forceDecimals = false, $locale = null, $currencies = null)
```

--------------------------------

### MoneyCast get() method signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/casts.md

Retrieves the cast value. Returns null if the raw value is null; otherwise parses via Money::parse with the resolved currency and forceDecimals flag.

```php
public function get($model, string $key, $value, array $attributes)
```

--------------------------------

### register() method signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/service-provider-and-blade.md

Signature of the register method. It merges the package config into the money config namespace.

```php
public function register()
```

--------------------------------

### loadCurrencies() method signature

Source: https://github.com/cknow/laravel-money/blob/main/_autodocs/api-reference/isocurrencies.md

Signature for the loadCurrencies() method, which requires the file at config('money.isoCurrenciesPath') and throws RuntimeException if the file does not exist.

```php
protected function loadCurrencies()
```
Tokens:
Raw