### Composer Installation

Source: https://github.com/moneyphp/money/blob/master/README.md

Instructions for installing the Money PHP library using Composer, the dependency manager for PHP.

```bash
$composer require moneyphp/money

```

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

### Install MoneyPHP Money Library

Source: https://github.com/moneyphp/money/blob/master/doc/getting-started.rst

Provides the Composer command to install the MoneyPHP Money library. This is the standard method for adding the library to a PHP project.

```bash
$ composer require moneyphp/money
```

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

### Install Exchanger Library

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Instructions to install the Exchanger library, a framework for currency exchange rates, using Composer. This library can be used with MoneyPHP.

```bash
$ composer require florianv/exchanger
```

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

### Install Swap Library

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Instructions to install the Swap library, a popular PHP currency exchange library, using Composer. This library can be integrated with MoneyPHP for real-time exchange rates.

```bash
$ composer require florianv/swap
```

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

### Decimal Parser Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/parsing.rst

Parses simple decimal strings in a consistent format, independent of locale. Requires a currency repository to determine the correct subunit.

```php
use Money\Currency;
use Money\Currencies\ISOCurrencies;
use Money\Parser\DecimalMoneyParser;

$currencies = new ISOCurrencies();

$moneyParser = new DecimalMoneyParser($currencies);

$money = $moneyParser->parse('1000', new Currency('USD'));

echo $money->getAmount(); // outputs 100000
```

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

### Intl Money Parser Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/parsing.rst

Parses monetary strings using the intl extension and NumberFormatter. Requires the intl extension and a currency repository. Outputs the amount in subunits.

```php
use Money\Currencies\ISOCurrencies;
use Money\Parser\IntlMoneyParser;

$currencies = new ISOCurrencies();

$numberFormatter = new \NumberFormatter('en_US', \NumberFormatter::CURRENCY);
$moneyParser = new IntlMoneyParser($numberFormatter, $currencies);

$money = $moneyParser->parse('$1.00');

echo $money->getAmount(); // outputs 100
```

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

### Decimal Money Formatter Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/formatting.rst

Outputs a simple, consistent decimal string representation of money, independent of locale. It requires a currency repository.

```php
use Money\Currencies\ISOCurrencies;
use Money\Currency;
use Money\Formatter\DecimalMoneyFormatter;
use Money\Money;

$money = new Money(100, new Currency('USD'));
$currencies = new ISOCurrencies();

$moneyFormatter = new DecimalMoneyFormatter($currencies);

echo $moneyFormatter->format($money); // outputs 1.00
```

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

### Aggregate Money Formatter Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/formatting.rst

Combines multiple formatters and selects the most appropriate one based on the currency code. Useful for supporting multiple currencies with a single formatter instance.

```php
use Money\Currencies\BitcoinCurrencies;
use Money\Currencies\ISOCurrencies;
use Money\Currency;
use Money\Formatter\AggregateMoneyFormatter;
use Money\Formatter\BitcoinMoneyFormatter;
use Money\Formatter\IntlMoneyFormatter;
use Money\Money;

$dollars = new Money(100, new Currency('USD'));
$bitcoin = new Money(100, new Currency('XBT'));

$numberFormatter = new \NumberFormatter('en_US', \NumberFormatter::CURRENCY);
$intlFormatter = new IntlMoneyFormatter($numberFormatter, new ISOCurrencies());
$bitcoinFormatter = new BitcoinMoneyFormatter(7, new BitcoinCurrencies());

$moneyFormatter = new AggregateMoneyFormatter([
    'USD' => $intlFormatter,
    'XBT' => $bitcoinFormatter,
]);

echo $moneyFormatter->format($dollars); // outputs $1.00
echo $moneyFormatter->format($bitcoin); // outputs Ƀ0.0000010
```

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

### MoneyPHP Teller Usage Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/teller.rst

Demonstrates the difference between traditional float multiplication for monetary values and using the MoneyPHP Teller for accurate calculations. The Teller ensures precision by avoiding floating-point arithmetic issues.

