Brick Money

https://github.com/brick/money
Admin
Brick Money is a PHP library providing immutable classes for working with monies and currencies,...
Tokens:83,909
Snippets:610
Trust Score:9.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### ECB-style usage example with BaseCurrencyProvider

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/base-currency-provider.md

Shows a classic ECB-style setup: configure rates relative to EUR, wrap with BaseCurrencyProvider, and use with CurrencyConverter. Demonstrates derived rates (1.1, 10/11, 11/9) and conversion with rounding.

```php
use Brick\Money\Currency;
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\Money\ExchangeRateProvider\BaseCurrencyProvider;
use Brick\Money\CurrencyConverter;
use Brick\Money\Money;

$provider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.1')
    ->addExchangeRate('EUR', 'GBP', '0.9')
    ->build();

$provider = new BaseCurrencyProvider($provider, 'EUR');

$provider->getExchangeRate(Currency::of('EUR'), Currency::of('USD')); // 1.1
$provider->getExchangeRate(Currency::of('USD'), Currency::of('EUR')); // 10/11
$provider->getExchangeRate(Currency::of('GBP'), Currency::of('USD')); // 11/9

$converter = new CurrencyConverter($provider);
$converted = $converter->convert(
    Money::of('100', 'GBP'),
    'USD',
    roundingMode: \Brick\Math\RoundingMode::Down, // 1100/9 = 122.222... needs rounding
); // USD 122.22
```

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

### Choosing a comparison mode

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/money-comparator.md

Shows how to configure MoneyComparator with BaseCurrencyMode for consistent ordering or PairwiseMode for precise single-pair comparisons. Includes exchange rate setup and example comparisons.

```php
use Brick\Money\Money;
use Brick\Money\MoneyComparator;
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\Money\ComparisonMode\BaseCurrencyMode;
use Brick\Money\ComparisonMode\PairwiseMode;

$provider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.1')
    ->addExchangeRate('USD', 'EUR', '0.9') // asymmetric! reciprocal would be 0.9090...
    ->build();

// Consistent ordering for lists — recommended:
$comparator = new MoneyComparator($provider, new BaseCurrencyMode('EUR'));

$monies = [Money::of(100, 'EUR'), Money::of(100, 'USD')];
$min = $comparator->min(...$monies);  // USD 100 (in EUR: 90 < 100)
$max = $comparator->max(...$monies);  // EUR 100

// Most precise for a single pair:
$pairwise = new MoneyComparator($provider, new PairwiseMode());
$pairwise->isGreater(Money::of(100, 'USD'), Money::of(90, 'EUR')); // 100 USD vs 90 EUR compared in EUR
```

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

### Install Brick\Money via Composer

Source: https://github.com/brick/money/blob/main/README.md

Use this command to install the brick/money package with Composer. This is the standard installation method for the library.

```bash
composer require brick/money
```

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

### Basic Money Creation and Arithmetic

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

Shows how to create Money instances from strings, integers, and minor units, and perform addition and multiplication with rounding modes. Includes examples of rounding up and down.

```php
use Brick\Money\Money;
use Brick\Math\RoundingMode;

$money = Money::of(50, 'USD');                       // USD 50.00
$money = Money::of('19.9', 'USD');                   // USD 19.90
$money = Money::ofMinor(1234, 'USD');                // USD 12.34
$money = Money::of('123.456', 'USD', roundingMode: RoundingMode::Up); // USD 123.46

echo $money->plus('4.99');              // USD 128.45
echo $money->multipliedBy('1.2345', RoundingMode::Down); // USD 152.41
```

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

### Create CachedProvider with custom PSR-16 cache and TTL

Source: https://github.com/brick/money/blob/main/README.md

Creates a CachedProvider with a custom PSR-16 cache implementation and a TTL in seconds. The example uses named arguments for provider, cache, and ttl.

```php
$cachedProvider = new CachedProvider(
    provider: $provider,
    cache: $yourPsr16Cache,
    ttl: 3600, // seconds
);
```

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

### Comparing monies with context-independence

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/abstract-money.md

Shows how to compare Money instances regardless of their context. The example demonstrates that isEqualTo() returns true for equal amounts even with different contexts, compareTo() works with a string, and a CurrencyMismatchException is thrown when comparing different currencies.

```php
use Brick\Money\Money;
use Brick\Money\Context\AutoContext;
use Brick\Money\Exception\CurrencyMismatchException;

$a = Money::of('10.00', 'USD');
$b = Money::of('10.0000', 'USD', new AutoContext());

var_dump($a->isEqualTo($b));   // true — same currency and amount, contexts ignored
var_dump($a->compareTo('9.99')); // 1

try {
    $a->isEqualTo(Money::of(1, 'EUR'));
} catch (CurrencyMismatchException $e) {
    // caught instead of returning false
}
```

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

### Add and subtract Money instances

Source: https://github.com/brick/money/blob/main/README.md

Adds and subtracts Money instances using the plus() and minus() methods. The operations return new Money instances and can be chained. The example shows a cost, shipping, and discount being combined.

```php
use Brick\Money\Money;

$cost = Money::of(25, 'USD');
$shipping = Money::of('4.99', 'USD');
$discount = Money::of('2.50', 'USD');

echo $cost->plus($shipping)->minus($discount); // USD 27.49
```

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

