Geo for Laravel
A canonical geography reference for Laravel: countries, subdivisions and currencies bound to stable ISO codes, resolved deny-by-default, carrying the tax-relevant attributes that billing and tax engines build on.
Geo for Laravel is a canonical geography reference: countries, subdivisions and currencies bound to stable ISO codes, resolved deny-by-default, and carrying the tax-relevant attributes that billing and tax engines build on. It is the shared jurisdiction primitive for the portfolio. Identity organization addresses, billing invoice addresses and the tax engine all bind to the same jurisdiction keys, so nothing downstream matches on free text.
Why it exists
A tax or billing engine must never fuzzy-match a country name or guess a rate from a ZIP. Everything has to bind to a stable, validated jurisdiction key. This package provides that key: ISO 3166-1 alpha-2 countries, ISO 3166-2 subdivisions and ISO 4217 currencies, sourced from the vetted commerceguys/addressing dataset, with one layer added on top, the tax profile of each jurisdiction.
The Jurisdiction Primitive
Stable ISO Keys
Countries, subdivisions and currencies keyed on ISO 3166 and ISO 4217, so every consumer binds to the same validated code instead of a free-text name.
Tax Profile
Each jurisdiction carries structural, slow-moving facts: regime (vat, gst, sales_tax, none), a stable regimeModule key, EU membership, sub-federal and rooftop flags. Not rates, those live in the tax engine feeds.
Deny-By-Default
An unknown country, an unknown subdivision, or a subdivision that does not belong to its country all resolve to null. Never a guess.
Sub-Federal vs Rooftop
Canada stacks tax at province level, so a subdivision is enough. The US stacks below the state and needs rooftop geocoding. The two are modelled separately rather than lumped together.
Contracts-First
Depend on the JurisdictionRepository contract; the default binding wraps the ISO dataset. Swap or persist the data without touching callers.
No Forced Migration
The reference data ships inside the library. Persisting jurisdictions for foreign-key integrity is an optional host concern, not a required migration.
One key, every consumer
Because identity, billing and tax all resolve against the same jurisdiction keys, a country or subdivision means exactly one thing across the portfolio. That is what lets a tax engine map a regimeModule to a rate feed without ever matching on a country name.