```php
// before
$price = 234.56;
$discount = 0.05;
$discountAmount = $price * $discount; // 11.728

// after
$teller = \Money\Teller::USD();
$discountAmount = $teller->multiply($price, $discount); // '11.73'
```

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

### Aggregate Money Parser Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/parsing.rst

Combines multiple money parsers, attempting to parse a string with each until one succeeds. Useful for handling various monetary formats within a single parser instance.

```php
use Money\Parser\AggregateMoneyParser;
use Money\Parser\BitcoinMoneyParser;
use Money\Parser\IntlMoneyParser;

$numberFormatter = new \NumberFormatter('en_US', \NumberFormatter::CURRENCY);
$intlParser = new IntlMoneyParser($numberFormatter, 2);
$bitcoinParser = new BitcoinMoneyParser(2);

$moneyParser = new AggregateMoneyParser([
    $intlParser,
    $bitcoinParser,
]);

$dollars = $moneyParser->parse('1 USD');
$bitcoin = $moneyParser->parse("Ƀ1.00");
```

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

### Intl Money Formatter Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/formatting.rst

Formats money using the Intl extension and NumberFormatter, requiring the 'intl' extension and a currency repository. It displays the currency sign and uses locale-specific formatting.

```php
use Money\Currencies\ISOCurrencies;
use Money\Currency;
use Money\Formatter\IntlMoneyFormatter;
use Money\Money;

$money = new Money(100, new Currency('USD'));
$currencies = new ISOCurrencies();

$numberFormatter = new \NumberFormatter('en_US', \NumberFormatter::CURRENCY);
$moneyFormatter = new IntlMoneyFormatter($numberFormatter, $currencies);

echo $moneyFormatter->format($money); // outputs $1.00
```

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

### Intl Localized Decimal Parser Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/parsing.rst

Parses localized decimal strings using the intl extension and NumberFormatter. Requires the intl extension and a currency repository. Handles locale-specific decimal separators and grouping.

```php
use Money\Currency;
use Money\Currencies\ISOCurrencies;
use Money\Parser\IntlLocalizedDecimalParser;

$currencies = new ISOCurrencies();

$numberFormatter = new \NumberFormatter('nl_NL', \NumberFormatter::DECIMAL);
$moneyParser = new IntlLocalizedDecimalParser($numberFormatter, $currencies);

$money = $moneyParser->parse('1.000,00', new Currency('EUR'));

echo $money->getAmount(); // outputs 100000
```

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

### Intl Localized Decimal Formatter Example

Source: https://github.com/moneyphp/money/blob/master/doc/features/formatting.rst

Formats money using the Intl extension and NumberFormatter for localized decimal values without a currency sign. It requires the 'intl' extension and a currency repository.

```php
use Money\Currencies\ISOCurrencies;
use Money\Currency;
use Money\Formatter\IntlLocalizedDecimalFormatter;
use Money\Money;

$money = new Money(100000, new Currency('EUR'));
$currencies = new ISOCurrencies();

$numberFormatter = new \NumberFormatter('nl_NL', \NumberFormatter::DECIMAL);
$moneyFormatter = new IntlLocalizedDecimalFormatter($numberFormatter, $currencies);

echo $moneyFormatter->format($money); // outputs 1.000,00
```

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

### Instantiate Money Object

Source: https://github.com/moneyphp/money/blob/master/doc/getting-started.rst

Demonstrates how to create Money objects using the MoneyPHP library. It shows both the standard constructor and a static factory method. Requires the Money and Currency classes.

```php
use Money\Currency;
use Money\Money;

$fiver = new Money(500, new Currency('USD'));
// or shorter:
$fiver = Money::USD(500);
```

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

### Running Tests

Source: https://github.com/moneyphp/money/blob/master/README.md

Command to run the library's tests using Composer and PHPUnit.

```bash
$composer test

```

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

### Dockerized Test Execution

Source: https://github.com/moneyphp/money/blob/master/README.md

Steps to build a Docker image for the Money PHP library and run tests within a Docker container, useful for setting up a consistent testing environment.