### Create Money from minor units with Money::ofMinor()

Source: https://github.com/brick/money/blob/main/README.md

Creates a Money instance from a number of minor units (e.g., cents) and a currency code. The amount is divided by 100 to get the major unit value.

```php
use Brick\Money\Money;

$money = Money::ofMinor(1234, 'USD'); // USD 12.34
```

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

### Catching MoneyFormatException and other money exceptions

Source: https://github.com/brick/money/blob/main/_autodocs/errors.md

Shows how to catch the specific MoneyMismatchException, its subtypes, and the general MoneyException interface. The example uses $money->minus($otherMoney) which can throw a MoneyMismatchException, and then checks for CurrencyMismatchException to access the expected currency code.

```php
use Brick\Money\Money;
use Brick\Money\Exception\MoneyException;
use Brick\Money\Exception\MoneyMismatchException;
use Brick\Money\Exception\CurrencyMismatchException;
use Brick\MyFormatting;

try {
    $money->minus($otherMoney);
} catch (MoneyMismatchException $e) {
    // CurrencyMismatchException | ContextMismatchException
    if ($e instanceof CurrencyMismatchException) {
        echo $e->getExpectedCurrency()->getCurrencyCode();
    }
} catch (MoneyException $e) {
    // Any other money-library failure
}
```

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

### Chained exact arithmetic with final rounding (RationalMoney pattern)

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/abstract-money.md

Performs a series of exact arithmetic operations on a Money object converted to RationalMoney, then converts the result back to a Money context with a specified rounding mode. The example shows the intermediate rational values and the final rounded results using the default context and a custom context with scale 8.

```php
use Brick\Money\Money;
use Brick\Math\RoundingMode;
use Brick\Money\Context\CustomContext;

$money = Money::of('9.5', 'EUR');                       // EUR 9.50 (Money)
$rational = $money->toRational()                        // EUR 19/2 (RationalMoney)
    ->dividedBy(3)                                      // EUR 19/6
    ->plus('17.795')                                    // EUR 12577/600
    ->multipliedBy('1.196');                            // EUR 3760523/150000

$result = $rational->toContext($money->getContext(), RoundingMode::Down); // EUR 25.07 (Money)
$precise = $rational->toContext(new CustomContext(scale: 8), RoundingMode::Up); // EUR 25.07015334
```

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

### Allocation and Splitting with Modes and Contexts

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

Shows how to allocate a Money amount into ratios using AllocationMode and SplitMode, including with a CashContext for cash rounding. Demonstrates the FloorToFirst and ToFirst modes.

```php
use Brick\Money\Money;
use Brick\Money\AllocationMode;
use Brick\Money\SplitMode;
use Brick\Money\Context\CashContext;

$profit = Money::of('987.65', 'CHF');
[$a, $b, $c] = $profit->allocate([48, 41, 11], AllocationMode::FloorToFirst); // CHF 474.08, 404.93, 108.64

// With cash rounding:
$profit = Money::of('987.65', 'CHF', new CashContext(step: 5));
[$a, $b, $c] = $profit->allocate([48, 41, 11], AllocationMode::FloorToFirst); // CHF 474.10, 404.95, 108.60

[$first, $second, $third] = Money::of(100, 'USD')->split(3, SplitMode::ToFirst); // 33.34, 33.33, 33.33
```

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

### Chain operations with RationalMoney

Source: https://github.com/brick/money/blob/main/README.md

Use RationalMoney to chain operations without intermediate rounding, then convert back to Money with a context and rounding mode. The example shows a chain of operations on EUR 9.50, ending with toContext() applying RoundingMode::Down to get EUR 25.07.

```php
use Brick\Money\Money;
use Brick\Math\RoundingMode;

$money = Money::of('9.5', 'EUR');                       // EUR 9.50 (Money)
$money = $money->toRational()                           // EUR 19/2 (RationalMoney)
  ->dividedBy(3)                                        // EUR 19/6 (RationalMoney)
  ->plus('17.795')                                      // EUR 12577/600 (RationalMoney)
  ->multipliedBy('1.196')                               // EUR 3760523/150000 (RationalMoney)
  ->toContext($money->getContext(), RoundingMode::Down) // EUR 25.07 (Money)
```

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

### Comparing monies across currencies with MoneyComparator

Source: https://github.com/brick/money/blob/main/README.md

Shows how to set up a ConfigurableProvider with an exchange rate, create a MoneyComparator with PairwiseMode, and use compare(), isGreater(), and max() methods. The max() returns the original instance unchanged.

```php
use Brick\Money\Money;
use Brick\Money\MoneyComparator;
use Brick\Money\ComparisonMode\PairwiseMode;
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;

$provider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.10')
    ->build();

$comparator = new MoneyComparator($provider, new PairwiseMode());

$eur = Money::of('10.00', 'EUR'); // worth USD 11.00 at this rate
$usd = Money::of('10.50', 'USD');

$comparator->compare($eur, $usd);   // 1 (EUR 10.00 is worth more than USD 10.50)
$comparator->isGreater($eur, $usd); // true
$comparator->max($eur, $usd);       // EUR 10.00 (the original instance, unchanged)
```

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

### CachedProvider class declaration

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/cached-provider.md

Declares the final readonly CachedProvider class implementing ExchangeRateProvider. Use this as the starting point for the class definition.

