TR Adres (PHP) SQL İçe Aktarmadan İl / İlçe / Mahalle / Cadde-Sokak (Yol) Verisi
Statik JSON API + akıllı cache + checkout (adres seçimi) demo
Statik JSON API + akıllı cache + checkout (adres seçimi) demo
Merhaba,
PHP projelerinde adres seçimi (checkout / form / CRM / kargo vb.) ekranlarında Türkiye il → ilçe → mahalle → yol (cadde/sokak/bulvar) zincirini kurmak için genelde büyük SQL dumplar import etmek gerekiyor.
Bu projede amaç: SQL ile uğraşmadan Composer ile paketi kurup, hazır statik JSON API üzerinden veriyi çekmek ve cache ile performanslı kullanmak.
Nedir?
mebularts/tr-adres: PHP 8+ uyumlu, Türkiye adres hiyerarşisini statik JSON APIden okuyan istemci kütüphanesi.
Varsayılan veri kaynağı: GitHub Pages üzerinde statik JSON API.
İsterseniz kendi sunucunuza taşıyıp base URLi değiştirebiliyorsunuz.
Neden Kullanmalıyım?
- SQL import yok: hosting taşınırken / kurulumda dump derdi yok.
- Hızlı entegrasyon: tek komutla kurulum, birkaç satırla kullanım.
- Akıllı cache: aynı veriyi sürekli indirmez (varsayılan 30 gün TTL).
- Checkout hazır: il/ilçe/mahalle/yol dropdown zinciri çalışan demo var.
- Self-host opsiyonu: benim verim benim sunucumda kalsın diyene uygun.
- TR uyumlu metin dönüşümü: Türkçe İ/ı kurallarına uygun upper/title desteği.
- MIT Lisans: ücretsiz, açık ve ticari projelerde kullanılabilir.
Öne Çıkan Özellikler
Facade ile tek satırda: iller, ilceler, mahalleler, yollarByIlce
CLI komutları: ping, cache temizleme, örnek API publish
PHPUnit testleri + HTTP mock (cache davranışı testli)
Büyük SQL dumplardan statik API üretmek için araçlar
Kurulum (Composer)
composer require mebularts/tr-adresPHP Gereksinimi: PHP 8.0+
Hızlı Kullanım
<?php
require __DIR__ . '/vendor/autoload.php';
use MebulartsTrAdresTrAdres;
$tr = TrAdres::auto(); // TR_ADRES_BASE_URL varsa onu, yoksa varsayılan API'yi 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}]
// Mahalleye göre yol filtresi:
$yollarFiltre = $tr->yollarByIlce(3401, 340101);
// Türkçe upper (İ/ı uyumlu):
$illerUpper = $tr->iller('upper');
print_r($iller[0]);Checkout Demo (Adres Seçimi Hazır Örnek)Repo içinde tam çalışan örnek mevcut. Localde çalıştırmak için:
php -S 127.0.0.1:8000 -t examples/checkout/public Sayfa açılınca iller yüklenir
İl seçince ilçe gelir
İlçe seçince mahalle + yollar gelir
Mahalle seçilirse yollar mahalleye göre filtrelenir
Form submit olunca seçilen IDleri ekranda gösterir
Self-Host (Kendi Sunucunda Kullan)
Varsayılan API yerine kendi host ettiğin statik JSONu kullanmak için:
- Statik JSON klasörünü sunucuna koy
- Base URLi ortam değişkeniyle değiştir
TR_ADRES_BASE_URL=... TR_ADRES_CACHE_DIR=... TR_ADRES_CACHE_TTL_DAYS=30Örnek:
// Apache/Nginx env veya .env üzerinden: TR_ADRES_BASE_URL=https://seninsiteadresin.com/tr-adres-apiCLI Komutları
# (Genelde vendor/bin üzerinden çalıştırılır) 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 (opsiyonel mahalle_id filtresi)
Kullanım Alanları
- E-ticaret checkout adres seçimi
- Kargo / fatura / sipariş formları
- CRM & saha satış uygulamaları
- Üyelik formları (adres doğrulama / standartlaştırma)
- Panel / admin tarafında adres filtreleme
GitHub & Packagist
- GitHub: https://github.com/mebularts/tr-adres
- Packagist: https://packagist.org/packages/mebularts/tr-adres
Lisans
MIT
İletişim
Telegram: https://t.me/mebularts
Görüş/öneri/PR her türlü katkıya açığım.
Konuyu beğenirseniz yıldız atmanız motivasyon olur.