```bash
$docker build -t moneyphp .
$docker run --rm -it -v $PWD:/app -w /app moneyphp vendor/bin/phpunit --exclude-group segmentation

```

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

### Basic Money Operations

Source: https://github.com/moneyphp/money/blob/master/README.md

Demonstrates basic usage of the Money library, including creating Money objects, adding them, and allocating amounts. It highlights the immutability and precision of monetary calculations.

```php
<?php

use Money\Money;

$fiveEur = Money::EUR(500);
$tenEur = $fiveEur->add($fiveEur);

list($part1, $part2, $part3) = $tenEur->allocate([1, 1, 1]);
assert($part1->equals(Money::EUR(334)));
assert($part2->equals(Money::EUR(333)));
assert($part3->equals(Money::EUR(333)));

```

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

### Absolute Value of Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/features/operation.rst

Demonstrates how to get the absolute value of a Money object using the `absolute()` method. This immutable operation returns a new Money object with a non-negative value.

```php
$value = Money::EUR(-800);

    $result = $value->absolute();    // €8.00
```

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

### Accepted Integer Values for Money Instantiation

Source: https://github.com/moneyphp/money/blob/master/doc/getting-started.rst

Illustrates the types of numeric values accepted by the MoneyPHP Money object constructor. It highlights valid integer and string representations, and invalid formats that will throw an \InvalidArgumentException. Requires the Money and Currency classes.

```php
use Money\Currency;
use Money\Money;

// int is accepted
$fiver = new Money(500, new Currency('USD'));

// string is accepted if integer
$fiver = new Money('500', new Currency('USD'));

// string is accepted if fractional part is zero
$fiver = new Money('500.00', new Currency('USD'));

// leading zero's are not accepted
$fiver = new Money('00500', new Currency('USD'));

// multiple zero's are not accepted
$fiver = new Money('000', new Currency('USD'));
```

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

### Create CurrencyPair Object

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Demonstrates creating a `CurrencyPair` object, which represents a conversion rate between two currencies. It shows how to instantiate it directly with currencies and rate, or parse it from an ISO notation string.

```php
use Money\Currency;
use Money\CurrencyPair;

$pair = new CurrencyPair(new Currency('EUR'), new Currency('USD'), 1.2500);
```

```php
use Money\CurrencyPair;

$pair = CurrencyPair::createFromIso('EUR/USD 1.2500');
```

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

### Bitcoin Currency Usage

Source: https://github.com/moneyphp/money/blob/master/doc/features/bitcoin.rst

Demonstrates the construction of a Bitcoin currency object, its formatting, and parsing using the BitcoinMoneyFormatter and BitcoinMoneyParser classes from the MoneyPHP library. It highlights the subunit of 8 for Bitcoin.

```php
use Money\Currencies\BitcoinCurrencies;
use Money\Currency;
use Money\Formatter\BitcoinMoneyFormatter;
use Money\Money;
use Money\Parser\BitcoinMoneyParser;

// construct bitcoin (subunit of 8)
$money = new Money(100000000000, new Currency('XBT'));

// construct bitcoin currencies
$currencies = new BitcoinCurrencies();

// format bitcoin
$formatter = new BitcoinMoneyFormatter(2, $currencies);
echo $formatter->format($money); // prints Ƀ1000.00

// parse bitcoin
$parser = new BitcoinMoneyParser(2);
$money = $parser->parse("Ƀ1000.00", 'XBT');
echo $money->getAmount(); // outputs 100000000000
```

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

### Swap Exchange Integration

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Demonstrates integrating the Swap library with MoneyPHP for currency conversion. It involves creating a `SwapExchange` instance using a Swap interface implementation and then using it with the `Converter`.

```php
use Money\Money;
use Money\Converter;
use Money\Currencies\ISOCurrencies;
use Money\Exchange\SwapExchange;

// $swap = Implementation of \Swap\SwapInterface
$exchange = new SwapExchange($swap);

$converter = new Converter(new ISOCurrencies(), $exchange);
$eur100 = Money::EUR(100);
$usd125 = $converter->convert($eur100, new Currency('USD'));
[$usd125, $pair] = $converter->convertAndReturnWithCurrencyPair($eur100, new Currency('USD'));
```

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

