Trgeozones Laravel Package

Product Decisions This Supports

Market entry and localization for Türkiye. Any roadmap item that touches Turkish users — signup, checkout, KYC, seller onboarding, field-service dispatch — requires canonical il / ilçe / semt / mahalle / posta kodu data. This package is the reference-data layer behind that decision, and choosing it (or not) is effectively a decision about when the TR market becomes addressable.

Build vs. buy for reference data. The alternative is owning a Turkish address dataset in-house: sourcing it, seeding it, and re-sourcing it every time administrative boundaries change (büyükşehir law reorganizations, new districts, mahalle mergers). Acquiring a maintained MIT-licensed dataset replaces an ongoing data-ops chore with a dependency. This is the core trade: a small amount of vendor risk in exchange for zero data-curation headcount.

Checkout and onboarding conversion. Cascading province → district → neighborhood → postal code selects reduce free-text address entry, which is the single largest driver of failed deliveries and manual address-correction tickets in TR e-commerce. This supports the decision to ship structured address capture rather than a textarea, and to measure address-related support contacts as a KPI.

Downstream integration readiness. Turkish carriers (Yurtiçi, Aras, MNG, Sürat, Trendyol/Hepsiburada fulfillment) and e-invoice/e-arşiv flows expect discrete, coded address fields, not free text. Adopting a coded taxonomy now determines whether logistics and invoicing integrations are a config task or a migration later.

Delivery-cost and returns modelling. Province/district granularity is the minimum viable unit for shipping-zone pricing, COD availability, and returns routing. Having it in your own database — rather than behind a third-party geocoding API — makes it joinable to orders and warehouses for margin analysis.

Data governance and KVKK posture. Storing an address as a set of codes plus a normalized street line is easier to justify under data-minimization principles than storing scraped free-text addresses. It also makes retention and anonymization policies tractable, since the reference tables contain no personal data.

Roadmap pattern for other emerging markets. If TR succeeds, the same shape (bundled, seeded, code-based administrative divisions) becomes the template for MENA, LATAM, and SEA expansion. Evaluating this package is partly an evaluation of that reusable architecture.

When to Consider This Package

Adopt when:

• The stack is Laravel/PHP 8+ (or you're willing to port the seeders/models), and you want reference data as Eloquent models and migrations rather than an API contract.
• You need offline, low-latency, dependency-free lookups. Address dropdowns fire on every keystroke in onboarding; a network round-trip per cascade step is a real UX and cost tax, and an external provider outage shouldn't take down checkout.
• Coverage requirements are administrative hierarchies only — you need the list, not validation, geocoding, or parsing.
• Your address data changes at administrative-boundary cadence (months/years), not at postal-route cadence (continuous). A snapshot is acceptable if it's refreshed on a schedule you control.
• You're comfortable owning the update path: a scheduled re-seed on package upgrades, or a fork you maintain.

Look elsewhere when:

• You are not on Laravel/PHP, or you need a language-agnostic service boundary — consume an address API or a portable dataset instead.
• You need real-time validation, geocoding, or autocomplete — turning a partial string into a verified, rooftop-level address is a different product (Google Places, Mapbox, Loqate, or a Turkish specialist such as Başarsoft/HERE). This package will not verify that a mahalle exists at a given street number.
• You need international addresses. Adopting a TR-only schema as your primary address model creates a schema migration later; consider a global i18n address model with TR data as one country provider.
• Your compliance or contractual bar requires first-party official sources (PTT/TÜİK feeds) with provenance and SLA, not a community snapshot.
• You need free-text address parsing/normalization of legacy or user-pasted addresses.

Due diligence before committing (this package carries real signals):

The adoption profile is thin — 91 stars, zero dependents on record, and a low maintenance score — while the opportunity score is high (8.23). That combination usually means real unmet need, under-adopted solution: either a discoverability gap, or a package that hasn't been hardened by production users. Verify directly: last commit and release cadence, Laravel/PHP version support in composer.json, open issues touching data accuracy, whether seeders are current with recent boundary changes, and whether tests cover the hierarchy relations. Treat the dataset's staleness date as a first-class risk, since it is the one thing that silently degrades (bad dropdown options → bad addresses → failed deliveries) rather than failing loudly.

Mitigation regardless: wrap it behind a thin internal AddressRepository/AddressService interface so the package is swappable for a commercial provider or your own tables without touching feature code, and cache the hierarchy at the edge or in Redis since it is read-mostly and effectively static.

How to Pitch It (Stakeholders)

For executives. Entering or scaling in Türkiye requires structured Turkish address data in every flow that touches a customer or a parcel. This is a free (MIT), drop-in component for our existing PHP/Laravel stack that supplies the country's province, district, neighborhood, and postal-code hierarchy. The business case is speed and cost avoidance: it lets us ship TR address capture in days instead of funding a data-sourcing workstream, and it directly reduces the two expensive failure modes in that market — abandoned checkouts caused by clumsy address forms, and re-delivery costs from undeliverable parcels. There is no license fee and no per-lookup API charge. The honest caveat is counterparty risk: it's a small, lightly-adopted open-source project. We mitigate that by keeping it behind an internal interface, budgeting a small amount of engineering to fork and maintain the dataset if upstream goes quiet, and refreshing the data on a scheduled basis. Net: low cost, low lock-in, credible time-to-market gain; recommend a one-sprint spike to validate data currency before we commit it to the checkout roadmap.

For engineering. It's a Laravel package that ships migrations, seeders, and Eloquent models for the TR administrative hierarchy, so we get queryable local tables instead of an external service — no per-request latency, no API quota, no runtime third-party dependency for a read-mostly dataset. Please evaluate three things before we adopt: (1) composer.json constraint and actual compatibility with our Laravel/PHP versions plus test coverage on the relations; (2) how current the seeded data is and how we'd refresh it on boundary changes — assume we own a scheduled re-seed; (3) whether the schema generalizes, because if international expansion is on the roadmap we want TR as a country-specific provider behind a neutral address model rather than the address model itself. Implementation expectation: wrap access behind an internal repository interface, cache the hierarchy, and treat the package as a replaceable data source — we should be able to swap to a commercial provider or our own tables without changing feature code.