llcu/us-states

A PHP package providing US states data with static method access

1.0.0 2025-12-16 16:27 UTC

Requires

• php: >=8.1

Requires (Dev)

• pestphp/pest: ^4.2

MIT

• LLC University

README

A PHP package providing US states data with static method access.

Requirements

• PHP 8.3 or higher

Installation

composer require llcu/us-states

Usage

All methods are static, so no instantiation is required.

Get All States

use LLCU\UsStates\States;

// Get all 50 US states (abbreviation => name)
$states = States::all();
// ['AL' => 'Alabama', 'AK' => 'Alaska', ...]

Lookup Methods

// Get state name by abbreviation
$name = States::getName('CA');
// 'California'

// Get abbreviation by state name
$abbr = States::getAbbreviation('California');
// 'CA'

Validation

// Check if valid state
States::isValidState('CA');      // true
States::isValidState('DC');      // false (DC is a territory)

// Check if valid state
States::isValid('CA');           // true
States::isValid('DC');           // true
States::isValid('XX');           // false

Lists

// Get all abbreviations
$abbreviations = States::abbreviations();
// ['AL', 'AK', 'AZ', ...]

// Get all names
$names = States::names();
// ['Alabama', 'Alaska', 'Arizona', ...]

// Get count
$count = States::count();
// 50

Search

// Search states by partial name
$results = States::search('new');
// ['NH' => 'New Hampshire', 'NJ' => 'New Jersey', 'NM' => 'New Mexico', 'NY' => 'New York']

HTML Select Options

// Basic options
$options = States::asSelectOptions();

// With placeholder
$options = States::asSelectOptions(false, 'Select a state...');
// ['' => 'Select a state...', 'AL' => 'Alabama', ...]

Random State

$random = States::random();
// ['abbreviation' => 'CA', 'name' => 'California']

Testing

This project uses Pest for testing.