Objekt Money

Money je finálny readonly hodnotový objekt: suma v najmenších jednotkách (minor) plus Currency. Každá operácia vracia novú inštanciu. Money::of() zámerne neexistuje — jednotka je vždy v názve factory metódy.

Vytvorenie sumy

use RoundlyConsulting\Money\Money;

$price = Money::ofMajor('19.99', 'EUR');          // minor "1999" — never a float
$fee   = Money::ofMinor(250, 'EUR');              // 2.50 EUR
$none  = Money::zero('USD');                      // 0.00 USD

Money::ofMajor('10.005', 'EUR');                          // throws RoundingNecessary
Money::ofMajor('10.005', 'EUR', RoundingMode::HalfEven);  // 10.00 EUR
Money::ofScaled(9990, 3, 'EUR');                          // Apple milli-units → 9.99 EUR
Money::ofScaled(9990000, 6, 'USD');                       // Google micros → 9.99 USD
Money::fromArray(['minor' => '1050', 'currency' => 'EUR']); // 10.50 EUR
Money::parse('1 234,50 EUR', locale: 'sk');                // 1234.50 EUR

• ofMinor($minor, $currency) — int alebo celočíselný reťazec najmenších jednotiek; float je TypeError.
• ofMajor($amount, $currency, ?$rounding) — celé číslo alebo desatinný reťazec; príliš presný vstup vyhodí RoundingNecessary, pokiaľ nezadáte režim zaokrúhlenia.
• ofScaled($value, $scale, $currency, ?$rounding) — celé číslo v inej škále (0..36): tisíciny od Apple majú škálu 3, milióntiny od Google škálu 6.
• zero($currency) — nulová suma.
• parse($input, ?$currency, ?$locale) — lokalizovaný vstup cez zaregistrovaný parser (pozri Formátovanie a parsovanie).
• fromArray($data) — tvar z toArray(); ak sú zadané minor aj decimal, musia sa zhodovať.

Mena zadaná reťazcom sa vyhľadá v registri (orezaná a prevedená na veľké písmená), takže funguje aj 'eur'; neznámy kód vyhodí UnknownCurrency.

Čítanie sumy

$total = Money::ofMajor('67.47', 'EUR');

$total->minor();           // "6747"   — a string
$total->minorInt();        // 6747     — throws AmountOverflow beyond int64
$total->fitsInt();         // true
$total->digits();          // 4
$total->currency()->code;  // "EUR"
$total->toDecimal();       // "67.47"  — locale-free
$total->toScaled(3);       // "67470"
(string) $total;           // "67.47 EUR"
json_encode($total);       // {"minor":"6747","decimal":"67.47","currency":"EUR"}

toDecimal(trimTrailingZeros: true) odstráni koncové nuly za desatinnou čiarkou (aj osamotenú bodku). toScaled($scale) vráti sumu ako celočíselný reťazec v inej škále a pri zmenšovaní zaokrúhli raz.

Serializácia

toArray() aj JSON prenášajú minor zámerne ako reťazec — JavaScript poškodí JSON čísla nad 2⁵³. __toString() je deterministický a nezávislý od lokality, ideálny do logov a textov výnimiek. Funguje aj PHP serialize(), takže Money prejde frontami aj s úplnou definíciou meny.