# Tanzania Locations

Offline Tanzania location data — **Region → District → Ward → Postcode** — as a
framework-agnostic Composer package. No database required.

- 30 regions (incl. the 4 operational **Verification Regions**), 147 districts,
  ~4,060 wards with postcodes
- Clean PHP API: `regions()`, `districts()`, `wards()`, `postcodes()`, `search()`,
  `isValidHierarchy()`
- Cascading dropdowns out of the box (`assets/tz-cascade.js`) — client-side or AJAX
- Optional FK-linked SQL export (`dist/schema.sql`) for projects that want DB tables
- Safe update workflow: `php bin/add.php …` → commit → `composer update` everywhere

```php
$tz = new TanzaniaLocations\TanzaniaLocations();
$tz->districts('dar-es-salaam');   // → Ilala, Kigamboni, Kinondoni, Temeke, Ubungo
```

**Full guide with Laravel and CodeIgniter examples: [USAGE.md](USAGE.md).**

Try the demo:

```bash
php -S localhost:8080 -t examples
# open http://localhost:8080/index.php
```

Run the tests:

```bash
php tests/run-tests.php
```

## Layout

```
data/locations.json   ← THE source of truth (edit via bin/add.php or by hand)
dist/                 ← generated: locations.php, locations.min.json, schema.sql
src/                  ← TanzaniaLocations, AjaxHandler, SqlExporter
assets/tz-cascade.js  ← cascading dropdown helper
bin/                  ← add.php (add records), build.php (validate + regenerate),
                        migrate-legacy.php (one-time import from the old SQL dump)
```

After any data change: `php bin/build.php` (add.php runs it for you).