Download the PHP package peterlupu/curs-bnr without Composer

💱 curs-bnr

Official BNR exchange rates for PHP — with the fiscal semantics done right.

curs-bnr fetches the official exchange rates of the National Bank of Romania (cursul valutar BNR) and answers the question every Romanian invoicing, accounting, or pricing app eventually asks: "which rate applies on this date?" — exactly as the Fiscal Code defines it.

• 🪶 Zero dependencies — just PHP ≥ 8.1 with ext-simplexml. No PSR plumbing, no HTTP discovery magic.
• 🧾 Fiscal Code art. 290 semantics built in — validOn() vs communicatedOn(), so you never write subDay() + walk-back loops again.
• 📅 Historical rates back to 2005, weekends, legal holidays, and year boundaries handled for you.
• 🔁 Transient-failure retries with configurable backoff.
• 🧪 Fully unit-tested against real BNR documents — both the old and the new XML namespace (yes, BNR changed it in 2026 and broke half the ecosystem).
• 🧩 Framework-agnostic — a plain PHP class you can use anywhere and wire into any container.
• 🎭 Batteries-included testing — an ExchangeRates interface plus a shipped FakeCursBnr that runs the same semantics code as the real client, so your tests never touch the network.

📦 Installation

🚀 Quick start

That's it. No API keys, no configuration — BNR's feeds are public.

🧾 "Which rate applies today?" — the D vs D+1 rule

This is the part every BNR consumer gets subtly wrong, so it deserves its own section.

BNR communicates rates each banking day around 13:00 Romanian time. Per Fiscal Code art. 290, the rate communicated on day D is valid on day D+1 — and it stays valid through any weekend or legal holiday that follows, until the next communication.

A real example, January 2024:

Pick your method by the question you're asking:

💡 If you were previously doing $date->subDay() and then looping backwards until a rate showed up — validOn() is that, done correctly, including holiday runs and year boundaries.

💶 Rates, multipliers, and the Rate object

Every lookup returns a CursBnr\Rate:

Notes worth knowing:

• 🇭🇺 Multiplier currencies (quoted per 100 units — currently HUF, IDR, ISK, JPY, KRW; read from the feed, not hardcoded) are normalized to per-1-unit values. You never touch the multiplier unless you want to display it.
• 🥇 XAU is RON per gram of gold, as published by BNR.
• 🇷🇴 RON itself is never in the feed (everything is quoted against it), so latest('RON') throws. For RON conversions use pair() — read on.

🔀 Currency pairs and cross rates

pair($from, $to, $validOn = null) returns the factor that converts an amount of $from into $to:

