PHPackages                             mebularts/tr-adres - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. mebularts/tr-adres

ActiveLibrary[API Development](/categories/api)

mebularts/tr-adres
==================

Turkiye il/ilce/mahalle/yol verisi icin SQL'siz PHP istemcisi (statik JSON API)

10PHP

Since Jan 11Pushed 5mo agoCompare

[ Source](https://github.com/mebularts/tr-adres)[ Packagist](https://packagist.org/packages/mebularts/tr-adres)[ RSS](/packages/mebularts-tr-adres/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

mebularts/tr-adres
==================

[](#mebulartstr-adres)

[![Packagist](https://camo.githubusercontent.com/33ced8b1e3a924040db7f0859b93b555d921af88adc5f6559d9d80633948f46a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6562756c617274732f74722d61647265733f636f6c6f723d306639643538266c6162656c3d5061636b6167697374)](https://packagist.org/packages/mebularts/tr-adres)[![PHP](https://camo.githubusercontent.com/47ee5b1af27a2d01af8923f86c27b8fd2b987bb9cfeb540f388c3406737097db/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d2533453d382e302d3737376262343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](#)[![Tests](https://camo.githubusercontent.com/7a054d47599e3cfbeed4b621153895ecab87ef2fb61bfea14b66ed6b31feab12/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d706870756e69742d677265656e)](#)[![Pages](https://camo.githubusercontent.com/1e707731526541806814cd4d846d1a9ff75e02e0f09190eb9a116e39a4f40dfa/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4150492d47697448756225323050616765732d3234323932663f6c6f676f3d676974687562)](https://mebularts.github.io/tr-adres-api/)[![License](https://camo.githubusercontent.com/05b1a2cc783a0f717ec85aee0225e9bf500976660437de294ad9c18cade76d7b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d303030)](LICENSE)[![Telegram](https://camo.githubusercontent.com/9edbb612ff2d8ca888c61ecdb8e11ded28bc7a2d38f09826e98258f0e57de1e7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f54656c656772616d2d406d6562756c617274732d3030396666663f6c6f676f3d74656c656772616d266c6f676f436f6c6f723d7768697465)](https://t.me/mebularts)[![WhatsApp](https://camo.githubusercontent.com/106a67a3911d7c89cb376f13c28caad3d1ef8448ee7a51f24d81c69c39621baf/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f57686174734170702d436861742d3235443336363f6c6f676f3d7768617473617070266c6f676f436f6c6f723d7768697465)](https://wa.me/12513160268)

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

[](#ö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
-------

[](#kurulum)

```
composer require mebularts/tr-adres
```

Hızlı Kullanım
--------------

[](#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

[](#ç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
-------------

[](#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
----------------

[](#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
---

[](#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)
----------------

[](#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
------------------------------

[](#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
--------------

[](#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
--------

[](#i̇letişim)

- Telegram: [t.me/mebularts](https://t.me/mebularts)
- WhatsApp: [wa.me/12513160268](https://wa.me/12513160268)

Lisans
------

[](#lisans)

MIT — bkz. `LICENSE`

###  Health Score

17

—

LowBetter than 6% of packages

Maintenance48

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/113755353?v=4)[Mehmet Bulat](/maintainers/mebularts)[@mebularts](https://github.com/mebularts)

---

Top Contributors

[![mebularts](https://avatars.githubusercontent.com/u/113755353?v=4)](https://github.com/mebularts "mebularts (4 commits)")

### Embed Badge

![Health badge](/badges/mebularts-tr-adres/health.svg)

```
[![Health](https://phpackages.com/badges/mebularts-tr-adres/health.svg)](https://phpackages.com/packages/mebularts-tr-adres)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35916.4M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24016.2M20](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172445.0k15](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

93459.5k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)