laranail/atlas

Countries, currencies, languages and coordinates for Laravel — a generated ISO catalogue with a swappable data source, distance and bounding-box maths, and offline IP-to-country lookup.

Requires PHP ^8.4.1 || ^8.5 and Laravel ^13.0. Companion to laranail/chrono, which answers when; this one answers where.

Install

composer require laranail/atlas

No data package required — 250 countries ship with the package as a flat PHP array that OPcache holds as compiled opcodes.

Quick start

use Simtabi\Laranail\Atlas\Facades\Atlas;

$kenya = Atlas::country('KE');       // alpha-2, alpha-3 or numeric, any case

$kenya->name;          // 'Kenya'
$kenya->flag();        // '🇰🇪'
$kenya->currency();    // 'KES'

Atlas::query()->inContinent('EU')->usingCurrency('EUR')->sortedByName()->get();
Atlas::form()->options();                           // for a <select>
Atlas::distance($london, $paris)->format();         // '343.6 km'
Atlas::countryForIp('41.90.0.1');                   // offline, no API key

Everything a form needs is behind form() and returns a value => label map — options(), groupedOptions(), continents(), dialCodes(). Everything on the facade itself returns records or plain lists.

The mental model

	What it is	Reach for it
Country enum	A typed key — 250 cases	A signature, a match arm, a column cast
CountryRecord	The data	Anything you display or compute with
Atlas facade	The way from one to the other	Everywhere

The enum carries no data on purpose. The module this replaces held names, calling codes and flags as three ~240-arm match tables — data wearing code's clothes, where every correction meant editing PHP and no two tables could be checked against each other.

Documentation

Hosted at opensource.simtabi.com/documentation/laranail/atlas.

Guides

• Installation — requirements, what to publish, the table that is built rather than shipped
• Getting started — the mental model and the first calls
• Configuration — every key and its environment variable
• Architecture — the layering, what is enforced, and why the odd decisions are the way they are
• Release — cutting a version, keeping generated data current

Reference

• Querying — the immutable builder, and what the dataset does and does not carry
• Form data — everything behind form(), and why the maps live apart from the records
• Geo — coordinates, bounding boxes, and the formula that does not always converge
• IP to country — offline lookup, and the three things a null means
• Enums — three generated, one an allow-list
• Phone numbers — dial codes, per-country length rules, and what exact means
• Validation rules — CountryCode, CurrencyCode, LanguageCode, Coordinate
• Data sources — the PlaceRepository seam and extend()
• The REST API — opt-in, read-only, ten endpoints
• The chrono bridge — country → timezones, optional
• Commands — doctor, and the generators

Recipes

• Build a country picker
• Store a country on a model
• Geolocate a request
• Find the nearest thing

Stability

Pre-1.0, with immutable tags — every release is its own v0.1.x and none is ever re-pointed, so a lockfile means something. Constraints resolve ^0.1. New SemVer minors begin at 1.0.

Subdivisions, a hosted remote data source, and polygon-accurate point-in-country are candidates for v0.2; see the architecture notes.

Sister packages

• laranail/chrono — the when to this package's where
• laranail/ip-intel — city, ASN and threat signals, using this as its offline tier

Contributing & security

Issues and PRs are welcome — see CONTRIBUTING.md. Report vulnerabilities per SECURITY.md (opensource@simtabi.com); participation follows the Code of Conduct.

License

MIT © Simtabi LLC. See LICENSE.