### MoneyPHP Teller API Documentation

Source: https://github.com/moneyphp/money/blob/master/doc/features/teller.rst

Comprehensive documentation for the MoneyPHP Teller class, covering its various methods for monetary operations, comparisons, allocations, aggregations, and conversions. This API reference details method signatures, parameters, return types, and usage.

```APIDOC
Teller:
  USD() : Teller
    Creates a Teller instance for USD currency.

  EUR() : Teller
    Creates a Teller instance for EUR currency.

  // Operation Methods
  absolute($amount) : string
    Returns an absolute monetary amount.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: The absolute monetary amount as a string.

  add($amount, $other, ...$others) : string
    Adds one or more monetary amounts to a monetary amount.
    Parameters:
      - $amount: The base monetary amount (string or float).
      - $other: The monetary amount(s) to add (string or float).
    Returns: The sum of the monetary amounts as a string.

  divide($amount, $divisor) : string
    Divides a monetary amount by a divisor.
    Parameters:
      - $amount: The monetary amount to divide (string or float).
      - $divisor: The divisor (numeric).
    Returns: The result of the division as a string.

  mod($amount, $divisor)
    Returns the mod of one amount by another.
    Parameters:
      - $amount: The monetary amount (string or float).
      - $divisor: The divisor (numeric).
    Returns: The modulo result.

  multiply($amount, $multiplier) : string
    Multiplies a monetary amount by a multiplier.
    Parameters:
      - $amount: The monetary amount to multiply (string or float).
      - $multiplier: The multiplier (numeric).
    Returns: The product as a string.

  negative($amount) : string
    Negates a monetary amount.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: The negated monetary amount as a string.

  ratioOf($amount, $other)
    Determines the ratio of one monetary amount to another.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: The ratio.

  subtract($amount, $other, ...$others) : string
    Subtracts one or more monetary amounts from a monetary amount.
    Parameters:
      - $amount: The base monetary amount (string or float).
      - $other: The monetary amount(s) to subtract (string or float).
    Returns: The result of the subtraction as a string.

  // Comparison Methods
  compare($amount, $other) : int
    Compares one monetary amount to the other.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: -1 if $amount < $other, 0 if $amount == $other, 1 if $amount > $other.

  equals($amount, $other) : bool
    Checks if two monetary amounts are equal.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: true if equal, false otherwise.

  greaterThan($amount, $other) : bool
    Checks if one monetary amount is greater than the other.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: true if $amount > $other, false otherwise.

  greaterThanOrEqual($amount, $other) : bool
    Checks if one monetary amount is greater than or equal to the other.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: true if $amount >= $other, false otherwise.

  isNegative($amount) : bool
    Checks if a monetary amount is less than zero.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: true if the amount is negative, false otherwise.

  isPositive($amount) : bool
    Checks if a monetary amount is greater than zero.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: true if the amount is positive, false otherwise.

  isZero($amount) : bool
    Checks if a monetary amount is equal to zero.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: true if the amount is zero, false otherwise.

  lessThan($amount, $other) : bool
    Checks if one monetary amount is less than the other.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: true if $amount < $other, false otherwise.

  lessThanOrEqual($amount, $other) : bool
    Checks if one monetary amount is less than or equal to the other.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $other: The second monetary amount (string or float).
    Returns: true if $amount <= $other, false otherwise.

  // Allocation Methods
  allocate($amount, array $ratios) : string[]
    Allocates a monetary amount according to an array of ratios.
    Parameters:
      - $amount: The monetary amount to allocate (string or float).
      - $ratios: An associative array where keys are identifiers and values are ratios.
    Returns: An array of allocated monetary amounts as strings.

  allocateTo($amount, $n) : string[]
    Allocates a monetary amount among N targets.
    Parameters:
      - $amount: The monetary amount to allocate (string or float).
      - $n: The number of targets to allocate to.
    Returns: An array of allocated monetary amounts as strings.

  // Aggregation Methods
  avg($amount, ...$amounts) : string
    Averages a series of monetary amounts.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $amounts: Additional monetary amounts (string or float).
    Returns: The average monetary amount as a string.

  sum($amount, ...$amounts) : string
    Sums a series of monetary amounts.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $amounts: Additional monetary amounts (string or float).
    Returns: The sum of the monetary amounts as a string.

  max($amount, ...$amounts) : string
    Finds the highest of a series of monetary amounts.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $amounts: Additional monetary amounts (string or float).
    Returns: The highest monetary amount as a string.

  min($amount, ...$amounts) : string
    Finds the lowest of a series of monetary amounts.
    Parameters:
      - $amount: The first monetary amount (string or float).
      - $amounts: Additional monetary amounts (string or float).
    Returns: The lowest monetary amount as a string.

  // Conversion Methods
  convertToMoney($amount) : Money
    Converts a monetary amount to a Money object.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: A Money object.

  convertToMoneyArray(array $amounts) : Money[]
    Converts an array of monetary amounts to an array of Money objects.
    Parameters:
      - $amounts: An array of monetary amounts (string or float).
    Returns: An array of Money objects.

  convertToString($amount) : string
    Converts a monetary amount to a string.
    Parameters:
      - $amount: The monetary amount (string or float).
    Returns: The monetary amount as a string.

  convertToStringArray($amount) : string[]
    Converts an array of monetary amounts to an array of strings.
    Parameters:
      - $amounts: An array of monetary amounts (string or float).
    Returns: An array of monetary amounts as strings.

  zero() : string
    Returns a zero monetary amount.
    Returns: The string '0.00'.
```

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

