Us State Laravel Package

Product Decisions This Supports

• Build vs. buy (build vs. depend): Replaces a hand-rolled US state name/abbreviation list plus normalization logic that every US-facing form eventually accumulates. Low-cost dependency versus owning a lookup table, edge cases (casing, abbreviations, territories), and its maintenance forever.
• Framework upgrade roadmap: 1.9.0 adds Laravel 12.x compatibility. This is the gating signal that the package will not block a Laravel 12 upgrade — a concrete input to sequencing the platform upgrade on the roadmap.
• Feature scoping: Any US address, billing/shipping, tax jurisdiction, KYC/onboarding, or compliance data-capture work can assume state validation is a solved, one-line concern — no design or estimation time needed.
• Data consistency: Enforcing a single canonical state vocabulary at the validation boundary reduces downstream normalization bugs in reporting, tax, and fulfillment integrations.
• Dependency policy: Fits a "narrow, single-purpose, actively compatibility-maintained" acceptance bar rather than a "strategic vendor" bar — useful when setting rules for what the team is allowed to pull in.

When to Consider This Package

Adopt when:

• Your validation surface is US-only and you use Laravel's native validator.
• You want zero configuration and no database-backed lookup for state validation.
• You want a small, MIT-licensed, single-responsibility dependency rather than a broad "geo" library.
• You are planning a Laravel 12 upgrade and need to clear compatibility blockers (1.9.0 covers this).

Look elsewhere when:

• You need international subdivisions — use an ISO 3166-2-based package instead; this one will not scale past the US.
• You need UI data (state dropdown options, autocomplete lists), not just validation — this package validates; it is not a data/API source for the frontend.
• You need jurisdiction data that changes (or auditable, versioned legal/geo datasets) — prefer a source with a stated data-refresh process and changelog for the data itself, not just the code.
• Your team requires vendor-backed SLAs or security review of every dependency; this is a community package with automated compatibility PRs.
• You are pinned below the supported Laravel range — verify the version matrix before adopting 1.9.0.

Release-specific note: 1.9.0 is a compatibility-only release — no new features, no breaking changes, no deprecations. It carries no product decision on its own beyond unblocking Laravel 12; the adoption rationale is unchanged from 1.8.x.

How to Pitch It (Stakeholders)

To executives: A tiny, free, open-source component that removes an entire class of data-entry and tax/fulfillment errors from our US forms, and it just cleared its Laravel 12 compatibility check — so it does not stand in the way of the platform upgrade. Cost is effectively zero; the alternative is us maintaining that list ourselves.

To engineering: One validation rule replaces hand-rolled state arrays and abbreviation maps, giving us a single canonical vocabulary at the boundary. The 1.9.0 release is Laravel 12 support only — drop-in, no migration work, no code changes. Compatibility is maintained via automated upstream PRs, so the ongoing upgrade tax is low.

Risk posture: Low. Scope is deliberately narrow (US state validation only), the failure mode is a stale jurisdiction value rather than a security or availability issue, and it is trivially replaceable if it goes unmaintained. The one thing to watch is scope creep — it is not an international or a UI data source, and shouldn't be asked to be one.