Annotate immutability of Money and mutation-free of Currency (#17)

* Refactor Currency to be mostly mutation-free

* Annotate Money as immutable

* Update CHANGELOG

* Remove pointless casting

* Run tests paralel

Author: Slava

.github/workflows/workflow.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
 
     strategy:
-      max-parallel: 1
+      fail-fast: false
       matrix:
         php-version: ['7.3', '7.4', '8.0']
 

CHANGELOG.md

@@ -16,6 +16,13 @@ Security - in case of vulnerabilities.
 
 ## [Unreleased]
 
+## 1.2.0 (2021-10-08)
+
+### Changed
+
++ Annotate the immutability of `Money`.
++ Annotate the mutation-free behavior of all methods of `Currency`, except `addCurrency`.
+
 ## 1.1.2 (2021-04-19)
 
 ### Changed

src/Currency.php

@@ -1526,6 +1526,36 @@ final class Currency implements JsonSerializable
      */
     private $currencyCode;
 
+    /**
+     * @var string
+     */
+    private $displayName;
+
+    /**
+     * @var int
+     */
+    private $numericCode;
+
+    /**
+     * @var int
+     */
+    private $defaultFractionDigits;
+
+    /**
+     * @var int
+     */
+    private $subUnit;
+
+    /**
+     * @var string
+     */
+    private $sign;
+
+    /**
+     * @var bool
+     */
+    private $deprecated;
+
     public function __construct(string $currencyCode)
     {
         $currencyCode = mb_strtoupper($currencyCode);
@@ -1534,15 +1564,27 @@ public function __construct(string $currencyCode)
             throw new InvalidArgumentException(sprintf('Unknown currency code "%s"', $currencyCode));
         }
 
+        assert(isset(
+            self::$currencies[$currencyCode]['display_name'],
+            self::$currencies[$currencyCode]['numeric_code'],
+            self::$currencies[$currencyCode]['default_fraction_digits'],
+            self::$currencies[$currencyCode]['sub_unit'],
+            self::$currencies[$currencyCode]['sign'],
+            self::$currencies[$currencyCode]['pretty_print_format'],
+            self::$currencies[$currencyCode]['negative_pretty_print_format'],
+            self::$currencies[$currencyCode]['deprecated'],
+        ));
+
         $this->currencyCode = $currencyCode;
+        $this->displayName = self::$currencies[$currencyCode]['display_name'];
+        $this->numericCode = self::$currencies[$currencyCode]['numeric_code'];
+        $this->defaultFractionDigits = self::$currencies[$currencyCode]['default_fraction_digits'];
+        $this->subUnit = self::$currencies[$currencyCode]['sub_unit'];
+        $this->sign = self::$currencies[$currencyCode]['sign'];
+        $this->deprecated = self::$currencies[$currencyCode]['deprecated'];
     }
 
-    /**
-     * Returns the ISO 4217 currency code of this currency.
-     *
-     * @return string
-     */
-    public function __toString()
+    public function __toString(): string
     {
         return $this->getCurrencyCode();
     }