### Fixed Exchange Conversion

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Demonstrates how to convert Money instances using a fixed exchange rate. This involves setting up a `FixedExchange` with predefined conversion ratios and then using a `Converter` to perform the conversion.

```php
use Money\Converter;
use Money\Currency;
use Money\Currencies\ISOCurrencies;
use Money\Exchange\FixedExchange;

$exchange = new FixedExchange([
    'EUR' => [
        'USD' => '1.25'
    ]
]);

$converter = new Converter(new ISOCurrencies(), $exchange);

$eur100 = Money::EUR(100);
$usd125 = $converter->convert($eur100, new Currency('USD'));
```

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

### Allocate Money by Ratios

Source: https://github.com/moneyphp/money/blob/master/doc/features/allocation.rst

Demonstrates how to divide a monetary amount between two parties based on percentage ratios. The `allocate` method handles the distribution, including rounding and remainder allocation to ensure the total amount is distributed accurately. The order of ratios in the input array determines the order of the resulting allocated amounts.

```php
use Money\Money;

$profit = Money::EUR(5);
list($my_cut, $investors_cut) = $profit->allocate([70, 30]);
// $my_cut is 4 cents, $investors_cut is 1 cent

// The order is important:
list($investors_cut, $my_cut) = $profit->allocate([30, 70]);
// $my_cut is 3 cents, $investors_cut is 2 cents
```

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

### Immutable Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/concept.rst

Demonstrates the immutability of Money objects in MoneyPHP. Operations like subtraction return new instances, preserving the original object's state.

```php
use Money\Money;

$jimPrice = $hannahPrice = Money::EUR(2500);
$coupon = Money::EUR(500);
$jimPrice = $jimPrice->subtract($coupon);
$jimPrice->lessThan($hannahPrice); // true
$jimPrice->equals(Money::EUR(2000)); // true
```

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

### Convert Using CurrencyPair with SwapExchange

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Illustrates how to obtain a `CurrencyPair` using the `SwapExchange` and then use this pair to convert a `Money` amount. This is useful when you have a specific `CurrencyPair` object and want to perform a conversion based on it.

```php
use Money\Currency;
use Money\Exchange\SwapExchange;

$eur = new Currency('EUR');
$usd = new Currency('USD');

// $swap = Implementation of \Swap\SwapInterface
$exchange = new SwapExchange($swap);

$pair = $exchange->quote($eur, $usd);
```

