Laravel Cities Laravel Package

Product Decisions This Supports

• Location input as a shared primitive. Whether the roadmap item is flight/hotel search, store pickup, shipping quotes, regional pricing, or user profiles, the package gives one consistent answer to "what is a city?" — IATA city code plus ISO 3166-1 country code — returned as readonly City objects via find, findOrFail, exists, inCountry, search, and options. That means one lookup contract across web, API, and admin tooling instead of three homegrown lists.
• Search and autocomplete UX. search()/options() back a typeahead or country→city dependent dropdown without standing up a search service. This is the cheapest way to ship a "pick your origin/destination" or "select your region" flow, and it removes free-text location entry — the single largest source of dirty location data in analytics and CRM.
• Input validation and data hygiene. The bundled CityCode validation rule lets product enforce "is this a valid city code?" at the form and API boundary. That directly improves the reliability of downstream segmentation, routing logic, and reporting, and reduces support tickets caused by typos like LHR vs LHR or "London" vs "LON".
• Build vs. buy: buy. The engineering cost here is mostly data curation and validation wiring, not code. Acquiring a maintained, MIT-licensed dataset with a Laravel-native access layer and a test suite is materially cheaper than assembling and QA-ing our own reference table.
• Roadmap sequencing: useful as an enabler for an MVP or a scoped feature rather than a platform bet. It is small enough to adopt in a sprint and abstracted enough to replace later — so it de-risks "we need location data" without committing the team to an owned geo dataset.
• Not a geospatial decision. This is a code standardization capability, not a mapping capability. Do not let it be scoped into any roadmap item that implies coordinates, distance, delivery radius, or map rendering — those need a geocoding provider.

When to Consider This Package

Consider it when:

• The product's location concept is city/metro-level and IATA codes are a legitimate identifier for your domain (travel search, airline/rail booking, corporate travel, logistics lane definitions, regional availability).
• You want zero runtime dependency on an external geo API — no per-call cost, no third-party latency or rate limits in a critical path such as checkout or booking.
• Your stack is Laravel on PHP 8.2+ (Laravel 12/13). The v1.0.0 rewrite targets exactly this, with package auto-discovery, an optional Eloquent model/migration/idempotent seeder, and CI — so the old "Laravel 5, dev-master, abandoned" objection no longer applies.
• You need a validation rule more than a database. The in-memory lookup means you can ship without a migration at all.
• Your team is small and would otherwise spend a sprint building a reference table.

Look elsewhere or build when:

• You need airport-level codes rather than city-level. IATA city codes are metro codes (NYC, LON); if the feature is "which terminal/airport," you need an airport dataset (e.g., OurAirports/OpenFlights) — this is a real and common mismatch worth resolving before commitment.
• You need global city coverage. IATA city codes only exist for commercially significant cities. Address entry, shipping to arbitrary towns, or onboarding users anywhere in the world will require a broader dataset (GeoNames-class) or a geocoder.
• You need coordinates, timezones, population, admin hierarchy, or localized/native-language names. None of these are in scope; diacritics and non-Latin scripts are unverified and should be tested against your target markets.
• You need a commercial SLA or freshness guarantee on code changes (airline codes do change). A static, release-driven dataset cannot promise that.
• You're not on Laravel — the underlying data is portable, but you'd be adopting the data, not the package.

Adoption risk to price in: 11 stars, 0 known dependents, effectively a single maintainer, and "readme"-level maturity metadata. Mitigate by confining the dependency behind a thin internal interface (e.g., our own CityLookup contract wrapping the facade) so a swap or a vendored fork of the dataset is a contained change, and by pinning the version.

How to Pitch It (Stakeholders)

For executives: We can standardize location input across the product in days, not a quarter. This package gives us a curated list of city codes with country codes, a validation rule, and a Laravel-native lookup — MIT-licensed, no API fees, no third-party latency in checkout or search, and no new vendor contract. It's a small, replaceable component: we adopt it behind our own interface, so it accelerates the feature without locking us in. The open question I'd flag is coverage — we should confirm it covers the markets in scope before we commit it to the roadmap, because it covers commercially significant cities, not every city.

For engineering: It's a Laravel 12/13, PHP 8.2+ package under the FLAIRUK\Cities namespace, auto-discovered, returning immutable City value objects. You get find/findOrFail/exists/inCountry/search/options in memory, plus a CityCode validation rule — so no migration is required for the common case. If you do want it in the database, the migration, Eloquent model, and idempotent seeder are opt-in via cities:install/cities:seed. It ships with a test suite and GitHub Actions CI. Two things to validate in a spike: data coverage and name handling for our target locales, and long-term stewardship — it's a low-adoption, single-maintainer project, so we wrap it in an internal contract and pin the version; if it stalls, we fork the dataset rather than rewrite the feature.