dipeshsukhia/laravel-country-state-city-data
Laravel package that ships ready-to-use country, state, and city data with migrations, Eloquent models, and seeders. Add searchable location dropdowns and relational geography to your app quickly, without manually importing or maintaining large datasets.
Architecture fit. This is a reference-data package, not a behavior package. It contributes schema (countries/states/cities), Eloquent models, and a bulk seeder that populates lookup tables from bundled JSON/CSV. That makes it a clean fit for Laravel applications that need address forms, shipping-zone logic, geo-segmentation, or country/state validation — and a poor fit for anything that needs real geospatial capability (boundaries, lat/lng proximity search, postal codes, admin level 3+). The critical architectural decision is whether this data lives in your application database or in a separate reference store. For most monoliths and small services, in-app tables behind a thin repository interface are correct; the package should be the source of the data, not a runtime dependency your domain code imports directly.
Integration feasibility. Mechanically low-friction: composer require, publish config/migrations, run the seeder. The real work is in the seeder itself — a full city dataset is on the order of 150k rows, which means batched inserts, memory ceilings, and deploy-time execution risk. Verify the package's illuminate/* constraints against your Laravel version, whether data ships inside the package or is downloaded at seed time (offline/CI implications), and whether it defines foreign keys and indexes or leaves that to you. A half-day spike that seeds a real dataset and measures wall time and peak memory will answer most of this.
Technical risk. Three concerns dominate. First, data provenance and licensing: an MIT license on the PHP code does not automatically extend to the underlying dataset, which is likely derived from an upstream project (dr5hn, GeoNames, or similar) with its own attribution terms. This is the single most likely blocker and should be reviewed before adoption, not after. Second, bus factor: 81 stars and a single maintainer means limited community scrutiny of data defects and no guaranteed future. Third, data volatility: city renames, disputed territories, and transliteration differences make geographic data politically and legally sensitive in user-facing surfaces. Note the scoring tension here — a 9.6 utility score against 0.41 opportunity reflects a commodity capability that is genuinely useful but strategically undifferentiated; treat it as replaceable plumbing from day one.
Key questions. (1) What is the upstream data source, its license, and its attribution requirement? (2) Does the dataset include ISO 3166 codes, lat/lng, timezones, currencies, and translations, or only names? (3) Is the data versioned in lockstep with the package, and is a data-only refresh possible without a code upgrade? (4) Which Laravel/PHP versions are actually tested in CI? (5) Does the seeder truncate-and-reload or upsert, and is it safe to re-run? (6) How are diacritics and apostrophes stored and collated?
Stack fit. Suitable for Laravel 8–12-era applications on MySQL, PostgreSQL, or SQLite. It is the natural fit for a bounded set of use cases: cascading country→state→city selects, address normalization, country-based feature gating, and shipping/tax-zone rules. It is the wrong tool if you need city-level geocoding, autocomplete at scale, or multilingual place names — in that case pair it with a search index or choose a fuller competitor such as nnjeim/world.
Migration path. Do not let the package own your runtime schema. Publish its migrations once, then treat the resulting tables as your tables under your migration history — this freezes the shape and protects you from upstream schema changes. Wrap access in a small internal GeoRepository interface (country list, states by country, cities by state, reverse lookup by ISO code) with the package models as one implementation. That wrapper is the seam that lets you swap to a different dataset, a hosted API, or a self-curated import without touching controllers, form requests, or Blade views.
Compatibility. Watch three specifics: collation (city names with accents and apostrophes can behave inconsistently across MySQL and Postgres, and LIKE prefix search may miss expected matches), batch insert size (MySQL max_allowed_packet and Postgres placeholder limits both cap how large a seed chunk can be), and SQLite, which is fine for development but slow for a full 150k-row seed in CI — use a trimmed fixture dataset in the test suite.
Sequencing. (1) License and data-provenance review — gate everything else on this. (2) Spike branch: install, seed, measure rows, duration, and memory; confirm Laravel version support. (3) Data-shape audit: spot-check high-risk countries for completeness (states present, city coverage, encoding). (4) Introduce the repository interface and route all reads through it. (5) Add a caching layer for the country list and per-country state lists; index the lookup columns used by your forms. (6) Integrate into forms and validation rules. (7) Establish a refresh procedure — either a pinned lockfile plus periodic review, or a snapshot of the seed data committed to your own repository.
Maintenance. Low ongoing effort but non-zero governance. Pin the exact version, and strongly consider snapshotting the seed data into your own repository so a future upstream disappearance cannot break rebuilds or disaster recovery. Each upstream release is likely a wholesale data replacement, not a patch — plan a diff-and-refresh procedure rather than blind composer update. Because data changes can silently alter dropdown contents and validation outcomes, add a lightweight smoke test asserting expected row counts and a handful of known lookups.
Support. Community-only, no commercial backing, small issue volume. Internal ownership is required: someone on your team must be able to explain where the data came from, how to refresh it, and how to replace it. The repository abstraction is what makes that ownership cheap.
Scaling. Reference data is almost entirely read traffic and is trivially cacheable — full country lists and per-country state lists should live in Redis or the array cache with a long TTL. The city table is a few megabytes; it will not stress a modern database. The genuine scaling concern is query shape, not volume: typeahead over city names via LIKE '%term%' will not scale, so either restrict to prefix matching on an indexed column or route search to a dedicated index (Meilisearch/Elasticsearch). Also audit for N+1 patterns where a city list eager-loads its state and country per row.
Failure modes. Deploy-time seeder timeouts or memory exhaustion; partial seeding leaving referentially inconsistent rows; duplicate-key or slug-collision errors on re-run if the seeder lacks truncation or upsert semantics; missing coverage for countries that legitimately have no state-level division; stale data producing rejected addresses or outdated city names; disputed-territory entries creating political or legal exposure in some markets; encoding corruption surfacing as mojibake in user-facing forms.
Ramp-up. For a comfortable Laravel developer, roughly half a day to integrate and seed, and about one developer-week end-to-end including license review, the repository wrapper, caching, test fixtures, and a documented refresh process. The engineering is easy; the governance is the actual cost, and it is the part most teams skip.
How can I help you explore Laravel packages today?