```php
use Money\Money;
use Money\Currency;
use Money\Currencies\ISOCurrencies;
use Money\Exchange\SwapExchange;

// $swap = Implementation of \Swap\SwapInterface
$exchange = new SwapExchange($swap);

$converter = new Converter(new ISOCurrencies(), $exchange);
$eur100 = Money::EUR(100);
$usd125 = $converter->convertAgainstCurrencyPair($eur100, $pair);
```

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

### Allocate Money to N Targets

Source: https://github.com/moneyphp/money/blob/master/doc/features/allocation.rst

Shows how to distribute a monetary amount equally among a specified number of targets using the `allocateTo` method. The method divides the amount as evenly as possible, with any remaining cents distributed among the targets.

```php
$value = Money::EUR(800);           // €8.00

$result = $value->allocateTo(3);    // $result = [€2.67, €2.67, €2.66]
```

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

### CurrencyList Custom Implementation

Source: https://github.com/moneyphp/money/blob/master/doc/features/currencies.rst

Allows developers to create a custom currency repository by providing an array of currency code and minor unit pairs. Throws an exception for invalid input. Supports iteration, checking for currency existence, and retrieving subunits.

```php
use Money\Currencies\CurrencyList;
use Money\Currency;

$currencies = new CurrencyList([
    'MY1' => 2,
]);

foreach ($currencies as $currency) {
    echo $currency->getCode(); // prints MY1
}

$currencies->contains(new Currency('MY1')); // returns boolean whether MY1 is available in this repository (true)
$currencies->contains(new Currency('USD')); // returns boolean whether USD is available in this repository (false)
$currencies->subunitFor(new Currency('MY1')); // returns the subunit for the currency MY1 (2)
```

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

### Exchanger Exchange Integration

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Shows how to integrate the Exchanger library with MoneyPHP. This involves creating an `ExchangerExchange` instance with an Exchanger interface implementation and using it with the `Converter` for currency conversions.

```php
use Money\Money;
use Money\Converter;
use Money\Currencies\ISOCurrencies;
use Money\Exchanger\ExchangerExchange;

// $exchanger = Implementation of \Exchanger\Contract\ExchangeRateProvider
$exchange = new ExchangerExchange($exchanger);

$converter = new Converter(new ISOCurrencies(), $exchange);
$eur100 = Money::EUR(100);
$usd125 = $converter->convert($eur100, new Currency('USD'));
[$usd125, $pair] = $converter->convertAndReturnWithCurrencyPair($eur100, new Currency('USD'));
```

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

### JSON Serialization of Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/concept.rst

Shows how to serialize a Money object into a JSON string using PHP's built-in json_encode function.

```php
use Money\Money;

$money = Money::USD(350);
$json = json_encode($money);
echo $json; // outputs '{"amount":"350","currency":"USD"}'
```

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

### Rounding Money Objects to Unit

Source: https://github.com/moneyphp/money/blob/master/doc/features/operation.rst

Explains how to round a Money object to the nearest unit using the `roundToUnit()` method. This method accepts a precision argument to determine the rounding target.

```php
$value = Money::EUR(813);

    $result = $value->roundToUnit(2);   // Money::EUR(800)
    $result = $value->roundToUnit(1);   // Money::EUR(810)
```

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

### MoneyPHP min() Method

Source: https://github.com/moneyphp/money/blob/master/doc/features/aggregation.rst

The min() method returns the smallest of the given Money objects. It accepts multiple Money objects as arguments.

```php
$first = Money::EUR(100);
$second = Money::EUR(200);
$third = Money::EUR(300);

$min = Money::min($first, $second, $third) // €1.00
```

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

### ISOCurrencies Implementation

Source: https://github.com/moneyphp/money/blob/master/doc/features/currencies.rst

Provides all available ISO4217 currencies using the official ISO 4217 Maintenance Agency as the data source. Supports iterating through currencies, checking for currency existence, and retrieving the subunit for a given currency.

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