@@ -1607,6 +1649,8 @@ public static function getCurrenciesIncludingDeprecated(): array
 
     /**
      * Returns the ISO 4217 currency code of this currency.
+     *
+     * @psalm-mutation-free
      */
     public function getCurrencyCode(): string
     {
@@ -1616,60 +1660,77 @@ public function getCurrencyCode(): string
     /**
      * Returns the default number of fraction digits used with this
      * currency.
+     *
+     * @psalm-mutation-free
      */
     public function getDefaultFractionDigits(): int
     {
-        return self::$currencies[$this->getCurrencyCode()]['default_fraction_digits'];
+        return $this->defaultFractionDigits;
     }
 
     /**
      * Returns the name that is suitable for displaying this currency.
+     *
+     * @psalm-mutation-free
      */
     public function getDisplayName(): string
     {
-        return self::$currencies[$this->getCurrencyCode()]['display_name'];
+        return $this->displayName;
     }
 
     /**
      * Returns the ISO 4217 numeric code of this currency.
+     *
+     * @psalm-mutation-free
      */
     public function getNumericCode(): int
     {
-        return self::$currencies[$this->getCurrencyCode()]['numeric_code'];
+        return $this->numericCode;
     }
 
     /**
      * Returns the minor currency sub units.
+     *
+     * @psalm-mutation-free
      */
     public function getSubUnit(): int
     {
-        return self::$currencies[$this->getCurrencyCode()]['sub_unit'];
+        return $this->subUnit;
     }
 
     /**
      * Returns the currency sign.
+     *
+     * @psalm-mutation-free
      */
     public function getSign(): string
     {
-        return self::$currencies[$this->getCurrencyCode()]['sign'];
+        return $this->sign;
     }
 
     /**
      * Returns the deprecation status.
+     *
+     * @psalm-mutation-free
      */
     public function isDeprecated(): bool
     {
-        return self::$currencies[$this->getCurrencyCode()]['deprecated'];
+        return $this->deprecated;
     }
 
     /**
      * {@inheritdoc}
+     *
+     * @psalm-mutation-free
      */
     public function jsonSerialize(): string
     {
         return $this->getCurrencyCode();
     }
 
+    /**
+     * @psalm-mutation-free
+     */
     public function equals(self $currency): bool
     {
         return $this->getCurrencyCode() === $currency->getCurrencyCode();

src/Money.php

@@ -17,6 +17,8 @@
  * @see http://www.github.com/sebastianbergmann/money
  * @see http://martinfowler.com/bliki/ValueObject.html
  * @see http://martinfowler.com/eaaCatalog/money.html
+ *
+ * @psalm-immutable
  */
 final class Money implements JsonSerializable
 {
@@ -195,9 +197,7 @@ public function getCurrency(): Currency
      */
     public function add(self $other): self
     {
-        $this->assertSameCurrency($other);
-
-        $value = $this->getAmount() + $other->getAmount();
+        $value = $this->getAmount() + $this->castOtherAmountToInt($other);
 
         if (!is_int($value)) {
             throw new OverflowException('Value reached maximum amount');
@@ -219,9 +219,7 @@ public function add(self $other): self
      */
     public function subtract(self $other): self
     {
-        $this->assertSameCurrency($other);
-
-        $value = $this->getAmount() - $other->getAmount();
+        $value = $this->getAmount() - $this->castOtherAmountToInt($other);
 
         if (!is_int($value)) {
             throw new UnderflowException('Value reached minimum amount');
@@ -254,11 +252,7 @@ public function negate(): self
      */
     public function multiply(float $factor, int $roundingMode = PHP_ROUND_HALF_UP): self
     {
-        $this->assertRoundingMode($roundingMode);
-
-        $amount = round($factor * $this->getAmount(), 0, $roundingMode);
-
-        return $this->changeFloatAmount($amount);
+        return $this->changeFloatAmount($this->roundValueByMode($factor * $this->getAmount(), $roundingMode));
     }
 
     /**
@@ -342,12 +336,12 @@ public function allocateByRatios(array $ratios): array
      *
      * @see https://github.com/sebastianbergmann/money/issues/27
      *
-     * @param float $percentage
+     * @param float|int $percentage
      * @param int $roundingMode
      *
      * @return self[]
      */
-    public function extractPercentage($percentage, $roundingMode = PHP_ROUND_HALF_UP): array
+    public function extractPercentage($percentage, int $roundingMode = PHP_ROUND_HALF_UP): array
     {
         $amount = round($this->getAmount() / (100 + $percentage) * $percentage, 0, $roundingMode);
         $percentage = $this->changeFloatAmount($amount);
@@ -373,9 +367,7 @@ public function extractPercentage($percentage, $roundingMode = PHP_ROUND_HALF_UP
      */
     public function compareTo(self $other): int
     {
-        $this->assertSameCurrency($other);
-
-        return $this->getAmount() <=> $other->getAmount();
+        return $this->getAmount() <=> $this->castOtherAmountToInt($other);
     }
 
     /**
@@ -480,39 +472,41 @@ public function isNegative(): bool
      * Convert currency to a target currency given a conversion rate and rounding mode.
      *
      * @param Currency $targetCurrency
-     * @param $conversionRate
-     * @param $roundingMode
+     * @param float $conversionRate
+     * @param int $roundingMode
      *
      * @return self
      */
     public function convert(Currency $targetCurrency, float $conversionRate, int $roundingMode): self
     {
-        $this->assertRoundingMode($roundingMode);
-
-        $targetAmount = $this->castToInt(round($conversionRate * $this->getAmount(), 0, $roundingMode));
-
-        return new self($targetAmount, $targetCurrency);
+        return new self(
+            $this->castToInt($this->roundValueByMode($conversionRate * $this->getAmount(), $roundingMode)),
+            $targetCurrency,
+        );
     }
 
     /**
-     * Asserts that rounding mode is a valid integer value.
-     *
+     * @param float|int $value
      * @param int $roundingMode
      *
-     * @throws InvalidArgumentException
+     * @return float
      */
-    private function assertRoundingMode(int $roundingMode): void
+    private function roundValueByMode($value, int $roundingMode): float
     {
         if (!in_array($roundingMode, self::ROUNDING_MODES, true)) {
             throw new InvalidArgumentException('$roundingMode must be a valid rounding mode (PHP_ROUND_*)');
         }
+
+        return round($value, 0, $roundingMode);
     }
 
-    private function assertSameCurrency(self $other): void
+    private function castOtherAmountToInt(self $amount): int
     {
-        if (!$this->getCurrency()->equals($other->getCurrency())) {
+        if (!$this->getCurrency()->equals($amount->getCurrency())) {
             throw new CurrencyMismatchException();
         }
+
+        return $amount->getAmount();
     }
 
     /**

tests/MoneyTest.php

@@ -9,6 +9,8 @@
 
 /**
  * Class MoneyTest.
+ *
+ * @psalm-suppress UnusedMethodCall Some methods are called with expectation of exceptions.
  */
 class MoneyTest extends TestCase
 {