```php
namespace Brick\Money\ExchangeRateProvider;

final readonly class CachedProvider implements ExchangeRateProvider
```

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

### PdoProvider with dimensions and ordering

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/pdo-provider.md

Binds dimensions using SqlCondition and orders results by date descending. The example also shows a getExchangeRate call with dimension values.

```php
use Brick\Money\ExchangeRateProvider\PdoProvider;
use Brick\Money\ExchangeRateProvider\Pdo\SqlCondition;

$provider = PdoProvider::builder($pdo, 'exchange_rates', 'exchange_rate')
    ->setSourceCurrencyColumn('source_currency_code')
    ->setTargetCurrencyColumn('target_currency_code')
    ->bindDimension('year', fn (int $year) => new SqlCondition('year = ?', $year))
    ->bindDimension('month', fn (int $month) => new SqlCondition('month = ?', $month))
    ->bindDimension(
        'as_of',
        fn (\DateTimeInterface $date) => new SqlCondition(
            'year = ? AND month = ?',
            (int) $date->format('Y'),
            (int) $date->format('m'),
        ),
    )
    // If several rows can match, pick the latest:
    ->orderBy('date', 'DESC')
    ->build();

$rate = $provider->getExchangeRate(
    Currency::of('EUR'),
    Currency::of('USD'),
    ['year' => 2017, 'month' => 8],
);
```

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

### Configure exchange rates with ConfigurableProvider

Source: https://github.com/brick/money/blob/main/README.md

Build a provider with manual exchange rates using a builder. Add rates with addExchangeRate().

```php
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;

$provider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.1')
    ->addExchangeRate('EUR', 'GBP', '0.9')
    ->build();
```

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

### Currency mismatch exception

Source: https://github.com/brick/money/blob/main/README.md

Attempting to add two Money instances of different currencies throws a CurrencyMismatchException. This example shows that adding USD and EUR amounts is not allowed.

```php
use Brick\Money\Money;

$a = Money::of(1, 'USD');
$b = Money::of(1, 'EUR');

$a->plus($b); // CurrencyMismatchException
```

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

### Get exchange rate with dimensions

Source: https://github.com/brick/money/blob/main/README.md

Fetches an exchange rate from the provider by passing dimension values as an array. The dimensions must match previously bound dimension names.

```php
use Brick\Money\Currency;

$rate = $provider->getExchangeRate(
    Currency::of('EUR'),
    Currency::of('USD'),
    ['year' => 2017, 'month' => 8],
);
```

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

### Basic configuration with ConfigurableProvider

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/configurable-provider.md

Basic configuration of ConfigurableProvider with exchange rates and conversion using CurrencyConverter. Outputs 'USD 109.87'.

```php
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\Money\CurrencyConverter;
use Brick\Money\Money;

$provider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.0987')
    ->addExchangeRate('USD', 'EUR', '0.9123')
    ->addExchangeRate('GBP', 'USD', '1.27')
    ->build();

$converter = new CurrencyConverter($provider);
echo $converter->convert(Money::of('100', 'EUR'), 'USD'); // USD 109.87
```

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

### Using IsoCurrencyProvider to fetch currencies

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/iso-currency-provider.md

Shows how to obtain the singleton IsoCurrencyProvider and use its main methods: getCurrency, getCurrencyByNumericCode, getCurrenciesForCountry, getCurrencyForCountry, getHistoricalCurrenciesForCountry, and getAvailableCurrencies. The comments indicate expected return values for the given inputs.

```php
use Brick\Money\IsoCurrencyProvider;

$provider = IsoCurrencyProvider::getInstance();

$eur = $provider->getCurrency('EUR');          // Euro
$usd = $provider->getCurrencyByNumericCode(840); // US Dollar

// Current and historical currencies per country:
$provider->getCurrenciesForCountry('FR');        // [EUR]
$provider->getCurrencyForCountry('US');          // USD
$provider->getHistoricalCurrenciesForCountry('FR'); // [FRF]
$provider->getAvailableCurrencies();             // all ~300 currencies, indexed by code
```

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

### Build and query a MoneyBag

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/money-bag.md

Creates a MoneyBag with USD and EUR amounts, then demonstrates querying individual currencies and checking if the bag is zero. Shows that missing currencies return a zero RationalMoney without throwing an exception, and that JSON encoding outputs an array of amount/currency objects.

```php
use Brick\Money\Money;
use Brick\Money\MoneyBag;

$bag = MoneyBag::of(
    Money::of('50', 'USD'),
    Money::of('100', 'EUR'),
);

echo $bag->getMoney('USD');                       // USD 50
echo $bag->getMoney('GBP');                       // GBP 0 (zero RationalMoney, no exception)
$bag->isZero();                                   // false
echo json_encode($bag);                           // [{"amount":"100","currency":"EUR"},{"amount":"50","currency":"USD"}]
```

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

### Hide fraction when whole

Source: https://github.com/brick/money/blob/main/README.md

Demonstrates the $hideFractionIfWhole parameter, which drops the fraction digits when the amount has no fraction. The first example shows $5,000 (no decimals), the second shows $5,000.50 (decimals preserved).