$currencies = new ISOCurrencies();
foreach ($currencies as $currency) {
    echo $currency->getCode(); // prints an available currency code within the repository
}

$currencies->contains(new Currency('USD')); // returns boolean whether USD is available in this repository
$currencies->subunitFor(new Currency('USD')); // returns the subunit for the dollar (2)
```

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

### AggregateCurrencies for Multiple Sources

Source: https://github.com/moneyphp/money/blob/master/doc/features/currencies.rst

Collects multiple currency sources into a single repository. Useful for supporting diverse currency data sources. Supports iteration, checking for currency existence across all sources, and retrieving subunits.

```php
use Money\Currency;
use Money\Currencies\AggregateCurrencies;
use Money\Currencies\BitcoinCurrencies;
use Money\Currencies\ISOCurrencies;

$currencies = new AggregateCurrencies([
    new BitcoinCurrencies(),
    new ISOCurrencies()
]);

foreach ($currencies as $currency) {
    echo $currency->getCode(); // prints XBT or any ISO currency code
}

$currencies->contains(new Currency('XBT')); // returns boolean whether XBT is available in this repository (true)
$currencies->contains(new Currency('USD')); // returns boolean whether USD is available in this repository (true)
$currencies->subunitFor(new Currency('XBT')); // returns the subunit for the Bitcoin (8)
```

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

### MoneyPHP sum() Method

Source: https://github.com/moneyphp/money/blob/master/doc/features/aggregation.rst

The sum() method provides the sum of all given Money objects. It accepts multiple Money objects as arguments.

```php
$first = Money::EUR(100);
$second = Money::EUR(-200);
$third = Money::EUR(300);

$sum = Money::sum($first, $second, $third) // €2.00
```

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

### Calculating Ratio Between Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/features/operation.rst

Shows how to calculate the ratio of one Money object in comparison to another using the `ratioOf()` method. This method returns a float representing the ratio.

```php
$three = Money::EUR(300);
    $six = Money::EUR(600);

    $result = $three->ratioOf($six); // 0.5
    $result = $six->ratioOf($three); // 2
```

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

### Money Object Less Than Comparison

Source: https://github.com/moneyphp/money/blob/master/doc/features/comparison.rst

Compares if the first Money object's value is strictly less than the second. Also includes `lessThanOrEqual` for checking less than or equal to.

```php
$value1 = Money::USD(800);
$value2 = Money::USD(700);

$result = $value1->lessThan($value2);   // false

$value1 = Money::USD(800);
$value2 = Money::USD(800);

$result = $value1->lessThanOrEqual($value2);    // true
```

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

### Division with Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/features/operation.rst

Demonstrates how to divide a Money object by a given divisor using the `divide()` method. This is an immutable operation that returns a new Money object representing the quotient.

```php
$value = Money::EUR(800);

    $result = $value->divide(2);    // €4.00
```

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

### Money Object Equality Comparison

Source: https://github.com/moneyphp/money/blob/master/doc/features/comparison.rst

Compares if two Money objects are equal in both value and currency.

```php
$value1 = Money::USD(800);
$value2 = Money::USD(800);
$value3 = Money::EUR(800);

$result = $value1->equals($value2);     // true
$result = $value1->equals($value3);     // false
```

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

### Money Object Value Sign Determination

Source: https://github.com/moneyphp/money/blob/master/doc/features/comparison.rst

Determines the sign of a Money object. Methods include `isZero()`, `isPositive()`, and `isNegative()`.

```php
Money::USD(100)->isZero();          // false
Money::USD(0)->isZero();            // true
Money::USD(-100)->isZero();         // false

Money::USD(100)->isPositive();      // true
Money::USD(0)->isPositive();        // false
Money::USD(-100)->isPositive();     // false

Money::USD(100)->isNegative();      // false
Money::USD(0)->isNegative();        // false
Money::USD(-100)->isNegative();     // true
```

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

### MoneyPHP avg() Method

Source: https://github.com/moneyphp/money/blob/master/doc/features/aggregation.rst

The avg() method returns the average value of the given Money objects as a Money object. It accepts multiple Money objects as arguments.

```php
$first = Money::EUR(100);
$second = Money::EUR(-200);
$third = Money::EUR(300);

