{"id":37379646,"url":"https://github.com/maciej-sz/nbp-php","last_synced_at":"2026-01-16T05:05:53.284Z","repository":{"id":27729969,"uuid":"31217478","full_name":"maciej-sz/nbp-php","owner":"maciej-sz","description":"API for accessing NBP (Narodowy Bank Polski) currecy rates in PHP","archived":false,"fork":false,"pushed_at":"2025-04-19T08:33:18.000Z","size":343,"stargazers_count":12,"open_issues_count":10,"forks_count":11,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T15:06:35.883Z","etag":null,"topics":["comodity","currencies","currency","currency-converter","currency-exchange","currency-exchange-rates","currency-rates","money","nbp","nbp-api","php"],"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/maciej-sz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-02-23T16:37:58.000Z","updated_at":"2025-04-19T08:33:22.000Z","dependencies_parsed_at":"2024-06-21T19:09:20.009Z","dependency_job_id":"ee870511-0162-48e0-9dcf-e2f965da4fa7","html_url":"https://github.com/maciej-sz/nbp-php","commit_stats":{"total_commits":33,"total_committers":3,"mean_commits":11.0,"dds":0.06060606060606055,"last_synced_commit":"bc724f431df18f1527002bed5be8357693204b7d"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/maciej-sz/nbp-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maciej-sz%2Fnbp-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maciej-sz%2Fnbp-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maciej-sz%2Fnbp-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maciej-sz%2Fnbp-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maciej-sz","download_url":"https://codeload.github.com/maciej-sz/nbp-php/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maciej-sz%2Fnbp-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["comodity","currencies","currency","currency-converter","currency-exchange","currency-exchange-rates","currency-rates","money","nbp","nbp-api","php"],"created_at":"2026-01-16T05:05:52.680Z","updated_at":"2026-01-16T05:05:53.279Z","avatar_url":"https://github.com/maciej-sz.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nbp-php\n\nAPI for accessing Polish National Bank (NBP - Narodowy Bank Polski) currency and commodities exchange rates.\n\n[![Latest Version on Packagist][badge-version]][link-packagist]\n[![No dependencies][badge-no-deps]][link-packagist]\n[![MIT License][badge-license]][link-license]\n\n[![Tests Coverage][badge-coverage]][link-coverage]\u003cbr /\u003e\n[![PHP 8.1 Test Result][badge-test-result-8.1]][link-php-tests]\u003cbr /\u003e\n[![PHP 8.2 Test Result][badge-test-result-8.2]][link-php-tests]\u003cbr /\u003e\n[![PHP 8.3 Test Result][badge-test-result-8.3]][link-php-tests]\u003cbr /\u003e\n[![PHP 8.4 Test Result][badge-test-result-8.4]][link-php-tests]\u003cbr /\u003e\n[![PHP 8.5 Test Result][badge-test-result-8.5]][link-php-tests]\n\n## Installing via composer\n\n```bash\ncomposer require maciej-sz/nbp-php\n```\n\n\n## Usage\n\nThe full API of this library can be found in [api.md](api.md).\n\n### Minimal setup\n\n```php\n\u003c?php\nrequire_once 'vendor/autoload.php';\n\nuse MaciejSz\\Nbp\\Service\\CurrencyAverageRatesService;\n\n$currencyAverages = CurrencyAverageRatesService::new();\n$rate = $currencyAverages-\u003efromDay('2023-01-02')-\u003efromTable('A')-\u003egetRate('USD');\n\nprintf('%s rate is %d', $rate-\u003egetCurrencyCode(), $rate-\u003egetValue());\n```\n\n```\nUSD rate is 4.381100\n```\n\n### Examples\n\nSee the [examples](./examples/) directory for complete and runnable examples.\n\n\n\n### Using cache\n\n_Note that a library implementing PSR-6 has to be provided in order to use the caching\nabilities._\n\nThe `CachedTransport` class is a proxy for all other transport implementations.\nThis transport has to be backed by another transport, as it relies on it to\nmake the actual requests that have not been cached yet.\n\n#### Example\n\n```php\nuse Symfony\\Component\\Cache\\Adapter\\FilesystemAdapter as CachePoolAdapter;\n\n// 1) create repository backed by caching transport\n$cachePool = new CachePoolAdapter();\n$cachingTransportFactory = CachingTransportFactory::new($cachePool);\n$client = NbpWebClient::new(transportFactory: $cachingTransportFactory);\n$nbpRepository = NbpWebRepository::new($client);\n\n// 2) create needed services using cache-backed repository:\n$goldRates = new GoldRatesService($nbpRepository);\n\n// 3) run multiple times to check the effect of caching:\n$start = microtime(true);\n$goldRates-\u003efromDayBefore('2013-05-15')-\u003egetValue();\n$end = microtime(true);\n$took = $end - $start;\nprintf('Getting the rate took %F ms', $took * 1000);\n```\n\n### Using custom transport\n\nThe library uses Symfony HTTP Client and Guzzle as default transports.\nIf those packages are not available then it falls back to the `file_get_contents`\nmethod. This may not be ideal in some situations. Especially when there is no access\nto HTTP client packages as may be the case when using PHP version prior to 8.0.\n\nIn such cases it is suggested to use different transport. It can be achieved \nby replacing the `TransportFactory` of the `NbpClient` with your own implementation.\n\n```php\n$customTransportFactory = new class() implements TransportFactory {\n    public function create(string $baseUri): Transport\n    {\n        return new class() implements Transport {\n            public function get(string $path): array\n            {\n                echo \"Requesting resource: {$path}\" . PHP_EOL;\n\n                $ch = curl_init();\n                $url = NbpWebClient::BASE_URL . $path;\n                curl_setopt($ch, CURLOPT_URL, $url);\n                curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);\n                try {\n                    $output = curl_exec($ch);\n                } finally {\n                    curl_close($ch);\n                }\n\n                echo 'Request successful' . PHP_EOL;\n\n                return json_decode($output, true);\n            }\n        };\n    }\n};\n\n$client = NbpWebClient::new(transportFactory: $customTransportFactory);\n$nbpRepository = NbpWebRepository::new($client);\n$goldRates = GoldRatesService::new($nbpRepository);\n\n$rate = $goldRates-\u003efromDay('2022-01-03');\n\nprintf(\n    'Gold rate from %s is %F',\n    $rate-\u003egetDate()-\u003eformat('Y-m-d'),\n    $rate-\u003egetValue()\n);\n```\n\n```\nRequesting resource: /api/cenyzlota/2022-01-01/2022-01-31\nRequest successful\nGold rate from 2022-01-03 is 235.720000\n```\n\n## Architecture\n\nOn the infrastructure level the code utilizes layered architecture to keep the concerns separated.\n\n### Service layer\n\nThe service consists of [facades](https://refactoring.guru/design-patterns/facade)\nfor the package. Classes here are named `services` instead of facades due to common\nunderstanding of this word as something through which you access the internals of a system.\n\nThis layer provides a high level business-oriented methods for interacting\nwith the NBP API.\nIt exposes most common use cases of the `nbp-php` package and is the\nlikely starting point for all applications using this package.\nOne needs to interact with other layers only for more complex tasks.\n\nThe service layer is structured in the way that it directly communicates \nwith the repository layer.\n\n### Repository layer\n\nRepository layer allows getting data from NBP API by providing methods that\nclosely reflect the NBP Web API. This layer operates on higher level, \nhydrated domain objects.\n\nThe only constraint here is that the repository\nlayer operates on month-based dates. So for example you can get trading rates\nfrom entire month, but in order to retrieve a specific date you have to iterate\nthrough the retrieved month (you can use service layer for that).\nThis is by design for the purpose of reducing network traffic to the NBP servers.\nIt also allows simplifying caching on the transport layer, because there is no need\nfor any cache-pooling logic.\n\n### Client layer\n\nClient layer is a bridge between the repository and the transport layer.\nIt processes request objects on the input, and then it uses the transport layer \nto fulfill those requests.\n\nThe requests thet client layer uses are higher-level requests then those on\nthe transport layer. They implement `NbpClientRequest` interface.\n\n### Transport layer\n\nThe transport layer is responsible for directly interacting with the NBP API.\nA few independent transport implementations are provided for serving\nconnections to the NBP API. \n\nIt is also equipped with a convenient factories which pick the most appropriate\nimplementation depending on installed libraries and configuration.\n\n[badge-version]:https://img.shields.io/packagist/v/maciej-sz/nbp-php.svg?style=shield\n[badge-no-deps]:https://img.shields.io/badge/dependencies-none-brightgreen.svg?style=shield\n[badge-license]:https://img.shields.io/badge/license-MIT-blue.svg?style=shield\n\n[badge-test-result-8.1]:https://img.shields.io/endpoint?url=https%3A%2F%2Fkvdb.io%2F96S9JomzUfJKGdkpUQHBkD%2Ftest-result-8.1\n[badge-test-result-8.2]:https://img.shields.io/endpoint?url=https%3A%2F%2Fkvdb.io%2F96S9JomzUfJKGdkpUQHBkD%2Ftest-result-8.2\n[badge-test-result-8.3]:https://img.shields.io/endpoint?url=https%3A%2F%2Fkvdb.io%2F96S9JomzUfJKGdkpUQHBkD%2Ftest-result-8.3\n[badge-test-result-8.4]:https://img.shields.io/endpoint?url=https%3A%2F%2Fkvdb.io%2F96S9JomzUfJKGdkpUQHBkD%2Ftest-result-8.4\n[badge-test-result-8.5]:https://img.shields.io/endpoint?url=https%3A%2F%2Fkvdb.io%2F96S9JomzUfJKGdkpUQHBkD%2Ftest-result-8.5\n\n[badge-coverage]:https://img.shields.io/endpoint?url=https%3A%2F%2Fkvdb.io%2F96S9JomzUfJKGdkpUQHBkD%2Fcoverage\n\n[link-packagist]:https://packagist.org/packages/maciej-sz/nbp-php\n[link-license]:https://github.com/maciej-sz/nbp-php/blob/master/LICENSE\n[link-php-tests]:https://github.com/maciej-sz/nbp-php/actions/workflows/php-tests.yml\n[link-coverage]:https://github.com/maciej-sz/nbp-php/actions/workflows/master-coverage.yml","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaciej-sz%2Fnbp-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaciej-sz%2Fnbp-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaciej-sz%2Fnbp-php/lists"}