PHPackages                             cboxdk/laravel-geo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. cboxdk/laravel-geo

ActiveLibrary

cboxdk/laravel-geo
==================

Cbox Geo — a canonical ISO 3166 country/subdivision and ISO 4217 currency reference for Laravel: data-driven jurisdiction lookups and structured addresses bound to stable codes, carrying the tax-relevant attributes downstream billing and tax engines need.

v0.6.1(2w ago)5690↓41%3MITPHPPHP ^8.4CI passing

Since Jul 14Pushed 2w agoCompare

[ Source](https://github.com/cboxdk/laravel-geo)[ Packagist](https://packagist.org/packages/cboxdk/laravel-geo)[ RSS](/packages/cboxdk-laravel-geo/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (7)Dependencies (14)Versions (8)Used By (3)

Cbox Geo
========

[](#cbox-geo)

**`cboxdk/laravel-geo`** — a canonical geography reference for Laravel: 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. A dependency-light framework library — every capability sits behind a contract you bind, mock or replace.

> This is the shared **jurisdiction primitive** for the Cbox portfolio. Identity (org addresses), billing (invoice address, seller entities) and the tax engine all bind to the *same* jurisdiction keys, so nothing downstream matches on free text.

Why it exists
-------------

[](#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, ISO 4217 currencies — sourced from the vetted [`commerceguys/addressing`](https://github.com/commerceguys/addressing) dataset, with one layer added on top: the **tax profile** of each jurisdiction.

```
use Cbox\Geo\Contracts\JurisdictionRepository;
use Cbox\Geo\ValueObjects\CountryCode;
use Cbox\Geo\ValueObjects\SubdivisionCode;

$geo = app(JurisdictionRepository::class);

$dk = $geo->find(new CountryCode('DK'));
$dk->currency;                      // "DKK"
$dk->taxProfile->regimeModule;      // "eu-vat"
$dk->taxProfile->isEuMember;        // true
$dk->isResolvedForTax();            // true — national regime

$us = $geo->find(new CountryCode('US'));
$us->needsSubdivision();            // true — sub-federal, a state is required
$us->taxProfile->requiresRooftop;   // true — rooftop geocoding needed for rates

$ca = $geo->find(new CountryCode('US'), new SubdivisionCode('US-CA'));
$ca->subdivisionName;               // "California"

$geo->find(new CountryCode('ZZ'));  // null — deny-by-default, never a guess
```

The tax profile
---------------

[](#the-tax-profile)

Each modelled jurisdiction carries structural, slow-moving facts — **not rates**(those live in the tax engine's data feeds):

attributemeaning`regime``vat` · `gst` · `sales_tax` · `none` (unmodelled → deny-by-default)`regimeModule`stable key a tax engine maps to a regime (`eu-vat`, `us-sales-tax`, …)`isEuMember`drives EU reverse-charge / OSS routing`isSubFederal`tax is set below the national level — a subdivision is required (US, CA)`requiresRooftop`rate resolution needs address-level geocoding (US only)Sub-federal is deliberately split from rooftop: **Canada** stacks at province level (a subdivision is enough), while the **US** stacks below the state and needs rooftop geocoding. National VAT/GST regimes (EU, UK, CH, NO, AU, NZ, MX) need neither.

Design
------

[](#design)

- **Contracts-first.** Depend on `Contracts\JurisdictionRepository`; 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 FK integrity is an optional host concern.
- **Deny-by-default.** An unknown country, an unknown subdivision, or a subdivision that does not belong to its country all resolve to `null`.

Requirements
------------

[](#requirements)

PHP `^8.4`; Laravel `^12 || ^13`. See `composer.json`.

Development
-----------

[](#development)

```
composer install
composer qa    # pint --test, phpstan (level max), pest, license-check, audit
```

License
-------

[](#license)

MIT.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance97

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

7

Last Release

17d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b9761a79e61f2d5b9d650510dfb3555da18daf38f027aa84012c937e397e39a7?d=identicon)[cboxdk](/maintainers/cboxdk)

---

Top Contributors

[![sylvesterdamgaard](https://avatars.githubusercontent.com/u/2431914?v=4)](https://github.com/sylvesterdamgaard "sylvesterdamgaard (7 commits)")

---

Tags

addresscboxcountrygeoiso-3166jurisdictionlaravelsubdivisionlaraveladdressISO 3166geocountrycboxsubdivisionjurisdiction

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/cboxdk-laravel-geo/health.svg)

```
[![Health](https://phpackages.com/badges/cboxdk-laravel-geo/health.svg)](https://phpackages.com/packages/cboxdk-laravel-geo)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3365.5M359](/packages/psalm-plugin-laravel)[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k104.7M370](/packages/laravel-horizon)[laravel/sail

Docker files for running a basic Laravel application.

1.9k220.0M1.5k](/packages/laravel-sail)[illuminate/database

The Illuminate Database package.

3.0k56.7M13.6k](/packages/illuminate-database)[laravel/ai

The official AI SDK for Laravel.

1.1k6.4M360](/packages/laravel-ai)[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k118.2M1.0k](/packages/laravel-socialite)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)