```php
$money = Money::of(5000, 'USD');
echo $money->formatToLocale('en_US', CurrencyDisplay::Symbol, hideFractionIfWhole: true); // $5,000

$money = Money::of('5000.50', 'USD');
echo $money->formatToLocale('en_US', CurrencyDisplay::Symbol, hideFractionIfWhole: true); // $5,000.50
```

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

### Bind complex dimension type with DateTimeInterface

Source: https://github.com/brick/money/blob/main/README.md

Binds a dimension that accepts a DateTimeInterface and derives multiple SQL conditions. The example shows binding an 'as_of' dimension and then using it in a getExchangeRate call.

```php
$provider = PdoProvider::builder($pdo, 'exchange_rates', 'exchange_rate')
    ->setSourceCurrencyColumn('source_currency_code')
    ->setTargetCurrencyColumn('target_currency_code')
    ->bindDimension(
        'as_of',
        fn (\DateTimeInterface $date) => new SqlCondition(
            'year = ? AND month = ?',
            (int) $date->format('Y'),
            (int) $date->format('m'),
        ),
    )
    ->build();

$rate = $provider->getExchangeRate(
    Currency::of('EUR'),
    Currency::of('USD'),
    ['as_of' => new \DateTimeImmutable('2017-08-15')],
);
```

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

### getInstance

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/iso-currency-provider.md

Returns the singleton instance of IsoCurrencyProvider.

```APIDOC
## getInstance

### Description
Returns the singleton instance of IsoCurrencyProvider.

### Method
public static function getInstance(): IsoCurrencyProvider

### Returns
- **IsoCurrencyProvider** - The singleton instance.

### Source
`src/IsoCurrencyProvider.php`, line 95.
```

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

### Format money to locale

Source: https://github.com/brick/money/blob/main/README.md

Formats a Money object according to a locale. Requires the intl extension linked against ICU 62.1 or later. The examples show USD 5000 formatted in en_US and fr_FR.

```php
$money = Money::of(5000, 'USD');
echo $money->formatToLocale('en_US'); // $5,000.00
echo $money->formatToLocale('fr_FR'); // 5 000,00 $US
```

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

### Basic conversion with rounding and exact rational conversion

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/currency-converter.md

Shows how to create a CurrencyConverter with a ConfigurableProvider, convert a Money object with a rounding mode, and convert to a rational number without rounding. Also demonstrates that without a rounding mode, an inexact conversion throws a RoundingNecessaryException.

```php
use Brick\Money\CurrencyConverter;
use Brick\Money\Money;
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\Math\RoundingMode;

$provider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.0987')
    ->addExchangeRate('USD', 'EUR', '0.9123')
    ->build();

$converter = new CurrencyConverter($provider);

$money = Money::of('50', 'USD');
$converted = $converter->convert($money, 'EUR', roundingMode: RoundingMode::Up); // EUR 45.62 (45.615 rounded up)
$exact = $converter->convertToRational($money, 'EUR');                 // EUR 9123/200 (no rounding)

// Without a rounding mode, an inexact conversion throws instead of silently rounding:
try {
    $converter->convert(Money::of('50', 'USD'), 'EUR');
} catch (\Brick\Math\Exception\RoundingNecessaryException $e) {
    // 50 * 0.9123 = 45.615 does not fit 2 fraction digits
}
```

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

### Bind dimensions to PdoProvider

Source: https://github.com/brick/money/blob/main/README.md

Binds dimensions to the PdoProvider builder. Each dimension uses a callback that returns a SqlCondition with positional parameters, or null to skip filtering. This example binds 'year' and 'month' dimensions.

```php
use Brick\Money\ExchangeRateProvider\PdoProvider;
use Brick\Money\ExchangeRateProvider\Pdo\SqlCondition;

$provider = PdoProvider::builder($pdo, 'exchange_rates', 'exchange_rate')
    ->setSourceCurrencyColumn('source_currency_code')
    ->setTargetCurrencyColumn('target_currency_code')
    ->bindDimension('year', fn (int $year) => new SqlCondition('year = ?', $year))
    ->bindDimension('month', fn (int $month) => new SqlCondition('month = ?', $month))
    ->build();
```

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

### Formatting with Money::formatToLocale()

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

Shows how to format money using Money::formatToLocale() with different CurrencyDisplay cases and options. The output comments show expected results for en_US and fr_FR locales.

```php
use Brick\Money\Money;
use Brick\Money\CurrencyDisplay;

$money = Money::of('1234.56', 'USD');

echo $money->formatToLocale('en_US');                       // $1,234.56
echo $money->formatToLocale('fr_FR');                       // 1 234,56 $US
echo $money->formatToLocale('en_US', CurrencyDisplay::Code); // USD 1,234.56
echo $money->formatToLocale('en_US', CurrencyDisplay::Name); // 1,234.56 US dollars
echo $money->formatToLocale('en_US', CurrencyDisplay::None); // 1,234.56
echo $money->formatToLocale('en_US', hideFractionIfWhole: true); // $1,235 → stays $1,234.56; for whole values hides decimals
```

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

### Constructor for BaseCurrencyProvider

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/base-currency-provider.md

Constructor accepting an ExchangeRateProvider and a base currency (Currency or string ISO code). Throws UnknownCurrencyException for unknown currency codes.

```php
public function __construct(
    private ExchangeRateProvider $provider,
    Currency|string $baseCurrency,
)
```

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

### Arithmetic with slot removal

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/money-bag.md