• With no date, it uses the rates valid today — exactly the same as passing today's date. (If you want the freshly communicated rate that becomes valid tomorrow, use latest().)
• With a date, both legs use the rate valid on that date (same walk-back as validOn()).
• ⚠️ Inverse and cross rates are returned at full float precision. (florianv/swap used to truncate inverses to 4 decimals — we don't. Round at display time, not in your data.)

📚 A whole day of rates in one call

Updating a rates table nightly? Don't make 30 requests:

The same works for any date — one lookup, every currency:

🕰️ Dates, timezones, and other sharp edges

• Any DateTimeInterface is accepted — DateTime, DateTimeImmutable, Carbon, CarbonImmutable — and is reduced to its calendar date (Y-m-d). No timezone conversion is performed: if you pass "2024-01-27" in any timezone, you get the rate for January 27.
• 🌙 Near midnight this matters: new DateTime('now') on a UTC server at 23:30 Romanian time is still "yesterday" in UTC. If the exact day is important, build your dates in Europe/Bucharest.
• 📜 Historical data starts at 2005 (that's as far back as BNR's yearly XML files go). Earlier dates throw UnsupportedDateException.
• 🔮 Future dates are refused, not guessed. The rate valid on a future day depends on a communication BNR hasn't made yet — silently answering with today's rate would give you a number that changes once BNR publishes. Anything beyond tomorrow throws RateNotYetAvailableException; tomorrow itself is answered as soon as today's ~13:00 communication is out.
• 🚷 validOn() gives up after 15 days of walking back (configurable) — with real BNR data that never happens; if it does, the feed is broken and you'll get a WalkBackExhaustedException instead of an infinite loop.

🚨 Error handling

Every runtime failure extends one base class (programmer errors — a negative retry count, a malformed date string — throw plain SPL \InvalidArgumentException/\LogicException, as usual):

Or catch precisely:

All exception properties are readonly — safe to log, impossible to mangle.

🔧 Advanced configuration

Everything is constructor-injected and optional:

Retries 🔁

Transient HTTP failures are retried automatically (default: 3 attempts, 200ms/400ms backoff). Tune it, give it a closure, or turn it off:

Only transport errors are retried — a malformed document will never be re-fetched in a loop.

The clock 🕐

The future-date guard needs to know what "today" is (Europe/Bucharest by default). For deterministic tests of code that uses the real client, inject one:

(For application tests you'll usually reach for FakeCursBnr instead — see below.)

Bring your own HTTP client 🌐

The default client is built on PHP streams and needs nothing installed. If you'd rather route through your existing stack, implement the one-method interface:

…or adapt any PSR-18 client (Guzzle shown; requires psr/http-client + a PSR-17 factory, which you likely already have):

Custom feed URLs 🧭

Point at a mirror, a proxy, or a test server:

🗄️ Caching (there isn't any — on purpose)

The package performs no caching: a rate for a past date never changes, but your app knows best how long to remember it and where. The only smartness inside is per-instance memoization of already-parsed yearly documents, so one walk-back over a weekend doesn't re-download the same file three times.

Wrapping it is a one-liner with whatever cache you already have (PSR-16 shown):

In a framework, register CursBnr\CursBnr as a singleton in your DI container and inject it — there's no service provider or bundle to install, and none is needed.

🧬 Data source & reliability notes

• Feeds: curs.bnr.ro/nbrfxrates.xml (daily) and curs.bnr.ro/files/xml/years/nbrfxrates{year}.xml (per year, 2005+), the official endpoints per BNR's documentation.
• The XML namespace is detected from the document, not hardcoded. BNR changed it from http://www.bnr.ro/xsd to https://www.bnr.ro/xsd in 2026 — silently breaking every parser that had it hardcoded (this package exists partly because of that day 🙃). Both variants are covered by tests.
• BOMs, redirects, and multiplier quirks are handled; garbage responses fail loudly with ParseException.

🧪 Testing your app

The package ships everything you need to test code that depends on exchange rates — no HTTP, no XML fixtures, no mocking library.

Step 1: depend on the interface

Type-hint CursBnr\ExchangeRates (not the concrete class) and bind the real client in your DI container:

Step 2: use the built-in fake in tests

CursBnr\Testing\FakeCursBnr is an in-memory ExchangeRates implementation. For most tests, constant mode is all you need — one timeless answer for any date:

Step 3: go date-aware when the calendar matters

Register specific communications and the fake behaves exactly like production — strictly-before validOn(), weekend/holiday walk-back, the works:

Step 4: test your error handling too

The fake throws the same typed exceptions as the real client, so your failure paths get real coverage instead of hand-waved mocks:

🔬 The fake cannot drift from the real client: both run the exact same internal semantics code (walk-back, future-date guard, 2005 floor) — and a parity test runs a full scenario through both anyway, asserting identical values and identical exceptions.

Testing the wiring itself

If you specifically want to exercise the real parser/HTTP pipeline (rarely needed), the lower-level seam is still there: implement the one-method HttpClientInterface returning canned XML and point FeedUrls at test URLs.

🧩 Wiring it into your framework

For plain unit tests you don't need a container at all — constructor-inject ExchangeRates and pass the fake directly:

The container binding matters for production wiring and for feature/integration tests, where your framework constructs the objects. Recipes:

Laravel

Symfony

Any PSR-11 container (PHP-DI, League, ...)

Alias CursBnr\ExchangeRates to a shared CursBnr\CursBnr instance; in tests, register FakeCursBnr under the same id before booting the code under test.

☝️ Whatever the framework: depend on ExchangeRates, never on CursBnr directly, and the production/test split stays a one-line binding.

📐 Versioning & backward compatibility

The package follows semver. The public API is everything under CursBnr\ except classes and methods marked @internal — those may change in any release. While on 0.x, breaking changes may land in minor versions and are always called out in the CHANGELOG; from 1.0 on, they only happen in major versions.

Security issues: see SECURITY.md — please report privately.

🤝 Development & AI transparency

This package is developed with AI assistance (Claude Code) — disclosure level ai-generated per the ai-disclosure convention; details in AI_DISCLOSURE.md. Every release is human-reviewed and gated by the full test suite (run against real BNR XML documents), PHPStan at level max, code style checks, and CI across all supported PHP versions. Issues and PRs are read by a human — me.

📄 License

MIT © Peter Lupu