{"id":13739015,"url":"https://github.com/Stichoza/nbg-currency","last_synced_at":"2025-05-08T18:31:37.563Z","repository":{"id":47974340,"uuid":"48929576","full_name":"Stichoza/nbg-currency","owner":"Stichoza","description":"💵 National Bank of Georgia (NBG) currency service API wrapper in PHP","archived":false,"fork":false,"pushed_at":"2023-08-07T09:02:39.000Z","size":127,"stargazers_count":28,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T15:51:51.519Z","etag":null,"topics":["currency","currency-converter","currency-exchange-rates","gel","georgia","georgian","lari","nbg"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stichoza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"patreon":"stichoza","liberapay":"stichoza","ko_fi":"stichoza","open_collective":"stichoza","custom":["https://www.paypal.me/stichoza","https://btc.com/bc1qc25j4x7yahghm8nnn6lypnw59nptylsw32nkfl"]}},"created_at":"2016-01-03T01:08:09.000Z","updated_at":"2025-04-14T09:31:19.000Z","dependencies_parsed_at":"2024-01-25T00:31:13.384Z","dependency_job_id":null,"html_url":"https://github.com/Stichoza/nbg-currency","commit_stats":{"total_commits":122,"total_committers":1,"mean_commits":122.0,"dds":0.0,"last_synced_commit":"3049d6d5793681f8a260bb8d9fa5a0b52ed37098"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stichoza%2Fnbg-currency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stichoza%2Fnbg-currency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stichoza%2Fnbg-currency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stichoza%2Fnbg-currency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stichoza","download_url":"https://codeload.github.com/Stichoza/nbg-currency/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253127068,"owners_count":21858185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["currency","currency-converter","currency-exchange-rates","gel","georgia","georgian","lari","nbg"],"created_at":"2024-08-03T04:00:23.203Z","updated_at":"2025-05-08T18:31:37.499Z","avatar_url":"https://github.com/Stichoza.png","language":"PHP","funding_links":["https://patreon.com/stichoza","https://liberapay.com/stichoza","https://ko-fi.com/stichoza","https://opencollective.com/stichoza","https://www.paypal.me/stichoza","https://btc.com/bc1qc25j4x7yahghm8nnn6lypnw59nptylsw32nkfl"],"categories":["Categories"],"sub_categories":[],"readme":"# NBG Currency\n\n[![Latest Stable Version](https://img.shields.io/packagist/v/Stichoza/nbg-currency.svg)](https://packagist.org/packages/stichoza/nbg-currency) [![Total Downloads](https://img.shields.io/packagist/dt/Stichoza/nbg-currency.svg)](https://packagist.org/packages/stichoza/nbg-currency)\n\nNational Bank of Georgia (NBG) currency service API wrapper in PHP\n\n## Installation\n\nInstall this package via [Composer](https://getcomposer.org/).\n\n```\ncomposer require stichoza/nbg-currency\n```\n\u003e **Note**\n\u003e PHP 8.1 or later is required. Use following versions of this package for older PHP versions:\n\n| Package version | PHP Version  | Documentation                                                                                 |\n|-----------------|--------------|-----------------------------------------------------------------------------------------------|\n| `v3.0`          | PHP \u003e= 8.1   | [v3 Docs](#nbg-currency)                                                                      |\n| `v2.0`          | PHP \u003e= 7.1.8 | [v2 Docs](https://github.com/Stichoza/nbg-currency/tree/2.0#nbg-currency)                     |\n| ~~`v1.2`~~      | PHP \u003e= 5.5.9 | ~~[v1.2 Docs](https://github.com/Stichoza/nbg-currency/tree/1.2#nbg-currency)~~ (Not working) |\n\n## Quick Examples\n\n```php\nNbgCurrency::rate('usd'); // 2.7177\nNbgCurrency::rate('usd', '2022-12-02'); // 2.7112\n\nNbgCurrency::get('usd')-\u003erate; // 2.7177\nNbgCurrency::get('usd', '2022-12-02')-\u003erate; // 2.7112\nNbgCurrency::get('usd', '2022-12-02', 'en')-\u003ename; // US Dollar\n\nNbgCurrency::date(Carbon::yesterday())-\u003eget('usd')-\u003ediff; // 0.0012\nNbgCurrency::date('2022-12-02', 'en')-\u003eget('usd')-\u003eincreased(); // true\n```\n\nContinue reading for more details about additional functionality.\n\n## Basic Usage\n\nThe class is namespaced as `Stichoza\\NbgCurrency\\NbgCurrency`:\n\n```php\nuse Stichoza\\NbgCurrency\\NbgCurrency;\n```\n\nThis package has three main static methods from which you can access currency rates.\n\n### Get Currency Rate\n\nThe `NbgCurrency::rate()` method returns a currency rate in `float`.\n\n```php\nNbgCurrency::rate(string $code, DateTimeInterface|string|null $date = null): float\n```\n\n| Parameter | Default | Description                                                                                                                               |\n|-----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|\n| `$code`   |         | Currency code, not case-sensitive                                                                                                         |\n| `$date`   | `null`  | Date of currency rate: [Carbon](https://carbon.nesbot.com), [DateTime](https://www.php.net/manual/en/class.datetime.php), string or null. |\n\n\u003e **Important**\n\u003e The rate is always for a **single unit**. The original NBG JSON API returns rate for different amounts per currency. For example Japanese Yen (JPY) rate will be 1.9865 and quantity will be set to 100 (100 JPY is 1.9865 GEL). It is quite confusing during calculations so **this package always returns price per single unit**. So in this case JPY will be 0.019865 (1 JPY is 0.019865 GEL).\n\n**Examples:**\n\n```php\nNbgCurrency::rate('usd'); // Returns current rate of USD. Example: 2.7177\nNbgCurrency::rate('usd', '2022-12-02'); // USD rate on 2022-12-02\nNbgCurrency::rate('eur', 'yesterday'); // EUR rate from yesterday. Strings are parsed via Carbon::parse()\nNbgCurrency::rate('eur', Carbon::yesterday()); // EUR rate from yesterday\nNbgCurrency::rate('gbp', Carbon::today()-\u003esubDays(5)); // GBP rate 5 days ago\nNbgCurrency::rate('gbp', new DateTime()); // GBP rate today\n\nif (NbgCurrency::rate('usd') \u003e 3) {\n    echo 'Oh no!';\n}\n```\n\nWhen passing dates as [`Carbon`](https://carbon.nesbot.com) or `DateTime` objects, it's recommended to have its timezone set to `Asia/Tbilisi` to avoid unexpected behavior. For convenience, timezone string is available as `NbgCurrency::TIMEZONE` class constant.\n\n### Get Currency Object\n\nThe `NbgCurrency::get()` method returns a `Currency` object containing data of a currency for specified date.\n\nThis method accepts same parameters as `::rate()` method and one additional parameter for language (Used for currency name).\n\n```php\nNbgCurrency::get(string $code, DateTimeInterface|string|null $date = null, string $language = 'ka'): Currency\n```\n\n| Parameter   | Default | Description                                              |\n|-------------|---------|----------------------------------------------------------|\n| `$code`     |         | Currency code, not case-sensitive                        |\n| `$date`     | `null`  | Date of currency rate                                    |\n| `$language` | `ka`    | Language for currency name (Currently only `en` or `ka`) |\n\n**Examples:**\n\n```php\n$usd = NbgCurrency::get('usd'); // Currency object (Stichoza\\NbgCurrency\\Data\\Currency)\n\n$usd-\u003ecode; // USD\n$usd-\u003erate; // 2.7112\n$usd-\u003ename; // აშშ დოლარი\n$usd-\u003ediff; // -0.0065\n$usd-\u003edate; // Carbon object of date: 2022-12-01 17:45:12\n$usd-\u003evalidFrom; // Carbon object since when the rate is valid: 2022-12-02 00:00:00\n$usd-\u003echange; // Currency rate change. -1 if decreased, 0 if unchanged and 1 if increased.\n\n// Using methods available on Carbon objects\n$usd-\u003edate-\u003eformat('j F Y'); // 1 December 2022\n$usd-\u003edate-\u003ediffForHumans(); // 3 days ago\n$usd-\u003evalidFrom-\u003eisPast(); // true\n\n// Additional methods\n$usd-\u003eincreased(); // Returns true if rate has increased, false otherwise.\n$usd-\u003edecreased(); // Returns true if rate has decreased, false otherwise.\n$usd-\u003eunchanged(); // Returns true if rate hasn't changed, false otherwise.\n\n// The changeString() method returns first parameter if rate was increased, second string if there was\n// no change and third string if the rate went up. Useful for CSS classes, font icons, etc.\n$class = $usd-\u003echangeString('text-red', 'text-gray', 'text-green');\n$icon  = $usd-\u003echangeString('fa-arrow-down', 'fa-circle', 'fa-arrow-down');\n```\n\n\u003e **Note**\n\u003e All properties of `Currency` class are declared as `readonly`. Updating them will result in Fatal Error.\n\n## Advanced Usage\n\n### Get All Currencies\n\nThe `NbgCurrency::date()` method will return a `Currencies` object. This is a collection-like object that contains a list of all `Currency` objects available for specified date.\n\n```php\nNbgCurrency::date(DateTimeInterface|string|null $date = null, string $language = 'ka'): Currencies\n```\n\n| Parameter   | Default | Description                                                    |\n|-------------|---------|----------------------------------------------------------------|\n| `$date`     | `null`  | Date of currency rates                                         |\n| `$language` | `ka`    | Language for names of currencies (Currently only `en` or `ka`) |\n\n**Examples:**\n\n```php\n$currencies = NbgCurrency::date('3 days ago');\n$currencies = NbgCurrency::date(Carbon::now()-\u003estartOfMonth(), 'en');\n```\n\n`Currencies` class has date attribute and several methods that you can use.\n\n```php\n$currencies-\u003edate; // Carbon object of date\n\n$currencies-\u003eget('usd'); // Returns Currency object for USD\n$currencies-\u003ehas('eur'); // True if EUR currency is contained in $currencies collection\n$currencies-\u003ecount(); // Count of Currency objects in collection\n\n$currencies-\u003eget('usd')-\u003erate; // Currency rate of USD\n$currencies-\u003eget('eur')-\u003edate-\u003ediffForHumans(); // 10 days ago\n```\n\nNote that `-\u003eget()` method of `Currencies` object has only one parameter `string $code`, while the static method with the same name (`NbgCurrency::get()`) has two additional parameters described in basic usage examples above.\n\nThe `Currencies` object also implements `Countable` and `IteratorAggregate` interfaces, so you can use the object in `foreach` loops and `count()` function.\n\n**Examples:**\n\n```php\n$currencies = NbgCurrency::date('2022-12-02', 'en'); // Currencies object (Stichoza\\NbgCurrency\\Data\\Currencies) \n\necho 'Total ' . count($currencies) . ' currencies for ' . $currencies-\u003edate-\u003etoFormattedDateString();\n// Total 43 currencies for Dec 2, 2022\n\nforeach ($currencies as $code =\u003e $currency) {\n    echo $currency-\u003ecode . ' costs ' . $currency-\u003erate;\n}\n// AED costs 7.3662\n// AMD costs 6.8453\n// ...\n```\n\n## Error Handling\n\nThere are 5 exceptions in `Stichoza\\NbgCurrency\\Exceptions` namespace that could be thrown from methods:\n\n - `CurrencyNotFoundException` - If currency is not available.\n - `DateNotFoundException` - If specified date is not available.\n - `LanguageNotFoundException` - If specified language is not available.\n - `InvalidDateException` - If the specified date is in invalid format or cannot be parsed.\n - `RequestFailedException` - If there was an error during API request.\n\nAll exceptions above extend `Exception` class, so you can handle all exceptions by catching `Exception` or `Throwable`.\n\n```php\ntry {\n    $usdRate = NbgCurrency::date('10 days ago', 'en')-\u003eget('usd')-\u003erate;\n} catch (Exception) {\n    // Whoops...\n}\n```\n\n## Additional Info\n\n### Number of HTTP Requests\nWhen you access any currency, all currencies for that day in selected language will be fetched (API returns all currencies in a single request) and stored in NbgCurrency class attribute. When you request any other currency, no additional HTTP requests will be made for same date and language.\n\n```php\n// Next 3 method calls will result in 1 HTTP request in total.\nNbgCurrency::rate('usd');\nNbgCurrency::rate('eur');\nNbgCurrency::rate('gbp');\n\n// Next 3 method calls will result in 3 HTTP requests in total.\nNbgGurrency::rate('usd', '2022-10-10');\nNbgGurrency::rate('eur', '2022-11-11', 'en');\nNbgGurrency::rate('gbp', '2022-11-11');\n\n// Next 3 method calls will result in 2 HTTP request in total.\nNbgGurrency::rate('usd', '2022-11-11');\nNbgGurrency::rate('eur', '2022-11-11');\nNbgGurrency::rate('gbp', '2022-11-11', 'en');\n```\n\n### Memory Usage \u0026 Caching\n\nBy default, all retrieved currencies are stored in a static property of `NbgCurrency` class. If you're planning to get currencies for many different dates, it might use excessive memory. In this case it's recommended to turn off the caching feature.\n\n```php\nNbgCurrency::disableCaching(); // Disable caching, also removes data stored in the property.\nNbgCurrency::enableCaching(); // Enables caching in class property.\n```\n\nOn the other hand, disabling caching may increase number of HTTP requests being sent. Example:\n\n```php\n$codes = ['USD', 'EUR', 'GBP', 'UAH', 'JPY'];\n\nforeach ($codes as $code) {\n    echo NbgCurrency::rate($code);\n}\n```\n\nThe above code would make a single HTTP request to the API when caching is enabled. But if you disable caching, it will send 5 separate HTTP requests. To load multiple currencies of same date using a single HTTP request with caching disabled, you can use `::date()` method to get `Currencies` object and then access all contained objects after.\n\n```php\n$codes = ['USD', 'EUR', 'GBP', 'UAH', 'JPY'];\n\n$currencies = NbgCurrency::date();\n\nforeach ($codes as $code) {\n    echo $currencies-\u003eget($code)-\u003erate;\n}\n```\n\nIn this case there will be a single HTTP request made even with caching disabled.\n\n### Keywords\n\n\u003e ლარის კურსი, ეროვნული ბანკის გაცვლითი კურსი, ვალუტა, ლარის ვალუტის კურსი, laris kursi, laris valuta, lari currency, national bank of georgia, nbg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStichoza%2Fnbg-currency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FStichoza%2Fnbg-currency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FStichoza%2Fnbg-currency/lists"}