Standards Laravel Package

Product Decisions This Supports

Build vs. buy — the core decision. This package turns a recurring build-vs-maintain question into a near-trivial "buy" (MIT, zero-cost, low-integration). Any roadmap item that needs country, currency, language, script, TLD, phone-prefix, or HTTP-status reference data would otherwise spawn an internal data-ownership project: sourcing tables, writing importers, tracking upstream changes, and defending accuracy in audits. That is weeks of engineering plus permanent maintenance for commodity data that is not a differentiator. Adopting this package reallocates that budget to product surface area.

Feature work it unblocks or de-risks:

• International expansion / localization. Country and language selectors, locale negotiation from Accept-Language, per-language display names, script and language-tag handling. This is the "go multi-market" epics list, and it front-loads the tedious 20% of i18n work.
• Checkout, pricing, and invoicing. Currency codes, minor units (decimal places), and currency symbols are exactly the metadata that causes rounding and display bugs. Note the boundary: this is currency identity and formatting metadata, not FX rates, tax logic, or payment rails.
• Address and signup forms. Country → subdivision relationships (states/provinces), dependent dropdowns, and validation that rejects free-text country entry.
• Phone input. Country calling codes plus national/international dial prefixes enable "+31 20 …" style formatting and sane defaults by user country. It is not a full phone parser/validator — plan to pair it with a libphonenumber-style library for E.164 validation.
• Eligibility and geo/regulatory gating. Country-group membership (EU, EEA, EFTA, Schengen, Eurozone, NATO, BRICS, WTO) makes "is this customer in the EU?" a typed, testable predicate instead of a hardcoded array that silently rots—directly relevant to VAT, data-residency, and feature-availability decisions.
• API/SDK and platform work. HTTP status codes and methods as enums reduce magic-number bugs in clients, webhooks, and integration layers; TLD enums support domain/email validation.
• Compliance and audit narratives. Values are traceable to authoritative upstreams (ISO, IANA, SIX, Library of Congress) with daily automated sync, which is a stronger story to auditors than "someone edited a spreadsheet in 2021."

Scope decisions this forces (usefully). Because the data is shipped as code, "how fresh is our country list?" becomes a deliberate release-cadence decision with reproducible, version-pinned behavior — good for audits and deterministic tests — rather than an opaque runtime lookup. The trade-off to accept explicitly: no same-day updates without a deploy.

Effort and risk envelope. Composer install, PHP 8.1+, no service, no credentials, no runtime latency. Real costs are (a) an upgrade cadence and (b) deciding where the vendor enum types are allowed to appear in your domain.

When to Consider This Package

Adopt when:

• You are on PHP 8.1+ (Laravel or otherwise) and already use enums or are willing to; the value proposition is typed, exhaustive, IDE-autocompletable reference data in place of string constants.
• Your product handles any of: multi-country signup/addresses, multi-currency display or billing, localization, phone or TLD input, or a public API with status/method semantics.
• You want to eliminate a homegrown lookup table or a stale countries.php config file — this is usually a small, well-bounded refactor with a clear test story.
• Data provenance matters (regulated, enterprise, or public-sector buyers) and you want an upstream-tracked source rather than hand-curated data.
• You need country-group logic (EU/EEA/Schengen) that changes over time, since membership drift is a classic silent bug.

Look elsewhere or wait when:

• You need runtime-fresh data. Sanctions lists, FX rates, tax rates, or anything that must change intraday: this is static-at-release. Pair with a live source of truth.
• You need parsing/validation depth. Full phone number parsing and E.164 validation, postal-address validation, timezone resolution, or IBAN/BIC logic — this package gives the reference data, not the algorithms.
• You need UI assets. Flags are emoji here; brand-sensitive consumer UIs may want SVG flag sets and localized country names in more languages.
• Supply-chain policy is strict. Single-maintainer, sponsorship-funded, modest adoption signals (≈489 stars; no visible dependents) mean you should treat it as a data dictionary, not critical-path logic: wrap it behind a thin internal adapter, pin the version, and keep a fallback.
• You are not on PHP 8.x, or your stack is JS/Python/Go — equivalent enum/lookup packages exist, and mixing runtimes for shared reference data is a consistency risk.
• You need framework-native artifacts (migrations, seeders, admin CRUD for country data). None ship here; that is a deliberate, low-blast-radius design, but it is real glue you would write.
• Legal review flags upstream redistribution terms for ISO-derived content; verify once with counsel rather than per-feature.

Decision rule: default to adopting for new i18n/geo/currency-adjacent work; require an ADR and an adapter boundary for existing monoliths where the vendor namespace would otherwise spread across domain code.

How to Pitch It (Stakeholders)

For executives (30 seconds). We would otherwise rebuild and perpetually maintain commodity reference data — country, currency, language, phone-prefix, TLD, and HTTP code lists — that every market we enter depends on. This package gives us that data, kept in sync daily with authoritative sources, as type-safe code under a permissive MIT license, with no service, no vendor contract, and negligible cost. The business case is cost avoidance plus accuracy: fewer data-staleness defects in checkout, forms, and geo-eligibility, and a defensible "our data is traceable to the standard" answer for enterprise and regulated buyers. The risk is contained: it is data, not a platform, and we isolate it behind a thin internal layer so it can be swapped.

For engineering leads (the practical case). Backed PHP 8.1 enums you can typehint, so invalid country/currency values become impossible to pass and match expressions become exhaustive. Rich cross-relations (Alpha2 ↔ Alpha3 ↔ numeric ↔ name, country → subdivisions, calling codes, currencies, languages, flag emoji, number formatting), plus group membership predicates for EU/EEA/Schengen/NATO/WTO. PHPStan level 10, high test coverage, semver with an UPGRADING.md, framework-agnostic and Laravel-friendly (enum casts, Rule::enum). Integration is one composer line; the only real work is replacing existing string constants and adding a regression test that asserts on a handful of enum values so a data refresh cannot silently shift behavior.

For product/design. We get localized country names, flag emoji, and region-aware number formatting for free, which shortens the "does this look native in five markets?" loop. Explicit non-goals to design around: no FX conversion, no address or phone validation logic, no flag imagery — those stay separate decisions.

Ask. Approve as a foundational dependency for the localization/expansion track; assign ownership of a quarterly dependency-update and data-diff review; fund an internal adapter layer so vendor enums do not leak across the domain.