Performs plus, minus, and multipliedBy operations on a MoneyBag. When a currency's net amount becomes zero, its slot is removed from the bag. The example shows the resulting amounts and that the bag is not zero.

```php
use Brick\Money\Money;
use Brick\Money\MoneyBag;

$bag = MoneyBag::of(Money::of('100', 'USD'), Money::of('25', 'EUR'));

$result = $bag->plus(Money::of('50.00', 'USD'))   // USD 150, EUR 25
    ->minus(Money::of('25', 'EUR'))               // EUR slot nets to zero and is removed
    ->multipliedBy('0.5');                        // USD 75

echo $result->getMoney('USD'); // USD 75
echo $result->getMoney('EUR'); // EUR 0
$result->isZero();             // false
```

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

### Primary/fallback provider combination

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/chain-provider.md

Shows how to combine a fast ConfigurableProvider with a slow CachedProvider in a ChainProvider, and use it with a CurrencyConverter. The chain tries the quick provider first and falls back to the slow one.

```php
use Brick\Money\ExchangeRateProvider\ChainProvider;
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\Money\ExchangeRateProvider\CachedProvider;
use Brick\Money\CurrencyConverter;

$quickProvider = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.0987')
    ->build();

$slowProvider = new CachedProvider($yourVariableProvider, ttl: 300);

$provider = new ChainProvider($quickProvider, $slowProvider);

$converter = new CurrencyConverter($provider);
$converted = $converter->convert($money, 'USD'); // tries $quickProvider first, falls back to $slowProvider
```

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

### allocate() method signature

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

Allocates this money according to a list of ratios. Ratios must be non-negative and sum to a non-zero value. Results have the same context as this money. Throws ContextException if the context is not fixed, MathException for invalid ratio numbers, and InvalidArgumentException if the ratio list is empty, contains negatives, or sums to zero.

```php
public function allocate(array $ratios, AllocationMode $mode): array
```

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

### Context interface methods

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/context.md

Lists the methods that implementations must provide. applyTo() must respect the given rounding mode, getStep() returns the cash rounding step in minor units, isFixedScale() is false only for AutoContext, and __toString() returns a debug representation.

```php
public function applyTo(BigNumber $amount, Currency $currency, RoundingMode $roundingMode): BigDecimal;
public function getStep(): int;
public function isFixedScale(): bool;
public function isEqualTo(Context $context): bool;
public function __toString(): string;
```

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

### Context interface definition

Source: https://github.com/brick/money/blob/main/_autodocs/types.md

Defines the Context interface extending Stringable. It declares methods for applying rounding, getting the step, checking fixed scale, equality, and string conversion. Implementations include DefaultContext, CashContext, CustomContext, and AutoContext.

```php
interface Context extends Stringable
{
    public function applyTo(BigNumber $amount, Currency $currency, RoundingMode $roundingMode): BigDecimal;
    public function getStep(): int;
    public function isFixedScale(): bool;
    public function isEqualTo(Context $context): bool;
    public function __toString(): string;
}
```

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

### ConfigurableProviderBuilder::build() method

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/configurable-provider.md

Builds the immutable ConfigurableProvider from the configured rates.

```php
public function build(): ConfigurableProvider
```

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

### RationalMoney::__construct

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/rational-money.md

Constructor for creating a RationalMoney instance.

```APIDOC
## Constructor

```php
public function __construct(
    private BigRational $amount,
    private Currency $currency,
)
```

### Parameters
- `$amount` (BigRational) - Required - The exact amount.
- `$currency` (Currency) - Required - The currency.

### Description
Creates a new `RationalMoney` instance with the given exact amount and currency.
```

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

### Allocate money with CashContext and AllocationMode::FloorToFirst

Source: https://github.com/brick/money/blob/main/README.md

Allocates a profit of 987.65 CHF with a CashContext step of 5, using AllocationMode::FloorToFirst. The result is CHF 474.10, CHF 404.95, CHF 108.60.

```php
use Brick\Money\Money;
use Brick\Money\AllocationMode;
use Brick\Money\Context\CashContext;

$profit = Money::of('987.65', 'CHF', new CashContext(step: 5));

// CHF 474.10, CHF 404.95, CHF 108.60
[$a, $b, $c] = $profit->allocate([48, 41, 11], AllocationMode::FloorToFirst);
```

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

### Error handling and comparison

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/money-bag.md

Shows how to catch a DivisionByZeroException when dividing a MoneyBag by zero. Also demonstrates that a MoneyBag can be compared for equality with a single Money instance of the same value.

```php
use Brick\Money\Money;
use Brick\Money\MoneyBag;
use Brick\Math\Exception\DivisionByZeroException;

$bag = MoneyBag::of(Money::of('10', 'USD'));

try {
    $bag->dividedBy(0);
} catch (DivisionByZeroException $e) {
    // division by zero
}

// The bag compares equal to a single Money of the same value:
var_dump($bag->isEqualTo(Money::of('10', 'USD')));  // true
```

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

### PdoProviderBuilder::build

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/pdo-provider.md

Builds the PdoProvider instance. Validates that a source currency selector is configured.

```APIDOC
## PdoProviderBuilder::build

### Description
Builds the PdoProvider instance. Validates that a source currency selector is configured.

### Method
Builder method

### Signature
```php
public function build(): PdoProvider
```

### Returns
- `PdoProvider` - The configured provider.

### Throws
- `Brick\Money\Exception\InvalidArgumentException` if no source currency selector is configured.
```

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

