🐛 Bug fix

• Money::formatToLocale() and MoneyLocaleFormatter would, for some locales, format with root locale data, and break every intl formatter created afterwards for that locale in the same process (#135 by @tomsommer)

📌 Compatibility

• Compatibility with brick/math version 1.0

💥 Breaking changes

• The constructors of these exception classes are now @internal:
  • ExchangeRateProviderException
  • MoneyFormatException
• MoneyNumberFormatter has been removed; call NumberFormatter::formatCurrency() directly instead
• Money::formatToLocale() and MoneyLocaleFormatter:
  • now format through ICU's modern number skeleton pipeline, and minor formatting differences may appear in some locales
  • now require the intl extension to be linked against ICU 62.1 or later, and throw a MoneyFormatException on older ICU (this is independent of the PHP version)
  • now accept a CurrencyDisplay parameter in the second position
  • now throw a MoneyFormatException if the amount cannot be accurately represented as a float, rather than formatting it with wrong digits
  • now throw a MoneyFormatException if the intl extension has no data for the locale's language (e.g. xx_YY), rather than silently formatting in the process default locale
• The $allowWholeNumber parameter of Money::formatToLocale() and MoneyLocaleFormatter has been renamed to $hideFractionIfWhole

✨ New features

• Money::formatToLocale() and MoneyLocaleFormatter now accept a CurrencyDisplay parameter controlling how the currency is displayed: Symbol (default), NarrowSymbol, Code, Name, or None (amount only)
• MoneyLocaleFormatter now properly displays custom currencies whose code is not three letters (e.g. USDT, GOLD)

📌 Compatibility

• Compatibility with brick/math version 0.20

📌 Compatibility

• Compatibility with brick/math version 0.19

💥 Breaking changes

• deprecated class ProviderChain has been removed; use ChainProvider instead
• deprecated method MoneyBag::fromMonies() has been removed; use of() instead

📌 Compatibility

• Compatibility with brick/math version 0.18 (#129 by @delolmo)

💥 Breaking changes

• MoneyBag can no longer be instantiated with new: its constructor is now private; use MoneyBag::zero() to create an empty instance
• Money::convertedTo() now defaults to DefaultContext instead of $this's context
• The following methods no longer accept null for the $context parameter:
  • CurrencyConverter::convert()
  • Money::of()
  • Money::ofMinor()
  • Money::zero()
  • Money::convertedTo()
• Money::allocate() signature has changed: replace allocate(1, 2, 3) with allocate([1, 2, 3], AllocationMode::FloorToFirst) to keep the same behaviour as before
• Money::allocateWithRemainder() has been removed: replace allocateWithRemainder(1, 2, 3) with allocate([1, 2, 3], AllocationMode::BlockSeparate) to keep the same behaviour as before
• Money::split() signature has changed: replace split(3) with split(3, SplitMode::ToFirst) to keep the same behaviour as before
• Money::splitWithRemainder() has been removed: replace splitWithRemainder(3) with split(3, SplitMode::Separate) to keep the same behaviour as before
• The following methods now throw an exception when used on a Money with AutoContext:
  • quotient()
  • remainder()
  • quotientAndRemainder()
  • allocate()
  • split()
• MoneyBag no longer retains zero-balance currencies after plus()/minus() operations
• ExchangeRateProvider::getExchangeRate() signature has changed: it now accepts Currency instances, and returns BigNumber|null
• CurrencyConversionException has been renamed to ExchangeRateException, with ExchangeRateProviderException and ExchangeRateNotFoundException subclasses
• PdoProvider::setParameters() has been removed, use dimension bindings instead
• PdoProvider constructor is now private, use PdoProvider::builder()->...->build() to create an instance
• PdoProviderConfiguration has been removed, use PdoProvider::builder() instead
• CurrencyConverter::convert() signature has changed: parameter $dimensions now comes before $context
• CachedProvider::invalidate() has been removed, pass a PSR-16 cache implementation to the constructor if you need to invalidate the cache
• MoneyComparator constructor now requires a ComparisonMode instance, explicitly pass an instance of PairwiseMode to keep the same behaviour as before
• ConfigurableProvider is now immutable: setExchangeRate() has been removed, use ConfigurableProvider::builder()->addExchangeRate()->build() instead
• The following methods now throw an exception when the exchange rate is negative or zero:
  • Money::convertedTo()
  • RationalMoney::convertedTo()
  • CurrencyConverter::convert()
  • CurrencyConverter::convertToRational()
• The following methods now throw when performing same-currency operations with a rate different from 1:
  • Money::convertedTo()
  • RationalMoney::convertedTo()
• Constructors and factory methods of library-internal exceptions are now @internal
• Context methods are now @internal: userland code should only rely on constructors
• Interfaces Context, Monetary, and MoneyException are now sealed: userland implementations are no longer supported
• Built-in ExchangeRateProvider implementations now consistently return 1 for same-currency pairs

Deprecated methods removed:

• AbstractMoney::to() has been removed, use toContext() instead
• AbstractMoney::isAmountAndCurrencyEqualTo() has been removed, use isSameValueAs() instead
• Money::total() has been removed, use sum() instead
• Money::getUnscaledAmount() has been removed, use getAmount()->getUnscaledValue() instead
• RationalMoney::simplified() has been removed, RationalMoney is always in its simplest form now
• MoneyBag::add() has been removed, use plus() instead, which returns a new instance
• MoneyBag::subtract() has been removed, use minus() instead, which returns a new instance

The following breaking changes only affect you if you're using named arguments:

• Currency::ofNumericCode() now uses $numericCode as the parameter name
• IsoCurrencyProvider::getCurrencyByNumericCode() now uses $numericCode as the parameter name
• MoneyBag::plus() and minus() now use $that as the parameter name

⚠️ Deprecations

• Method MoneyBag::fromMonies() is deprecated, use of() instead
• Class ProviderChain is deprecated, use ChainProvider instead

✨ New features

• Support for custom dimensions (date, rate type, ...) in ExchangeRateProvider, CurrencyConverter and MoneyComparator
• Support for Money, RationalMoney, and MoneyBag in MoneyComparator
• Support for multiple comparison modes in MoneyComparator
• New Money::allocate() API with five algorithms, exposed through the new AllocationMode enum:
  • FloorToFirst (this is the implementation allocate() used previously)
  • FloorToLargestRatio
  • FloorToLargestRemainder
  • FloorSeparate
  • BlockSeparate (this is the implementation allocateWithRemainder() used previously)
• New Money::split() API with two algorithms, exposed through the new SplitMode enum:
  • ToFirst (this is the implementation split() used previously)
  • Separate (this is the implementation splitWithRemainder() used previously)
• MoneyMismatchException now has explicit CurrencyMismatchException and ContextMismatchException subclasses
• New exception: MoneyFormatException, thrown by MoneyFormatter::format()
• New methods in MoneyBag: isZero(), multipliedBy(), dividedBy(), negated(), isEqualTo(), of() (replaces fromMonies())
• New methods in RationalMoney: min(), max(), sum()
• Support for custom PSR-16 cache implementations in CachedProvider
• New exchange rate provider: ChainProvider (replaces ProviderChain)
• Support for numeric currency codes in PdoProvider

⚠️ Deprecations

• Method AbstractMoney::isAmountAndCurrencyEqualTo() is deprecated, use isSameValueAs() instead

🔄 Reverted deprecations

• The deprecation notice when calling AbstractMoney::isEqualTo() with a money in a different currency (introduced in 0.12.1) has been removed; this method will continue to throw a MoneyMismatchException

✨ New features

• New method: AbstractMoney::isSameValueAs() (replaces isAmountAndCurrencyEqualTo())

✨ New features

• Money::allocate() & allocateWithRemainder() now accept BigNumber|int|string and support decimal & rational ratios
• New method: Money::remainder()
• Methods abs() and negated() are now available on AbstractMoney

📌 Compatibility

• Compatibility with brick/math version 0.17

📌 Compatibility

• Compatibility with brick/math version 0.16