World Laravel Package

Product Decisions This Supports

• International address capture (build vs. buy): Gives a Laravel app a ready-made Country → State → City relational dataset and Eloquent models, so a cascading address form can ship in days without a paid geocoding/places API or a hand-assembled dataset. This is the primary decision it de-risks.
• Market expansion sequencing: The presence and quality of state/city coverage in a given country directly determines whether we can support state-level tax rules, shipping zones, or territory assignment there. Auditing coverage per market becomes an input to which market we launch next, not just how we render a dropdown.
• Owned data vs. API dependency: Committing a snapshot to our own database is a real architectural/product stance — no per-lookup cost, no vendor lock-in, offline/air-gapped capability, deterministic fixtures for tests. This package makes that stance cheap to evaluate.
• Feature areas it unlocks cheaply: shipping zones, US-state/CA-province tax jurisdiction mapping (as a lookup, not a tax engine), localization defaults (currency/locale by country), KYC and billing country lists, B2B territory/segment assignment, and analytics geo segmentation.
• Buy-vs-build for adjacent needs: It clarifies scope boundaries — list selection is solved; address validation, postal-code verification, geocoding, coordinates, and fuzzy autocomplete are explicitly not solved and still require a vendor.
• Time-to-spike: A PM can get a working prototype of a geo-dependent feature in a single sprint, which is often enough to validate demand before committing to a first-party dataset or a paid API contract.

When to Consider This Package

Adopt when:

• You're on Laravel/Eloquent and genuinely need the full country → state → city chain, not just a country list.
• Your flows are select from a list. No validation, no fuzzy matching, no reverse geocoding required.
• Your priority markets (typically US/CA/EU) are well covered and you can spot-check quality before launch.
• You can own a refresh cadence — a quarterly re-seed or data-diff job — and are willing to fork/vendor the seed data rather than depend on upstream maintenance.
• You need deterministic, offline-capable data for CI, tests, or regulated/on-prem deployments.
• License is acceptable: MIT for the code, but verify the provenance and license of the seed data itself (GeoNames-derived data is CC-BY and carries attribution obligations).

Look elsewhere when:

• You only need country names and ISO codes — a config array or symfony/intl is far cheaper than migrating and seeding a six-figure city table.
• You need address validation, postal codes, coordinates, autocomplete, or geocoding — use Google Places, Mapbox, Algolia Places, Lob, or Smarty.
• You need authoritative tax or shipping calculations — that's Avalara/Stripe Tax/TaxJar territory, not a geo list.
• You need localized place names, administrative levels beyond a single state tier, or dependable coverage in emerging markets.
• Your deploy pipeline can't absorb a large one-time seed (CI runtime, DB size, rollback story).
• Maintenance risk is unacceptable: ~480 stars but 0 dependent packages means very little production validation in the ecosystem, and likely a single-maintainer project. If you adopt, plan to own it.

How to Pitch It (Stakeholders)

For executives: This is a free, MIT-licensed drop-in that supplies countries, states, and cities as database tables and relationships inside our existing Laravel app. It lets us ship international address entry and market-specific rules in days rather than weeks, with no license fee and no per-lookup API cost. Two caveats keep this a speed decision rather than a platform decision: the data is a static snapshot that ages, and the project is small — one maintainer, no dependent packages. We mitigate by vendoring a fork, scheduling refreshes, and restricting its use to selection lists — never as the system of record for tax or shipping rates. Recommendation: adopt now as an accelerator, gate broader rollout on a data-quality audit of our top three markets plus a documented refresh and attribution plan.

For engineering: composer require, publish migrations, seed. You get Country, State, City models with relations. Trade-offs to plan for: a large seed step in the deploy path, static data with no upstream guarantee of freshness, and no postal codes, coordinates, or validation. Please pin the version, snapshot the seed data under our control, put a refresh job and attribution notice in place, and keep the models behind our own domain interface so swapping to a first-party dataset or a places API later is a one-adapter change rather than a refactor.