README

SQL’siz, hazır JSON API ile Türkiye il → ilçe → mahalle → yol (cadde/sokak) zinciri. PHP 8+ için “composer require” sonrası anında kullanılır. Varsayılan veri kaynağı: https://mebularts.github.io/tr-adres-api (GitHub Pages).

Geliştirici: @mebularts

Öne Çıkanlar

⚡ Anında kullanım: SQL import yok; sadece composer require.
🌐 Ücretsiz statik JSON API (GitHub Pages) veya kendi host’unuz için base URL override.
🧠 Akıllı cache (30 gün varsayılan) + hafif HTTP istemcisi; title/upper case desteği.
🧩 Facade ile tek satırda iller, ilceler, mahalleler, yollarByIlce.
🛠 CLI: ping, cache temizleme, örnek API kopyalama.
🧪 PHPUnit testleri, checkout demo (il → ilçe → mahalle → yol dropdown zinciri).

Kurulum

composer require mebularts/tr-adres

Hızlı Kullanım

use Mebularts\TrAdres\TrAdres;

$tr = TrAdres::auto(); // TR_ADRES_BASE_URL varsa onu, yoksa varsayılan GitHub Pages'i kullanır

$iller        = $tr->iller();                  // [{id, ad, plaka}]
$ilceler      = $tr->ilceler(34);              // [{id, il_id, ad}]
$mahalleler   = $tr->mahalleler(3401);         // [{id, il_id, ilce_id, ad}]
$yollar       = $tr->yollarByIlce(3401);       // [{id, il_id, ilce_id, mahalle_id, ad, tip}]
$yollarFiltre = $tr->yollarByIlce(3401, 340101);

// Üst metin seçeneği (TR İ/ı kurallı)
$illerUpper = $tr->iller('upper');

Çevre Değişkenleri

TR_ADRES_BASE_URL: Statik JSON API kökü. Varsayılan: https://mebularts.github.io/tr-adres-api
TR_ADRES_CACHE_DIR: Cache dizini. Varsayılan: sys_get_temp_dir()/tr-adres-cache
TR_ADRES_CACHE_TTL_DAYS: Cache ömrü (gün). Varsayılan: 30

Checkout Demo

Tam çalışan örnek examples/checkout içinde:

php -S 127.0.0.1:8000 -t examples/checkout/public

examples/checkout/public/index.php — form + dropdown zinciri
examples/checkout/public/api.php — op=iller|ilceler|mahalleler|yollar JSON endpoint’i
JS/CSS: examples/checkout/public/assets/

Sayfa açılınca iller yüklenir; il seçimi ilçe listesini, ilçe seçimi mahalle + yolları getirir. Mahalle seçilirse yollar mahalleye göre filtrelenir. Form POST edildiğinde il_id, ilce_id, mahalle_id, yol_id ekranda gösterilir.

API ve Self-Host

Varsayılan API: https://mebularts.github.io/tr-adres-api
Kendi sunucunuz: mebularts/tr-adres-api reposundaki docs/v1 klasörünü kopyalayın; TR_ADRES_BASE_URL değerini kendi URL’inizle değiştirin.
CLI ile örnek kopya: php bin/tr-adres publish:api --to=/var/www/html/tr-adres (bu repo içindeki küçük örnek veri içindir; tam veri için tr-adres-api kullanın).

CLI

tr-adres help
tr-adres api:ping [--base-url=...]
tr-adres cache:clear
tr-adres publish:api --to=PATH [--from=PATH]

API Formatı (v1)

/v1/meta.json
/v1/iller.json
/v1/ilceler/by-il/{IL_ID}.json
/v1/mahalleler/by-ilce/{ILCE_ID}.json
/v1/yollar/by-ilce/{ILCE_ID}.json (isteğe bağlı mahalle_id filtresi)

yol = cadde/sokak/bulvar vb. üst başlık. API kanonik olarak titlecase döner; kütüphane case='upper' ile TR uyumlu üst metin üretebilir.

SQL Dump → Statik JSON Üretimi

Büyük SQL dump’lardan statik API oluşturmak için:

python tools/generate_api.py ^
  --titlecase D:\path\titlecase_data.sql ^
  --uppercase D:\path\uppercase_data.sql ^
  --out docs/v1

SQL yolları argümanla verilir, hardcode yok.
Stream okuma, NDJSON ara dosyaları, id bazlı dedup (titlecase öncelikli).
Çıktılar: meta.json, iller.json, ilceler/by-il/*.json, mahalleler/by-ilce/*.json, yollar/by-ilce/*.json.
Tam veri yayını için ayrı repo: mebularts/tr-adres-api (docs/ GitHub Pages kaynağı). Bu paketteki docs/v1 küçük örnek veri içerir.

Test ve Kalite

composer install
composer test

Testler:

Türkçe upper normalizasyonu (İ/ı)
Remote repository cache davranışı (HTTP mock)
Facade uç noktalarının doğru bağlanması ve mahalle filtresi

İletişim

Telegram: t.me/mebularts
WhatsApp: wa.me/12513160268

Lisans

MIT — bkz. LICENSE

mebularts / tr-adres

Maintainers

Details