### ConfigurableProviderBuilder::build()

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/configurable-provider.md

Builds the immutable ConfigurableProvider from the configured rates.

```APIDOC
## ConfigurableProviderBuilder::build()

### Description
Builds and returns the immutable ConfigurableProvider instance using the rates added to this builder.

### Method
public

### Signature
```php
public function build(): ConfigurableProvider
```

### Parameters
None

### Return Value
- **ConfigurableProvider** - A new immutable provider with the configured rates.

### Source
`src/ExchangeRateProvider/Configurable/ConfigurableProviderBuilder.php`, line 82.
```

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

### Currency Constructor

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/currency.md

The constructor initializes a new currency instance. It requires a currency code, numeric code, name, and default fraction digits, with an optional currency type.

```php
public function __construct(
    private string $currencyCode,
    private ?int $numericCode,
    private string $name,
    private int $defaultFractionDigits,
    private CurrencyType $currencyType = CurrencyType::Custom,
)
```

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

### compareTo method signature

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/abstract-money.md

Compares this money to another amount. Currency must match if the argument is a money. Context is not checked.

```php
final public function compareTo(AbstractMoney|BigNumber|int|string $that): int
```

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

### Custom provider implementation

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/exchange-rate-provider.md

Shows how to implement a custom provider. Returns 1 for same-currency pairs, throws ExchangeRateProviderException only for operational errors, and returns null for missing rates or unsupported dimensions.

```php
use Brick\Money\Currency;
use Brick\Money\ExchangeRateProvider;
use Brick\Math\BigNumber;
use Brick\Money\Exception\ExchangeRateProviderException;

final class MyProvider implements ExchangeRateProvider
{
    public function getExchangeRate(Currency $sourceCurrency, Currency $targetCurrency, array $dimensions = []): ?BigNumber
    {
        if ($sourceCurrency->isEqualTo($targetCurrency)) {
            return BigNumber::of(1);
        }

        try {
            $rate = $this->fetchFromRemoteApi($sourceCurrency, $targetCurrency, $dimensions);
        } catch (NetworkException $e) {
            // Operational errors throw; missing rates return null:
            throw new ExchangeRateProviderException('Failed to fetch exchange rate.', $e);
        }

        return $rate === null ? null : BigNumber::of($rate);
    }
}

```

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

### Compare monies with isEqualTo and isSameValueAs

Source: https://github.com/brick/money/blob/main/README.md

Shows how to compare Money instances. isEqualTo throws CurrencyMismatchException on currency mismatch, while isSameValueAs does not.

```php
$oneEuro = Money::of(1, 'EUR');

$oneEuro->isEqualTo(Money::of(1, 'EUR')); // true
$oneEuro->isEqualTo(Money::of(2, 'EUR')); // false
$oneEuro->isEqualTo(Money::of(1, 'USD')); // CurrencyMismatchException

$oneEuro->isSameValueAs(Money::of(1, 'EUR')); // true
$oneEuro->isSameValueAs(Money::of(2, 'EUR')); // false
$oneEuro->isSameValueAs(Money::of(1, 'USD')); // false
```

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

### Create PdoProvider with builder

Source: https://github.com/brick/money/blob/main/README.md

Creates a PdoProvider using a PDO connection and table/column names. The builder requires the PDO instance, table name, and exchange rate column, with optional source and target currency column setters.

```php
use Brick\Money\ExchangeRateProvider\PdoProvider;

$pdo = new \PDO(...);

$provider = PdoProvider::builder($pdo, 'exchange_rates', 'exchange_rate')
    ->setSourceCurrencyColumn('source_currency_code')
    ->setTargetCurrencyColumn('target_currency_code')
    ->build();
```

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

### Error Handling for Currency and Rounding Exceptions

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

Demonstrates catching CurrencyMismatchException when adding different currencies and RoundingNecessaryException when division requires rounding. Shows how to handle these errors and retry with a rounding mode.

```php
use Brick\Money\Money;
use Brick\Math\RoundingMode;
use Brick\Money\Exception\CurrencyMismatchException;
use Brick\Money\Exception\ContextMismatchException;
use Brick\Math\Exception\RoundingNecessaryException;

$a = Money::of(1, 'USD');
$b = Money::of(1, 'EUR');

try {
    $a->plus($b);
} catch (CurrencyMismatchException $e) {
    // "The monies do not share the same currency: expected USD, got EUR."
    echo $e->getExpectedCurrency()->getCurrencyCode(); // USD
}

try {
    Money::of(50, 'USD')->dividedBy(3); // needs rounding
} catch (RoundingNecessaryException $e) {
    $money = Money::of(50, 'USD')->dividedBy(3, RoundingMode::Up); // USD 16.67
}
```

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

### Using MoneyLocaleFormatter directly

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

Creates a MoneyLocaleFormatter with a specific locale and CurrencyDisplay, then formats a Money object. The output for fr_CH with USD is shown in the comment.

```php
use Brick\Money\Formatter\MoneyLocaleFormatter;
use Brick\Money\CurrencyDisplay;

$formatter = new MoneyLocaleFormatter('fr_CH', CurrencyDisplay::Symbol);
echo $formatter->format(Money::of('1234.56', 'USD')); // 1 234,56 $US
```

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

