Allow using Money, Currency and Context in Psalm's immutable contexts

src/AbstractMoney.php

@@ -18,6 +18,8 @@
  *
  * Please consider this class sealed: extending this class yourself is not supported, and breaking changes (such as
  * adding new abstract methods) can happen at any time, even in a minor version.
+ *
+ * @psalm-immutable
  */
 abstract class AbstractMoney implements MoneyContainer, Stringable, JsonSerializable
 {

src/Context.php

@@ -11,6 +11,8 @@
 
 /**
  * Adjusts a rational number to a decimal amount.
+ *
+ * @psalm-immutable
  */
 interface Context
 {

src/Context/AutoContext.php

@@ -13,6 +13,8 @@
 
 /**
  * Automatically adjusts the scale of a number to the strict minimum.
+ *
+ * @psalm-immutable
  */
 final class AutoContext implements Context
 {

src/Context/CashContext.php

@@ -12,6 +12,8 @@
 
 /**
  * Adjusts a number to the default scale for the currency, respecting a cash rounding.
+ *
+ * @psalm-immutable
  */
 final class CashContext implements Context
 {

src/Context/CustomContext.php

@@ -12,6 +12,8 @@
 
 /**
  * Adjusts a number to a custom scale, and optionally step.
+ *
+ * @psalm-immutable
  */
 final class CustomContext implements Context
 {

src/Context/DefaultContext.php

@@ -12,6 +12,8 @@
 
 /**
  * Adjusts a number to the default scale for the currency.
+ *
+ * @psalm-immutable
  */
 final class DefaultContext implements Context
 {

src/Currency.php

@@ -9,6 +9,8 @@
 
 /**
  * A currency. This class is immutable.
+ *
+ * @psalm-immutable
  */
 final class Currency implements Stringable
 {
@@ -76,9 +78,15 @@ public function __construct(string $currencyCode, int $numericCode, string $name
      * @param string|int $currencyCode The 3-letter or numeric ISO 4217 currency code.
      *
      * @throws UnknownCurrencyException If an unknown currency code is given.
+     *
+     * @psalm-pure
      */
     public static function of(string|int $currencyCode) : Currency
     {
+        /**
+         * @psalm-suppress ImpureMethodCall
+         * @see https://github.com/brick/money/pull/75
+         */
         return ISOCurrencyProvider::getInstance()->getCurrency($currencyCode);
     }
 
@@ -90,9 +98,15 @@ public static function of(string|int $currencyCode) : Currency
      * @return Currency
      *
      * @throws UnknownCurrencyException If the country code is unknown, or there is no single currency for the country.
+     *
+     * @psalm-pure
      */
     public static function ofCountry(string $countryCode) : Currency
     {
+        /**
+         * @psalm-suppress ImpureMethodCall
+         * @see https://github.com/brick/money/pull/75
+         */
         return ISOCurrencyProvider::getInstance()->getCurrencyForCountry($countryCode);
     }
 

src/Money.php

@@ -30,6 +30,8 @@
  * - CashContext is similar to DefaultContext, but supports a cash rounding step.
  * - CustomContext handles monies with a custom scale, and optionally step.
  * - AutoContext automatically adjusts the scale of the money to the minimum required.
+ *
+ * @psalm-immutable
  */
 final class Money extends AbstractMoney
 {
@@ -71,6 +73,8 @@ private function __construct(BigDecimal $amount, Currency $currency, Context $co
      * @return Money
      *
      * @throws MoneyMismatchException If all the monies are not in the same currency.
+     *
+     * @psalm-pure
      */
     public static function min(Money $money, Money ...$monies) : Money
     {
@@ -96,6 +100,8 @@ public static function min(Money $money, Money ...$monies) : Money
      * @return Money
      *
      * @throws MoneyMismatchException If all the monies are not in the same currency.
+     *
+     * @psalm-pure
      */
     public static function max(Money $money, Money ...$monies) : Money
     {
@@ -121,6 +127,8 @@ public static function max(Money $money, Money ...$monies) : Money
      * @return Money
      *
      * @throws MoneyMismatchException If all the monies are not in the same currency and context.
+     *
+     * @psalm-pure
      */
     public static function total(Money $money, Money ...$monies) : Money
     {
@@ -146,6 +154,8 @@ public static function total(Money $money, Money ...$monies) : Money
      * @return Money
      *
      * @throws RoundingNecessaryException If RoundingMode::UNNECESSARY is used but rounding is necessary.
+     *
+     * @psalm-pure
      */
     public static function create(BigNumber $amount, Currency $currency, Context $context, int $roundingMode = RoundingMode::UNNECESSARY) : Money
     {
@@ -177,6 +187,8 @@ public static function create(BigNumber $amount, Currency $currency, Context $co
      * @throws UnknownCurrencyException   If the currency is an unknown currency code.
      * @throws RoundingNecessaryException If the rounding mode is RoundingMode::UNNECESSARY, and rounding is necessary
      *                                    to represent the amount at the requested scale.
+     *
+     * @psalm-pure
      */
     public static function of(
         BigNumber|int|float|string $amount,
@@ -217,6 +229,8 @@ public static function of(
      * @throws UnknownCurrencyException   If the currency is an unknown currency code.
      * @throws RoundingNecessaryException If the rounding mode is RoundingMode::UNNECESSARY, and rounding is necessary
      *                                    to represent the amount at the requested scale.
+     *
+     * @psalm-pure
      */
     public static function ofMinor(
         BigNumber|int|float|string $minorAmount,
@@ -247,6 +261,8 @@ public static function ofMinor(
      * @param Context|null        $context  An optional context.
      *
      * @return Money
+     *
+     * @psalm-pure
      */
     public static function zero(Currency|string|int $currency, ?Context $context = null) : Money
     {
@@ -641,6 +657,10 @@ private function gcdOfMultipleInt(array $values): int
     {
         $values = array_map(fn (int $value) => BigInteger::of($value), $values);
 
+        /**
+         * @psalm-suppress ImpureMethodCall
+         * FIXME: remove the suppression after BigInteger::gcdMultiple() is marked @psalm-pure
+         */
         return BigInteger::gcdMultiple(...$values)->toInt();
     }
 
@@ -769,6 +789,7 @@ public function convertedTo(
      */
     public function formatWith(\NumberFormatter $formatter) : string
     {
+        /** @psalm-suppress ImpureMethodCall */
         return $formatter->formatCurrency(
             $this->amount->toFloat(),
             $this->currency->getCurrencyCode()
@@ -785,6 +806,9 @@ public function formatWith(\NumberFormatter $formatter) : string
      * @param bool   $allowWholeNumber Whether to allow formatting as a whole number if the amount has no fraction.
      *
      * @return string
+     *
+     * @psalm-suppress ImpureMethodCall - \NumberFormatter is impure, but we use it here in a side effect free way
+     * @psalm-suppress ImpureStaticVariable - static variables are used for optimization reasons
      */
     public function formatTo(string $locale, bool $allowWholeNumber = false) : string
     {

src/RationalMoney.php

@@ -15,6 +15,8 @@
  *
  * This is used to represent intermediate calculation results, and may not be exactly convertible to a decimal amount
  * with a finite number of digits. The final conversion to a Money may require rounding.
+ *
+ * @psalm-immutable
  */
 final class RationalMoney extends AbstractMoney
 {
@@ -41,6 +43,8 @@ public function __construct(BigRational $amount, Currency $currency)
      * @param Currency|string|int        $currency The Currency instance, ISO currency code or ISO numeric currency code.
      *
      * @return RationalMoney
+     *
+     * @psalm-pure
      */
     public static function of(BigNumber|int|float|string $amount, Currency|string|int $currency) : RationalMoney
     {