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
 {

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
     {
@@ -641,6 +651,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();
     }
 
@@ -745,6 +759,10 @@ public function convertedTo(
         int $roundingMode = RoundingMode::UNNECESSARY,
     ) : Money {
         if (! $currency instanceof Currency) {
+            /**
+             * FIXME: dunno what to do here, Currency::of() uses ISOCurrencyProvider which is heavily "impure".
+             * @psalm-suppress ImpureMethodCall
+             */
             $currency = Currency::of($currency);
         }
 
@@ -769,6 +787,7 @@ public function convertedTo(
      */
     public function formatWith(\NumberFormatter $formatter) : string
     {
+        /** @psalm-suppress ImpureMethodCall */
         return $formatter->formatCurrency(
             $this->amount->toFloat(),
             $this->currency->getCurrencyCode()
@@ -785,6 +804,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
 {