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

0.12.3

⚠️ 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())

0.12.2

✨ 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

0.12.1

📌 Compatibility

• Compatibility with brick/math version 0.16

0.12.0

💥 Breaking changes

• Calling the following methods with floating-point values is no longer supported, explicitly cast floats to string (string) $float to get the same behaviour as before (brick/math#105):
  • Money::of(), ofMinor(), plus(), minus(), multipliedBy(), dividedBy(), quotient(), quotientAndRemainder(), convertedTo()
  • RationalMoney::of(), plus(), minus(), multipliedBy(), dividedBy()
  • AbstractMoney::compareTo(), isEqualTo(), isLessThan(), isLessThanOrEqualTo(), isGreaterThan(), isGreaterThanOrEqualTo()
  • ConfigurableProvider::setExchangeRate()
• Calling Currency::of() with a numeric code is no longer supported, use Currency::ofNumericCode() instead (#104)
• Calling the following methods with a numeric currency code is no longer supported, use a Currency instance from Currency::ofNumericCode() instead (#104):
  • Money::of()
  • Money::ofMinor()
  • Money::zero()
  • Money::convertedTo()
  • RationalMoney::of()
  • CurrencyConverter::convert()
  • CurrencyConverter::convertToRational()
  • IsoCurrencyProvider::getCurrency()
• RationalMoney is now always simplified to lowest terms: USD 25/100 is automatically simplified to USD 1/4
• Currency::$numericCode is now nullable
• PdoProviderConfiguration now has a private constructor, use a factory method instead
• Internal method Money::create() is now protected

Class name case changes:

• ISOCurrencyProvider has been renamed to IsoCurrencyProvider
• PDOProvider has been renamed to PdoProvider
• PDOProviderConfiguration has been renamed to PdoProviderConfiguration

Deprecated methods removed:

• Currency::is() has been removed, use Currency::isEqualTo() instead
• MoneyBag::getAmount() has been removed, use MoneyBag::getMoney()->getAmount() instead
• Money::formatTo() has been removed, use Money::formatToLocale() instead
• Money::formatWith() has been removed, use MoneyNumberFormatter::format() instead

⚠️ Deprecations

• Method RationalMoney::simplified() is deprecated, as it is now a no-op
• Method Money::getUnscaledAmount() is deprecated, use getAmount()->getUnscaledValue() instead
• Method Money::total() is deprecated, use sum() instead
• Method AbstractMoney::to() is deprecated, use toContext() instead
• Passing null to the $context parameter of the following methods is deprecated, use named arguments if you need to skip $context:
  • CurrencyConverter::convert()
  • Money::of()
  • Money::ofMinor()
  • Money::zero()
• Passing null to the $context parameter of Money::convertedTo() is deprecated, use an explicit Context instance; the default will change to DefaultContext in a future version
• Instantiating a MoneyBag with new is deprecated, use MoneyBag::zero() or MoneyBag::fromMonies() instead
• Method MoneyBag::add() is deprecated, use plus() instead, which returns a new instance
• Method MoneyBag::subtract() is deprecated, use minus() instead, which returns a new instance

📌 Compatibility

• brick/money now requires brick/math:~0.15

👌 Improvements

• All InvalidArgumentException thrown now implement MoneyException
• More exceptions have been documented
• CashContext::applyTo() now performs step ⟷ scale validation

✨ New features

• New method: AbstractMoney::toRational()
• New method: Money::sum() (replaces total())
• New method: RationalMoney::convertedTo()
• New method: RationalMoney::abs()
• New method: RationalMoney::negated()
• New MoneyBag immutable API:
  • MoneyBag::zero()
  • MoneyBag::fromMonies()
  • MoneyBag::plus()
  • MoneyBag::minus()
• New exception: ContextException thrown when a context cannot be applied
• New PDOProviderConfiguration factory methods:
  • forCurrencyPair()
  • forFixedSourceCurrency()
  • forFixedTargetCurrency()
• MoneyBag now implements JsonSerializable

0.11.2

⚠️ Deprecations

• Money::create() is now marked as @internal, and will be made protected in version 0.12

0.11.1

⚠️ Deprecations

• Added explicit trigger_deprecation() calls to methods that were already marked as @deprecated, so deprecation notices are now emitted at runtime

📌 Compatibility

• Restricted compatibility to brick/math:~0.14.4

👌 Improvements

• Fixed calls to deprecated brick/math and brick/money APIs

0.11.0

💥 Breaking changes

• Minimum PHP version is now 8.2
• The following classes are now final:
  • CurrencyConversionException
  • MoneyMismatchException
  • UnknownCurrencyException
• CustomContext now validates the step and will throw an exception if an invalid step is given
• Interface MoneyContainer has been removed (replaced with Monetary)
• Method AbstractMoney::getAmounts() has been removed (replaced with getMonies())
• Method MoneyBag::getAmounts() has been removed (replaced with getMonies())
• CurrencyConverter::convert() and convertToRational() now accept a Monetary instance (which still includes Money, RationalMoney and MoneyBag)
• MoneyBag::add() and subtract() now accept a Monetary instance (which still includes Money, RationalMoney and MoneyBag)

⚠️ Deprecations

• Calling Currency::of() with a numeric code is deprecated, use Currency::ofNumericCode() instead
• Calling ISOCurrencyProvider::getCurrency() with a numeric code is deprecated, use getCurrencyByNumericCode() instead
• Calling CurrencyConverter::convert() or convertToRational() with a numeric currency code is deprecated, use a Currency instance instead
• Calling Money::of(), ofMinor(), zero() or convertedTo() with a numeric currency code is deprecated, use a Currency instance instead
• Calling RationalMoney::of() with a numeric currency code is deprecated, use a Currency instance instead
• MoneyBag::getAmount() is deprecated, use getMoney() instead
• Money::formatTo() is deprecated, use Money::formatToLocale() instead
• Money::formatWith() is deprecated, use MoneyNumberFormatter::format() instead
• Currency::is() is deprecated, use Currency::isEqualTo() instead

Important

The convenience of passing a currency by ISO numeric code in addition to alphabetic code has been deprecated, leaving only alphabetic-code lookup in generic APIs. For example, Money::of() will accept Currency|string in the future, instead of Currency|string|int today.
This makes explicit the separation between retrieval by alphabetic code, which has strong backwards compatibility guarantees, and retrieval by numeric code, which may change in minor versions due to ISO reassignments.
This will require users to explicitly obtain a currency through Currency::ofNumericCode(), which is documented as not being covered by the same BC guarantees.

✨ New features

• Support for historical currencies in Money::of(), Currency::of(), etc. (#104 by @survik1)
• New enum: CurrencyType
• New methods:
  • Currency::getCurrencyType() returns the type of the currency
  • Currency::ofNumericCode() returns a currency by its numeric ISO 4217 code
  • Currency::isEqualTo() compares two currencies for equality (replaces is())
  • ISOCurrencyProvider::getCurrencyByNumericCode() returns a currency by its numeric code
  • ISOCurrencyProvider::getHistoricalCurrenciesForCountry() returns historical currencies for a country
  • MoneyBag::getMoney() returns the contained amount in a given currency (replaces getAmount())
  • MoneyBag::getMonies() returns the contained monies (replaces getAmounts())
  • Money::formatToLocale() formats the amount to a locale (replaces formatTo()) (#105 by @mklepaczewski)
  • RationalMoney::zero() returns a zero RationalMoney in a given currency
• New interfaces:
  • Monetary (replaces MoneyContainer)
  • MoneyFormatter formats a given Money object (#105 by @mklepaczewski)
• New classes:
  • MoneyLocaleFormatter formats a given Money object to a locale (#105 by @mklepaczewski)
  • MoneyNumberFormatter formats a given Money object using a NumberFormatter instance (#105 by @mklepaczewski)

0.10.3

👌 Improvements

• Compatibility with brick/math version 0.14 (#101 by @markwalet)

0.10.2

✨ New features

• Add possibility to pass previous exception in CurrencyConversionException (#99 by @arokettu)