Download the PHP package oguzhanbayirli/laravel-turkiye without Composer

laravel-turkiye

Validation rules for Turkish identity numbers (TCKN), tax numbers (VKN) and IBANs, amounts written out in Turkish words for invoices, and a client for the daily exchange rates published by the Central Bank of the Republic of Türkiye (TCMB). Works with Laravel 12 on PHP 8.2+ and Laravel 13 on PHP 8.3+. Laravel 11 is left out because it no longer gets security fixes and Composer refuses to install it by default.

Türkçe README

Why another package

For years epigra/tckimlik was the usual way to check a TCKN in Laravel. It is archived now. According to the NVI notice quoted in its README, NVI's free public verification service (KPSPublic) was scheduled to close on 30 September 2025; checking a number against the population register now requires KPS membership. The offline check is still what most forms need, so this package does that, along with the other small Turkey-specific chores that keep coming up in invoicing code: VKN and IBAN checks, "Yalnız ... TL" lines and TCMB rates. Every part also works as a plain PHP class if you are not inside a Laravel request.

Installation

The service provider is discovered automatically. To change the TCMB settings or the validation messages, publish them:

Validation

Four rules are registered, each available as a string and as a rule object:

Messages ship in Turkish and English and follow the app locale:

If your own lang/{locale}/validation.php has a tckn, vkn, tckn_or_vkn or tr_iban line, that one wins.

Outside of the validator:

What these checks do not tell you

All three checks are offline arithmetic. A TCKN that passes has the right shape and check digits; it does not mean a person with that number exists, or that the name typed next to it matches. The same goes for VKN and IBAN: the account may be closed, or belong to someone else. When that matters, ask the bank or GİB.

Amounts in words

Numbers follow TDK spelling: "bin" never becomes "bir bin" and "yüz" never becomes "bir yüz". Plain text keeps the words apart; the invoice preset joins them, as TDK prescribes for amounts on commercial documents. Capitalisation follows common invoice practice, with the dotted capital İ.

Presets can be adjusted:

Without the facade: (new \OguzhanBayirli\Turkiye\Words\AmountInWords)->convert(...). NumberToWords::spell(1234) gives the bare number, "bin iki yüz otuz dört".

Some details:

• Pass amounts as strings when every kuruş matters. "1234.56" is also what Laravel's decimal:2 cast returns. Floats work but are rounded through number_format, so the usual float surprises apply.
• Input uses a dot for decimals and no thousands separator. "1.234,56" is rejected with an InvalidArgumentException instead of being guessed at.
• Rounding is half away from zero at the second decimal: 10.005 is "On Türk Lirası Bir Kuruş", 999.995 is "Bin Türk Lirası".
• 0 is "Sıfır Türk Lirası", 0.50 is "Elli Kuruş", negatives start with "Eksi".
• Strings can go well past PHP_INT_MAX; the largest scale is desilyon (10^33).

TCMB exchange rates

Each Rate has forexBuying, forexSelling, banknoteBuying, banknoteSelling and crossRateUsd, all ?float. A price is null when the bulletin leaves it empty, which happens for SDR (XDR) banknote rates.

How it behaves:

• today() reads today.xml. TCMB publishes around 15:30 Istanbul time, so before that you get the previous working day's bulletin. Check $sheet->date rather than assuming.
• on($date) reads YYYYMM/DDMMYYYY.xml. Weekends and holidays have no file (TCMB answers 404), so it steps back one day at a time, up to max_lookback_days (10 by default, enough for a long bayram).
• Responses are cached through Laravel's cache. today.xml for 10 minutes, archived bulletins for 30 days. Past days without a bulletin are remembered too, so a weekend lookup does not repeat its 404s.
• Network problems, timeouts, non-404 HTTP errors and unreadable XML throw OguzhanBayirli\Turkiye\Tcmb\TcmbException. A 500 on Monday is not quietly replaced by Friday's rates.
• Future dates throw InvalidArgumentException without making a request.

Configuration, after publishing config/turkiye.php:

In your own tests, fake the HTTP client as usual:

These are TCMB's indicative rates. Which date and which of the four prices apply to a given invoice is a question for your accountant; the package only fetches them.

Testing

The test suite never touches the network. The TCMB tests replay real bulletins saved under tests/Fixtures.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.