Currencies Update (#10)

Currencies Update

Author: PostScripton

README.md

@@ -277,9 +277,11 @@ In order to get a specific currency:
 use PostScripton\Money\Currency;
 
 $usd = Currency::code('USD');
+$usd = Currency::code('usd');
+$usd = Currency::code('840');
 ```
 
-❗ Only international codes such as “USD”, “EUR”, “RUB” and so on should be used as a code.
+❗ Only international codes such as USD / 840, EUR / 978, RUB / 643 and so on should be used as a code.
 
 ---
 
@@ -291,9 +293,28 @@ You can also get or change some data from Currency object:
 use PostScripton\Money\Currency;
 
 $usd = Currency::code('USD');
-$usd->getCode();        // USD
+
+$usd->getFullName();    // "United States dollar"
+$usd->getName();        // "dollar"
+$usd->getCode();        // "USD"
+$usd->getNumCode();     // "840"
 $usd->getSymbol();      // "$"
 $usd->getPosition();    // 0 (Currency::POS_START)
+$usd->getDisplay();     // 10 (Currency::DISPLAY_SYMBOL)
+```
+
+`getSymbol()` takes an index as first parameter only if there are more than one symbol for the currency.
+
+```php
+use PostScripton\Money\Currency;
+
+Currency::setCurrencyList(Currency::LIST_ALL);
+
+$currency = Currency::code('EGP');
+
+// ['£', 'ج.م']
+$currency->getSymbol();     // '£'
+$currency->getSymbol(1);    // 'ج.م'
 ```
 
 ---
@@ -319,6 +340,49 @@ $money->toString();                             // "123.4 $"
 
 ---
 
+#### Display
+You may specify the way to display the currency whether it will be as an iso-code or a symbol.
+Use following constants:
+
+```php
+use PostScripton\Money\Currency;
+use PostScripton\Money\Money;
+
+$money = new Money(1234);
+
+$money->settings->getCurrency()->getDisplay();  // 10 (Currency::DISPLAY_SYMBOL)
+$money->toString();                             // "$ 123.4"
+
+$money->settings->getCurrency()->setDisplay(Currency::DISPLAY_CODE);
+
+$money->settings->getCurrency()->getDisplay();  // 11 (Currency::DISPLAY_CODE)
+$money->toString();                             // "USD 123.4"
+
+// If you don't like the look of the code at the beginning
+$money->settings->getCurrency()->setPosition(Currency::POS_END);
+$money->toString();                             // "123.4 USD"
+```
+
+---
+
+#### Currency List
+If you wish, you may select another currency list.
+To select currency list by default, go to the `config/money.php` and find there `currency_list`.
+
+All the lists are located at `vendor/postscripton/money/src/List`, so if you want, you can check something up there.
+
+```php
+use PostScripton\Money\Currency;
+
+Currency::setCurrencyList(Currency::LIST_POPULAR);
+Currency::code('USD');
+
+Currency::setCurrencyList(Currency::LIST_ALL);
+Currency::code('EGP');
+```
+
+---
+
 ### 💵 Money
 Here we are, prepared and ready to create our own Money objects.
 
@@ -541,4 +605,4 @@ use PostScripton\Money\Money;
 
 $money = new Money(1234);
 $money->toString(); // "$ 123.4"
-```
+```

composer.json

@@ -1,7 +1,7 @@
 {
     "name": "postscripton/laravel-money",
     "description": "A convenient way to convert numbers from DB or inputs into money strings for humans",
-  	"version": "2.1.0",
+  	"version": "2.2.0",
   	"type": "library",
     "license": "MIT",
     "authors": [

config/money.php

@@ -16,6 +16,23 @@
     */
 	'default_currency' => 'USD',
 
+    /*
+    |--------------------------------------------------------------------------
+    | Currency Lists
+    |--------------------------------------------------------------------------
+    |
+    | This option controls which list of currencies will be used.
+    |
+    | For now following lists are provided:
+    | 1. all - all the currencies in the world.
+    | 2. popular - only the most popular ones (35) are used. (default)
+    |
+    | Segregation of currencies is assumed for performance purposes so that
+    | unnecessary ones won't be used.
+    |
+    */
+    'currency_list' => 'popular',
+
 	/*
     |--------------------------------------------------------------------------
     | Thousands separator

src/Currency.php

@@ -2,7 +2,11 @@
 
 namespace PostScripton\Money;
 
+use Illuminate\Support\Collection;
 use PostScripton\Money\Exceptions\CurrencyDoesNotExistException;
+use PostScripton\Money\Exceptions\CurrencyHasWrongConstructorException;
+use PostScripton\Money\Exceptions\CurrencyListConfigException;
+use PostScripton\Money\Exceptions\NoSuchCurrencySymbolException;
 use PostScripton\Money\Exceptions\ShouldPublishConfigFileException;
 
 class Currency
@@ -12,38 +16,76 @@ class Currency
     public const POS_START = 0;
     public const POS_END = 1;
 
+    public const DISPLAY_SYMBOL = 10;
+    public const DISPLAY_CODE = 11;
+
+    public const LIST_ALL = 'all';
+    public const LIST_POPULAR = 'popular';
+    private static string $_list;
+
     public static function code(string $code): ?Currency
     {
-        $code = strtoupper($code);
+        $currency = is_numeric($code)
+            ? self::currencies()->firstWhere('num_code', $code)
+            : self::currencies()->firstWhere('iso_code', strtoupper($code));
 
-        if (!array_key_exists($code, self::all())) {
-            throw new CurrencyDoesNotExistException(__METHOD__, 1, '$code', $code);
+        if (is_null($currency)) {
+            throw new CurrencyDoesNotExistException(__METHOD__, 1, '$code', implode(',', [$code, self::$_list]));
         }
 
-        $currency = self::all()[$code];
+        return new Currency($currency);
+    }
 
-        return new Currency($code, $currency['symbol'], $currency['position']);
+    protected static function currencies(): Collection
+    {
+        if (!in_array(config('money.currency_list'), [self::LIST_ALL, self::LIST_POPULAR])) {
+            throw new CurrencyListConfigException(config('money.currency_list'));
+        }
+
+        if (!self::$currencies) {
+            self::setCurrencyList(config('money.currency_list'));
+        }
+
+        return collect(self::$currencies);
     }
 
-    protected static function all(): array
+    public static function setCurrencyList(string $list = self::LIST_POPULAR)
     {
-        if (!static::$currencies) {
-            static::$currencies = require __DIR__ . '/List/currencies.php';
+        if ($list !== self::LIST_ALL && $list !== self::LIST_POPULAR) {
+            $list = self::LIST_POPULAR;
         }
-        return static::$currencies;
+
+        self::$currencies = require __DIR__ . "/List/{$list}_currencies.php";
+        self::$_list = $list;
     }
 
     // ==================== OBJECT ==================== //
 
-    private string $code;
-    private string $symbol;
-    private string $position;
+    private string $full_name;
+    private string $name;
+    private string $iso_code;
+    private string $num_code;
+    private $symbol; // array or string
+    private int $position;
+    private int $display;
 
-    public function __construct(string $code, string $symbol, ?int $position = null)
+    public function __construct(array $currency)
     {
-        $this->code = $code;
-        $this->symbol = $symbol;
-        $this->position = $position ?? self::POS_START;
+        if (is_null($currency['full_name']) ||
+            is_null($currency['name']) ||
+            is_null($currency['iso_code']) ||
+            is_null($currency['num_code']) ||
+            is_null($currency['symbol'])) {
+            throw new CurrencyHasWrongConstructorException();
+        }
+
+        $this->full_name = $currency['full_name'];
+        $this->name = $currency['name'];
+        $this->iso_code = $currency['iso_code'];
+        $this->num_code = $currency['num_code'];
+        $this->symbol = $currency['symbol'];
+        $this->position = $currency['position'] ?? self::POS_END;
+        $this->display = self::DISPLAY_SYMBOL;
     }
 
     /**
@@ -58,13 +100,45 @@ public static function getConfigCurrency(): string
         return config('money.default_currency', 'USD');
     }
 
+    public function getFullName(): string
+    {
+        return $this->full_name;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
     public function getCode(): string
     {
-        return $this->code;
+        return $this->iso_code;
     }
 
-    public function getSymbol(): string
+    public function getNumCode(): string
     {
+        return $this->num_code;
+    }
+
+    public function getSymbol(int $index = 0): string
+    {
+        if ($this->display === self::DISPLAY_CODE) {
+            return $this->iso_code;
+        }
+
+        if (is_array($this->symbol)) {
+            if (!array_key_exists($index, $this->symbol)) {
+                throw new NoSuchCurrencySymbolException(
+                    __METHOD__,
+                    1,
+                    '$index',
+                    implode(',', [$index, count($this->symbol) - 1])
+                );
+            }
+
+            return $this->symbol[$index];
+        }
+
         return $this->symbol;
     }
 
@@ -73,13 +147,28 @@ public function getPosition(): int
         return $this->position;
     }
 
-    public function setPosition(string $position): Currency
+    public function getDisplay(): int
+    {
+        return $this->display;
+    }
+
+    public function setPosition(int $position = self::POS_START): self
     {
-        if ($position !== self::POS_START || $position !== self::POS_END) {
+        if ($position !== self::POS_START && $position !== self::POS_END) {
             $position = self::POS_START;
         }
 
         $this->position = $position;
         return $this;
     }
+
+    public function setDisplay(int $display = self::DISPLAY_SYMBOL): self
+    {
+        if ($display !== self::DISPLAY_SYMBOL && $display !== self::DISPLAY_CODE) {
+            $display = self::DISPLAY_SYMBOL;
+        }
+
+        $this->display = $display;
+        return $this;
+    }
 }

src/Exceptions/CurrencyDoesNotExistException.php

@@ -12,12 +12,13 @@ public function __construct(
         $code = 0,
         BaseException $previous = null
     ) {
+        $message = explode(',', $message);
         parent::__construct(
             $method,
             $arg_num,
             $arg_name,
             'must have standard currency code: alphabetical or numeric',
-            "The currency \"{$message}\" doesn't exist",
+            "The currency \"{$message[0]}\" doesn't exist in the list \"{$message[1]}\"",
             $code,
             $previous
         );

src/Exceptions/CurrencyHasWrongConstructorException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace PostScripton\Money\Exceptions;
+
+use PostScripton\Money\Currency;
+
+class CurrencyHasWrongConstructorException extends BaseException
+{
+    public function __construct($code = 0, BaseException $previous = null)
+    {
+        parent::__construct(
+            Currency::class . ' got wrong array as a parameter for constructor thus it can not be instantiated.',
+            $code,
+            $previous
+        );
+    }
+}

src/Exceptions/CurrencyListConfigException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace PostScripton\Money\Exceptions;
+
+class CurrencyListConfigException extends BaseException
+{
+    public function __construct(string $value, $code = 0, BaseException $previous = null)
+    {
+        parent::__construct(
+            "'The config value \"money.currency_list\" must be \"all\" or \"popular\". The value \"{$value}\" was given.'",
+            $code,
+            $previous
+        );
+    }
+}

src/Exceptions/NoSuchCurrencySymbolException.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace PostScripton\Money\Exceptions;
+
+class NoSuchCurrencySymbolException extends ValueErrorException
+{
+    public function __construct(
+        string $method,
+        int $arg_num,
+        string $arg_name = null,
+        string $message = null,
+        $code = 0,
+        BaseException $previous = null
+    ) {
+        $message = explode(',', $message);
+        parent::__construct(
+            $method,
+            $arg_num,
+            $arg_name,
+            "[{$message[0]}] is out of bounds. The range [0-{$message[1]}] is supposed",
+            null,
+            $code,
+            $previous
+        );
+    }
+}