Money Laravel Package

💥 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](https://github.com/internal)
• Context methods are now [@internal](https://github.com/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

💥 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

⚠️ Deprecations

• Money::create() is now marked as [@internal](https://github.com/internal), and will be made protected in version 0.12

⚠️ Deprecations

• Added explicit trigger_deprecation() calls to methods that were already marked as [@deprecated](https://github.com/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

💥 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)

👌 Improvements

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

✨ New features

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

👌 Improvements

• Compatibility with brick/math version 0.13 (#96 by @ekvedaras)

💥 ISO currency changes

• ZWG (Zimbabwe Gold) has been added
• ZWL (Zimbabwean Dollar) has been removed
• SLL (Sierra Leonean Leone) has been removed
• The currency of Zimbabwe (ZW) has been changed to ZWG (Zimbabwe Gold)
• The SLL currency has been removed from Sierra Leone (SL), which only has SLE now

💥 Breaking changes

• Minimum PHP version is now 8.1
• PDOProviderConfiguration no longer has getters, its properties are public readonly
• RoundingMode from brick/math is now an enum, so:
  • all methods accepting an int rounding mode now accept a RoundingMode instance instead
  • this should be transparent to your application, as you'll be using the same constants such as RoundingMode::UP

👌 Improvement

Currency now implements JsonSerializable (#79).

Thanks @joelvh!

💥 Breaking changes

• Minimum PHP version is now 8.0
• Due to Croatia's adoption of the Euro on January 1st, 2023:
  • the HRK currency (Kuna) has been removed from the ISO currency provider
  • the HR country (Croatia) is now mapped to EUR (Euro)
• PDOProviderConfiguration now has a proper constructor, and its properties are no longer public
• PDOProviderConfiguration now throws exceptions in the constructor when configuration is invalid
• All documented union types are now strongly typed:
  • If you have a custom ExchangeRateProvider implementation, you will need to update your getExchangeRate() method signature
  • If you were passing Stringable objects to of() or any of the methods internally calling of(), and have strict_types enabled, you will need to explicitly cast these objects to string first

👌 Improvements

• Compatibility with brick/math version 0.11

💥 Breaking changes

• JSON extension is now required for PHP 7.4 (always available with PHP >= 8.0)
• AbstractMoney is now officially sealed, extending it yourself is not supported

✨ New features

• Money and RationalMoney now implement JsonSerializable

💥 Breaking changes

• Minimum PHP version is now 7.4
• AbstractMoney::getAmount() now has a return type
• CurrencyConverter's constructor does not accept a default $context anymore
• CurrencyConverter::convert() now requires the $context previously accepted by the constructor as third parameter
• Money::allocateWithRemainder() now refuses to allocate a portion of the amount that cannot be spread over all ratios, and instead adds that amount to the remainder (#55)
• Money::splitWithRemainder() now behaves like allocateWithRemainder()

✨ New ISO currencies

• SLE (Leone) in Sierra Leone (SL)

👌 Improvements

• Compatibility with brick/math version 0.10

✨ Add support for VED (Venezuelan bolívar) currency.

✨ New methods

• Money::splitWithRemainder()
• Money::allocateWithRemainder()

These methods perform like their split() and allocate() counterparts, but append the remainder at the end of the returned array instead of spreading it over the first monies.

Thanks @NCatalani!

👌 Improvement

BaseCurrencyProvider now always returns a BigNumber for convenience (#37). This is useful if you're using BaseCurrencyProvider on its own, not just in CurrencyConverter.

Thanks @rdarcy1!

👌 Improvements

• compatibility with brick/math version 0.9

⚠️ Caution

When using brick/math version 0.9, the Money factory methods such as of() and ofMinor() now accept decimal numbers in the form .123 and 123., and do not throw an exception anymore in this case.

🐛 Bug fix

MoneyBag::getAmount(), add() and subtract() would throw an exception when using a custom currency (#25).

✨ New method

AbstractMoney::isAmountAndCurrencyEqualTo() compares a money to another. (#17)

This method is different from isEqualTo() in 2 aspects:

• it only accepts another money, not a raw number;
• it returns false if the money is in another currency, instead of throwing an exception.

🛠 Improvements

• MoneyBag::getAmount() now accepts an ISO numeric currency code as well

✨ New methods

• CurrencyConverter::convertToRational() converts to a RationalMoney (#22)

Performance improvement when calling Money::formatTo() many times for the same locale.

Added support for brick/math version 0.8.

Breaking Changes

• Deprecated method BigRational::toMoney() has been removed, use BigRational::to() instead;
• BigRational::__toString() now always outputs the amount in non-simplified rational form.

New methods

• BigRational::simplified() returns a copy of the money with the amount simplified.

ISO currency list update.

ISO currency list update.

Money::formatTo() can now format the amount as a whole number:

formatTo(string $locale, bool $allowWholeNumber = false) : string

By default, formatTo() always outputs all the fraction digits:

Money::of('23.5', 'USD')->formatTo('en_US'); // $23.50
Money::of(23, 'USD')->formatTo('en_US'); // $23.00

But can now be allowed to return the whole number by passing true as a second argument:

Money::of('23.5', 'USD')->formatTo('en_US', true); // $23.50
Money::of(23, 'USD')->formatTo('en_US', true); // $23

Note that this version now requires brick/math version 0.7.3. This is not a BC break. If you've locked your composer.json to an earlier version, you will just not be able to install brick/money version 0.3.2.

ISO currency list update.

New methods:

• CurrencyConversionException::getSourceCurrencyCode()
• CurrencyConversionException::getTargetCurrencyCode()

This allows to programmatically get the failing currency pair when an exchange rate is not available.

Breaking change:

• CurrencyConversionException constructor signature changed

Although this is technically a breaking change and requires a version bump, your code is unlikely to be affected, unless you're creating CurrencyConversionException instances manually (you shouldn't).

ISO currency list update.

Backports from 0.2.x:

• New method: CustomContext::getScale()
• Money::formatTo() now always respects the scale of the Money
• Bug fix: Money::allocate() incorrectly allocated negative monies

Bug fix: Money::allocate() incorrectly allocated negative monies.