TL;DR (EN): A PHP 8+ package to use Turkey address data (province→district→neighborhood→road) via a static JSON API + smart cache — no SQL dumps.
TL;DR (TR): Türkiye adres verisini (il→ilçe→mahalle→yol) statik JSON API + cache ile SQL import olmadan kullanın.
Links:
- GitHub: https://github.com/mebularts/tr-adres
- Packagist: https://packagist.org/packages/mebularts/tr-adres
English
If you have ever built a checkout/profile form for Turkish users, you know the usual pain:
- Province (il) → District (ilçe) → Neighborhood (mahalle) → Road (cadde/sokak/bulvar)
- Huge SQL dumps
- Slow imports and deployment friction
TR Adres is a lightweight PHP 8+ client that consumes a static JSON API (GitHub Pages by default) and adds smart caching — so you can ship an address selector without importing a database.
Highlights
- No SQL import (Composer install and go)
- Default data source: GitHub Pages static JSON API
- Base URL override for self-hosting
- Smart cache (default TTL: 30 days)
- Turkish-aware case conversion (İ/ı rules)
- Simple methods:
iller,ilceler,mahalleler,yollarByIlce - CLI helpers (ping, cache clear, publish sample API)
- Checkout demo included
Install
composer require mebularts/tr-adres
Requires: PHP 8.0+
Quick usage
<?php
require __DIR__ . '/vendor/autoload.php';
use Mebularts\TrAdres\TrAdres;
$tr = TrAdres::auto(); // if TR_ADRES_BASE_URL exists, uses it; otherwise uses default API
$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}]
// Optional: filter roads by neighborhood
$yollarFiltre = $tr->yollarByIlce(3401, 340101);
// Turkish uppercase (İ/ı aware)
$illerUpper = $tr->iller('upper');
Checkout demo (dropdown chain)
php -S 127.0.0.1:8000 -t examples/checkout/public
Flow:
- loads provinces on page load
- selecting province loads districts
- selecting district loads neighborhoods + roads
- selecting neighborhood filters roads
Environment variables
TR_ADRES_BASE_URL=...
TR_ADRES_CACHE_DIR=...
TR_ADRES_CACHE_TTL_DAYS=30
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 (optional mahalle_id filter)
If you try it, feedback and PRs are welcome.
Türkçe
Türkiye odaklı bir checkout / üyelik / adres formu yaptıysanız şu akışın zorluklarını bilirsiniz:
- İl → İlçe → Mahalle → Yol (cadde/sokak/bulvar)
- Büyük SQL dump’lar
- Kurulum/taşıma sırasında import süresi ve hata riski
TR Adres, PHP 8+ uyumlu; varsayılan olarak GitHub Pages statik JSON API üzerinden veriyi çeken ve akıllı cache ekleyen hafif bir istemcidir. Böylece adres seçimi için DB import etmek zorunda kalmazsınız.
Öne çıkanlar
- SQL import yok (Composer ile kur, kullan)
- Varsayılan kaynak: GitHub Pages statik JSON API
- Self-host için base URL override
- Akıllı cache (varsayılan TTL: 30 gün)
- Türkçe İ/ı kurallarına uygun upper/title desteği
- Basit metodlar:
iller,ilceler,mahalleler,yollarByIlce - CLI (ping, cache temizle, örnek API publish)
- Checkout demo hazır
Kurulum
composer require mebularts/tr-adres
Gereksinim: PHP 8.0+
Hızlı kullanım
<?php
require __DIR__ . '/vendor/autoload.php';
use Mebularts\TrAdres\TrAdres;
$tr = TrAdres::auto();
$iller = $tr->iller();
$ilceler = $tr->ilceler(34);
$mahalleler = $tr->mahalleler(3401);
$yollar = $tr->yollarByIlce(3401);
Checkout demo
php -S 127.0.0.1:8000 -t examples/checkout/public
Çevre değişkenleri
TR_ADRES_BASE_URL=...
TR_ADRES_CACHE_DIR=...
TR_ADRES_CACHE_TTL_DAYS=30
Deneyen olursa yorum/geri bildirim ve PR’lara açığım.
Top comments (0)