### ChainProvider::__construct

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/chain-provider.md

Creates a new ChainProvider instance with the given providers, tried in the given order.

```APIDOC
## ChainProvider::__construct

### Description
Creates a new ChainProvider instance with the given providers, tried in the given order.

### Method
Constructor

### Signature
```php
public function __construct(ExchangeRateProvider ...$providers)
```

### Parameters
- **$providers** (ExchangeRateProvider...) - Required - The providers, tried in the given order.

### Source
`src/ExchangeRateProvider/ChainProvider.php`, line 23.
```

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

### Constructor

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

Creates a new MoneyLocaleFormatter instance with the specified locale, currency display style, and fraction hiding option.

```APIDOC
## Constructor

### Description
Initializes a new MoneyLocaleFormatter instance.

### Method
Constructor

### Signature
```php
public function __construct(string $locale, CurrencyDisplay $currencyDisplay = CurrencyDisplay::Symbol, bool $hideFractionIfWhole = false)
```

### Parameters
- **$locale** (string) - Required - The locale to format to, e.g. `'fr_FR'`, `'en_US'`.
- **$currencyDisplay** (CurrencyDisplay) - Optional - How the currency is displayed. Defaults to `CurrencyDisplay::Symbol`.
- **$hideFractionIfWhole** (bool) - Optional - Hide the fraction digits when the amount is a whole number. Defaults to `false`.

### Throws
- `MoneyFormatException` if the intl extension is not installed, the ICU version is too old, or ICU has no data for the locale's language.
```

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

### Basic lookups and custom currency

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/currency.md

Shows basic Currency lookups using of() and ofCountry(), and creating a custom non-ISO currency with the public constructor. Outputs codes, names, and fraction digits.

```php
use Brick\Money\Currency;
use Brick\Money\CurrencyType;

$eur = Currency::of('EUR');
echo $eur->getCurrencyCode();          // EUR
echo $eur->getNumericCode();           // 978
echo $eur->getName();                  // Euro
echo $eur->getDefaultFractionDigits(); // 2

$currency = Currency::ofCountry('JP');
echo $currency->getCurrencyCode();     // JPY

// Custom (non-ISO) currency — the constructor is public:
$gold = new Currency('XAU', 959, 'Gold', 4, CurrencyType::Custom);
echo $gold->getCurrencyType()->name;   // Custom
```

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

### Basic usage with default in-memory cache

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/cached-provider.md

Wraps a ConfigurableProvider in a CachedProvider to cache exchange rates in memory. The first call to convert queries the inner provider; subsequent calls hit the cache.

```php
use Brick\Money\ExchangeRateProvider\CachedProvider;
use Brick\Money\ExchangeRateProvider\ConfigurableProvider;
use Brick\Money\CurrencyConverter;

$inner = ConfigurableProvider::builder()
    ->addExchangeRate('EUR', 'USD', '1.0987')
    ->build();

$cachedProvider = new CachedProvider($inner);

$converter = new CurrencyConverter($cachedProvider);
$converted = $converter->convert($money, 'USD'); // first call queries $inner, subsequent calls hit the cache
```

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

### Use CashContext for cash rounding

Source: https://github.com/brick/money/blob/main/README.md

Shows how to use CashContext with a step of 5 for CHF to round to 0.05 increments. dividedBy with RoundingMode::Down and Up demonstrates the rounding behavior.

```php
use Brick\Money\Money;
use Brick\Money\Context\CashContext;
use Brick\Math\RoundingMode;

$money = Money::of(10, 'CHF', new CashContext(step: 5)); // CHF 10.00
$money->dividedBy(3, RoundingMode::Down); // CHF 3.30
$money->dividedBy(3, RoundingMode::Up); // CHF 3.35
```

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

### ConfigurableProvider::builder() method

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/configurable-provider.md

Static factory method returning a new ConfigurableProviderBuilder instance.

```php
public static function builder(): ConfigurableProviderBuilder
```

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

### ChainProvider constructor

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/chain-provider.md

Constructor that accepts a variadic list of ExchangeRateProvider instances to be tried in order.

```php
public function __construct(ExchangeRateProvider ...$providers)
```

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

### Money::plus() method signature

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

Returns the sum of this money and the given operand. If the operand is a Money, its context must equal this money's context. If the operand is a RationalMoney, the context check is skipped and the result is fitted to this money's context. Throws MathException, RoundingNecessaryException, CurrencyMismatchException, ContextMismatchException (for Money operands), and ContextException. Source: src/Money.php, line 308.

```php
public function plus(AbstractMoney|BigNumber|int|string $that, RoundingMode $roundingMode = RoundingMode::Unnecessary): Money
```

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

### MoneyLocaleFormatter::__construct() and format()

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

Direct formatter usage: constructs a MoneyLocaleFormatter with a locale and currency display, then formats Money objects.

```APIDOC
## MoneyLocaleFormatter::__construct() and format()

### Description
Creates a locale formatter and formats Money objects directly.

### Constructor
`__construct(string $locale, CurrencyDisplay $currencyDisplay)`

### Method
`format(Money $money): string`

### Parameters
- **$locale** (string) - Required - The locale to format for (e.g., 'fr_CH').
- **$currencyDisplay** (CurrencyDisplay) - Required - The currency display mode.
- **$money** (Money) - Required - The money object to format.

### Return Value
(string) - The formatted money string.

### Usage Example
```php
use Brick\Money\Formatter\MoneyLocaleFormatter;
use Brick\Money\CurrencyDisplay;