$avg = Money::avg($first, $second, $third) // €2.00
```

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

### Reversed Currencies Exchange

Source: https://github.com/moneyphp/money/blob/master/doc/features/currency-conversion.rst

Shows how to use `ReversedCurrenciesExchange` to automatically handle reverse currency pair lookups. If a direct conversion rate isn't found, it attempts to use the inverse of the known rate. This is useful when you only define currency pairs in one direction.

```php
use Money\Converter;
use Money\Currency;
use Money\Currencies\ISOCurrencies;
use Money\Exchange\FixedExchange;
use Money\Exchange\ReversedCurrenciesExchange;

$exchange = new ReversedCurrenciesExchange(new FixedExchange([
    'EUR' => [
        'USD' => '1.25'
    ]
]));

$converter = new Converter(new ISOCurrencies(), $exchange);

$usd125 = Money::USD(125);
$eur100 = $converter->convert($usd125, new Currency('EUR'));
```

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

### Multiplication with Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/features/operation.rst

Illustrates how to multiply a Money object by a given factor using the `multiply()` method. The operation is immutable and returns a new Money object representing the product.

```php
$value = Money::EUR(800);

    $result = $value->multiply(2);  // €16.00
```

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

### Addition with Money Objects

Source: https://github.com/moneyphp/money/blob/master/doc/features/operation.rst

Demonstrates how to add two or more Money objects using the `add()` method. The operation is immutable, returning a new Money object with the sum.

```php
$value1 = Money::EUR(800);
    $value2 = Money::EUR(500);

    $result = $value1->add($value2); // €13.00
```

```php
$value1 = Money::EUR(800);
    $value2 = Money::EUR(500);
    $value3 = Money::EUR(600);

    $result = $value1->add($value2, $value3); // €19.00
```

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

### Money Object Same Currency Comparison

Source: https://github.com/moneyphp/money/blob/master/doc/features/comparison.rst

Compares if two or more Money objects share the same currency. Supports variadic arguments to check multiple objects against a target.

```php
$value1 = Money::USD(800);
$value2 = Money::USD(100);
$value3 = Money::EUR(800);

$result = $value1->isSameCurrency($value2);    // true
$result = $value1->isSameCurrency($value3);    // false

$target = Money::USD(800);
$containsEuros = [
    Money::USD(500),
    Money::EUR(800)
];
$allDollars = [
    Money::USD(500),
    Money::USD(600),
];
$result = $target->isSameCurrency(...$containsEuros); // false
$result = $target->isSameCurrency(...$allDollars);    // true
```

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

### Money Object Greater Than Comparison

Source: https://github.com/moneyphp/money/blob/master/doc/features/comparison.rst

Compares if the first Money object's value is strictly greater than the second. Also includes `greaterThanOrEqual` for checking greater than or equal to.

```php
$value1 = Money::USD(800);
$value2 = Money::USD(700);

$result = $value1->greaterThan($value2);    // true

$value1 = Money::USD(800);
$value2 = Money::USD(800);

$result = $value1->greaterThanOrEqual($value2);     // true
```

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

### BitcoinCurrencies Implementation

Source: https://github.com/moneyphp/money/blob/master/doc/features/currencies.rst

Provides a single currency: Bitcoin (XBT) with a subunit of 8. Allows checking for the existence of Bitcoin and other currencies, and retrieving its subunit.

```php
use Money\Currencies\BitcoinCurrencies;
use Money\Currency;

$currencies = new BitcoinCurrencies();
foreach ($currencies as $currency) {
    echo $currency->getCode(); // prints XBT
}

$currencies->contains(new Currency('XBT')); // returns boolean whether XBT is available in this repository (true)
$currencies->contains(new Currency('USD')); // returns boolean whether USD is available in this repository (false)
$currencies->subunitFor(new Currency('XBT')); // returns the subunit for the Bitcoin (8)
```