0.13.0

💥 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