$formatter = new MoneyLocaleFormatter('fr_CH', CurrencyDisplay::Symbol);
echo $formatter->format(Money::of('1234.56', 'USD')); // 1 234,56 $US
```
```

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

### new Currency()

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/currency.md

Creates a new immutable Currency instance. The constructor is public, allowing definition of both ISO and custom currencies.

```APIDOC
## Constructor

### Description
Creates a new immutable Currency instance. For ISO currencies, properties come from the bundled ISO 4217 dataset; for custom currencies, all properties must be provided.

### Method
Constructor

### Signature
```php
public function __construct(
    private string $currencyCode,
    private ?int $numericCode,
    private string $name,
    private int $defaultFractionDigits,
    private CurrencyType $currencyType = CurrencyType::Custom,
)
```

### Parameters
#### Parameters
- **$currencyCode** (`non-empty-string`) - Required - The currency code. For ISO currencies this is the 3-letter uppercase ISO 4217 code; for non-ISO currencies it must be unique across the application and must not conflict with ISO codes.
- **$numericCode** (`non-negative-int|null`) - Required - The ISO 4217 numeric code; `null` if the currency has no numeric code. Must be unique across the application for non-ISO currencies.
- **$name** (`non-empty-string`) - Required - The currency name (official English name for ISO currencies).
- **$defaultFractionDigits** (`non-negative-int`) - Required - Default number of fraction digits (typical scale), e.g. `2` for EUR, `0` for JPY.
- **$currencyType** (`CurrencyType`) - Optional (default: `CurrencyType::Custom`) - `IsoCurrent`, `IsoHistorical`, or `Custom`.

### Throws
- `Brick\Money\Exception\InvalidArgumentException` if `$defaultFractionDigits < 0`.

### Example
```php
$currency = new Currency('USD', 840, 'US Dollar', 2, CurrencyType::IsoCurrent);
```
```

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

### Constructor signature: __construct(string $locale, CurrencyDisplay $currencyDisplay = CurrencyDisplay::Symbol, bool $hideFractionIfWhole = false)

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

Defines the constructor for MoneyLocaleFormatter. The locale is required; currency display defaults to CurrencyDisplay::Symbol and hideFractionIfWhole defaults to false. Throws MoneyFormatException if the intl extension is missing, ICU version is too old, or ICU lacks data for the locale's language.

```php
public function __construct(string $locale, CurrencyDisplay $currencyDisplay = CurrencyDisplay::Symbol, bool $hideFractionIfWhole = false)
```

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

### ConfigurableProvider::builder()

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/configurable-provider.md

Creates a new builder for constructing a ConfigurableProvider instance. The class constructor is private, so this is the entry point.

```APIDOC
## ConfigurableProvider::builder()

### Description
Returns a new builder for creating a ConfigurableProvider instance.

### Method
static

### Signature
```php
public static function builder(): ConfigurableProviderBuilder
```

### Parameters
None

### Return Value
- **ConfigurableProviderBuilder** - A new builder instance.

### Source
`src/ExchangeRateProvider/ConfigurableProvider.php`, line 41.
```

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

### Create Money with Money::of()

Source: https://github.com/brick/money/blob/main/README.md

Creates a Money instance from a numeric or string amount and a currency code. The amount is rounded to the currency's default decimal places (2 for USD) using the default rounding mode (necessary), which throws RoundingNecessaryException if rounding is needed. The rounding mode is only applied once and not stored.

```php
use Brick\Money\Money;

$money = Money::of(50, 'USD'); // USD 50.00
$money = Money::of('19.9', 'USD'); // USD 19.90
```

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

### BaseCurrencyProvider::__construct

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/base-currency-provider.md

Creates a new BaseCurrencyProvider wrapping an ExchangeRateProvider and specifying the base currency. Throws UnknownCurrencyException if an unknown currency code is given.

```APIDOC
## BaseCurrencyProvider::__construct

### Description
Creates a new BaseCurrencyProvider wrapping an ExchangeRateProvider and specifying the base currency.

### Method
Constructor

### Signature
```php
public function __construct(
    private ExchangeRateProvider $provider,
    Currency|string $baseCurrency,
)
```

### Parameters
- **$provider** (ExchangeRateProvider) - Required - The provider for rates relative to the base currency.
- **$baseCurrency** (Currency|string) - Required - The currency (or ISO code) all rates are based on.

### Throws
- **Brick\Money\Exception\UnknownCurrencyException** - If an unknown currency code is given.

### Source
`src/ExchangeRateProvider/BaseCurrencyProvider.php`, line 35.
```

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

### Using a custom provider with CurrencyConverter

Source: https://github.com/brick/money/blob/main/_autodocs/api-reference/exchange-rate-provider.md

Wires a custom provider into CurrencyConverter. The converter calls getExchangeRate() per source currency and passes dimensions through.

```php
use Brick\Money\CurrencyConverter;

$converter = new CurrencyConverter(new MyProvider());
$converted = $converter->convert($money, 'EUR');

```
Tokens:
Raw