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 dump’lar 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 API’den okuyan istemci kütüphanesi.
• Varsayılan veri kaynağı: GitHub Pages üzerinde statik JSON API.
• İsterseniz kendi sunucunuza taşıyıp base URL’i 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 dump’lardan statik API üretmek için araçlar

Kurulum (Composer)

composer require mebularts/tr-adres

PHP 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. Local’de ç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 ID’leri ekranda gösterir


Self-Host (Kendi Sunucunda Kullan)
Varsayılan API yerine kendi host ettiğin statik JSON’u kullanmak için:

• Statik JSON klasörünü sunucuna koy
• Base URL’i ortam değişkeniyle değiştir

Ortam Değişkenleri:

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-api

CLI 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)

Not: “yol” = cadde/sokak/bulvar vb. üst başlık.

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.