Initial commit

application/Espo/Core/Field/Currency.php

@@ -0,0 +1,208 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Field;
+
+use Espo\Core\Currency\CalculatorUtil;
+
+use RuntimeException;
+use InvalidArgumentException;
+
+/**
+ * A currency value object. Immutable.
+ */
+class Currency
+{
+    /** @var numeric-string */
+    private string $amount;
+    private string $code;
+
+    /**
+     * @param numeric-string|float|int $amount An amount.
+     * @param string $code A currency code.
+     * @throws RuntimeException
+     */
+    public function __construct($amount, string $code)
+    {
+        if (!is_string($amount) && !is_float($amount) && !is_int($amount)) {
+            throw new InvalidArgumentException();
+        }
+
+        if (strlen($code) !== 3) {
+            throw new RuntimeException("Bad currency code.");
+        }
+
+        if (is_float($amount) || is_int($amount)) {
+            $amount = (string) $amount;
+        }
+
+        $this->amount = $amount;
+        $this->code = $code;
+    }
+
+    /**
+     * Get an amount as string.
+     *
+     * @return numeric-string
+     */
+    public function getAmountAsString(): string
+    {
+        return $this->amount;
+    }
+
+    /**
+     * Get an amount.
+     */
+    public function getAmount(): float
+    {
+        return (float) $this->amount;
+    }
+
+    /**
+     * Get a currency code.
+     */
+    public function getCode(): string
+    {
+        return $this->code;
+    }
+
+    /**
+     * Add a currency value.
+     *
+     * @throws RuntimeException If currency codes are different.
+     */
+    public function add(self $value): self
+    {
+        if ($this->getCode() !== $value->getCode()) {
+            throw new RuntimeException("Can't add a currency value with a different code.");
+        }
+
+        $amount = CalculatorUtil::add(
+            $this->getAmountAsString(),
+            $value->getAmountAsString()
+        );
+
+        return new self($amount, $this->getCode());
+    }
+
+    /**
+     * Subtract a currency value.
+     *
+     * @throws RuntimeException If currency codes are different.
+     */
+    public function subtract(self $value): self
+    {
+        if ($this->getCode() !== $value->getCode()) {
+            throw new RuntimeException("Can't subtract a currency value with a different code.");
+        }
+
+        $amount = CalculatorUtil::subtract(
+            $this->getAmountAsString(),
+            $value->getAmountAsString()
+        );
+
+        return new self($amount, $this->getCode());
+    }
+
+    /**
+     * Multiply by a multiplier.
+     */
+    public function multiply(float|int $multiplier): self
+    {
+        $amount = CalculatorUtil::multiply(
+            $this->getAmountAsString(),
+            (string) $multiplier
+        );
+
+        return new self($amount, $this->getCode());
+    }
+
+    /**
+     * Divide by a divider.
+     */
+    public function divide(float|int $divider): self
+    {
+        $amount = CalculatorUtil::divide(
+            $this->getAmountAsString(),
+            (string) $divider
+        );
+
+        return new self($amount, $this->getCode());
+    }
+
+    /**
+     * Round with a precision.
+     */
+    public function round(int $precision = 0): self
+    {
+        $amount = CalculatorUtil::round($this->getAmountAsString(), $precision);
+
+        return new self($amount, $this->getCode());
+    }
+
+    /**
+     * Compare with another currency value. Returns:
+     * - `1` if greater than the value;
+     * - `0` if equal to the value;
+     * - `-1` if less than the value.
+     *
+     * @throws RuntimeException If currency codes are different.
+     */
+    public function compare(self $value): int
+    {
+        if ($this->getCode() !== $value->getCode()) {
+            throw new RuntimeException("Can't compare currencies with different codes.");
+        }
+
+        return CalculatorUtil::compare(
+            $this->getAmountAsString(),
+            $value->getAmountAsString()
+        );
+    }
+
+    /**
+     * Check whether the value is negative.
+     */
+    public function isNegative(): bool
+    {
+        return $this->compare(self::create(0.0, $this->code)) === -1;
+    }
+
+    /**
+     * Create from an amount and code.
+     *
+     * @param numeric-string|float|int $amount An amount.
+     * @param string $code A currency code.
+     * @throws RuntimeException
+     */
+    public static function create($amount, string $code): self
+    {
+        return new self($amount, $code);
+    }
+}