PHP Class that allows you to access AND format the US States in an array format of your choosing

UsStates.php

<?php
namespace App\Helpers;
/*
* Access the US States in a format of your choosing by simply calling:
* UsStates::getStates(array $format, bool $stateAllCaps, bool $includeTerritories)
* check the getStates method below for more details on how to format
*/
class UsStates
{
    public static $usStates = [
        [
            "abbr" => "AL",
            "state" => "Alabama",
            "territory" => false,
        ],
        [
            "abbr" => "AK",
            "state" => "Alaska",
            "territory" => false,
        ],
        [
            "abbr" => "AS",
            "state" => "American Samoa",
            "territory" => true,
        ],
        [
            "abbr" => "AZ",
            "state" => "Arizona",
            "territory" => false,
        ],
        [
            "abbr" => "AR",
            "state" => "Arkansas",
            "territory" => false,
        ],
        [
            "abbr" => "CA",
            "state" => "California",
            "territory" => false,
        ],
        [
            "abbr" => "CO",
            "state" => "Colorado",
            "territory" => false,
        ],
        [
            "abbr" => "CT",
            "state" => "Connecticut",
            "territory" => false,
        ],
        [
            "abbr" => "DE",
            "state" => "Delaware",
            "territory" => false,
        ],
        [
            "abbr" => "DC",
            "state" => "District Of Columbia",
            "territory" => false,
        ],
        [
            "abbr" => "FM",
            "state" => "Federated States Of Mirconesia",
            "territory" => true,
        ],
        [
            "abbr" => "FL",
            "state" => "Florida",
            "territory" => false,
        ],
        [
            "abbr" => "GA",
            "state" => "Georgia",
            "territory" => false,
        ],
        [
            "abbr" => "GU",
            "state" => "Guam Gu",
            "territory" => true,
        ],
        [
            "abbr" => "HI",
            "state" => "Hawaii",
            "territory" => false,
        ],
        [
            "abbr" => "ID",
            "state" => "Idaho",
            "territory" => false,
        ],
        [
            "abbr" => "IL",
            "state" => "Illinois",
            "territory" => false,
        ],
        [
            "abbr" => "IN",
            "state" => "Indiana",
            "territory" => false,
        ],
        [
            "abbr" => "IA",
            "state" => "Iowa",
            "territory" => false,
        ],
        [
            "abbr" => "KS",
            "state" => "Kansas",
            "territory" => false,
        ],
        [
            "abbr" => "KY",
            "state" => "Kentucky",
            "territory" => false,
        ],
        [
            "abbr" => "LA",
            "state" => "Louisiana",
            "territory" => false,
        ],
        [
            "abbr" => "ME",
            "state" => "Maine",
            "territory" => false,
        ],
        [
            "abbr" => "MH",
            "state" => "Marshall Islands",
            "territory" => true,
        ],
        [
            "abbr" => "MD",
            "state" => "Maryland",
            "territory" => false,
        ],
        [
            "abbr" => "MA",
            "state" => "Massachusetts",
            "territory" => false,
        ],
        [
            "abbr" => "MI",
            "state" => "Michigan",
            "territory" => false,
        ],
        [
            "abbr" => "MN",
            "state" => "Minnesota",
            "territory" => false,
        ],
        [
            "abbr" => "MS",
            "state" => "Mississippi",
            "territory" => false,
        ],
        [
            "abbr" => "MO",
            "state" => "Missouri",
            "territory" => false,
        ],
        [
            "abbr" => "MT",
            "state" => "Montana",
            "territory" => false,
        ],
        [
            "abbr" => "NE",
            "state" => "Nebraska",
            "territory" => false,
        ],
        [
            "abbr" => "NV",
            "state" => "Nevada",
            "territory" => false,
        ],
        [
            "abbr" => "NH",
            "state" => "New Hampshire",
            "territory" => false,
        ],
        [
            "abbr" => "NJ",
            "state" => "New Jersey",
            "territory" => false,
        ],
        [
            "abbr" => "NM",
            "state" => "New Mexico",
            "territory" => false,
        ],
        [
            "abbr" => "NY",
            "state" => "New York",
            "territory" => false,
        ],
        [
            "abbr" => "NC",
            "state" => "North Carolina",
            "territory" => false,
        ],
        [
            "abbr" => "ND",
            "state" => "North Dakota",
            "territory" => false,
        ],
        [
            "abbr" => "MP",
            "state" => "Northern Mariana Islands",
            "territory" => true,
        ],
        [
            "abbr" => "OH",
            "state" => "Ohio",
            "territory" => false,
        ],
        [
            "abbr" => "OK",
            "state" => "Oklahoma",
            "territory" => false,
        ],
        [
            "abbr" => "OR",
            "state" => "Oregon",
            "territory" => false,
        ],
        [
            "abbr" => "PW",
            "state" => "Palau",
            "territory" => true,
        ],
        [
            "abbr" => "PA",
            "state" => "Pennsylvania",
            "territory" => false,
        ],
        [
            "abbr" => "PR",
            "state" => "Puerto Rico",
            "territory" => true,
        ],
        [
            "abbr" => "RI",
            "state" => "Rhode Island",
            "territory" => false,
        ],
        [
            "abbr" => "SC",
            "state" => "South Carolina",
            "territory" => false,
        ],
        [
            "abbr" => "SD",
            "state" => "South Dakota",
            "territory" => false,
        ],
        [
            "abbr" => "TN",
            "state" => "Tennessee",
            "territory" => false,
        ],
        [
            "abbr" => "TX",
            "state" => "Texas",
            "territory" => false,
        ],
        [
            "abbr" => "UT",
            "state" => "Utah",
            "territory" => false,
        ],
        [
            "abbr" => "VT",
            "state" => "Vermont",
            "territory" => false,
        ],
        [
            "abbr" => "VI",
            "state" => "Virgin Islands",
            "territory" => true,
        ],
        [
            "abbr" => "VA",
            "state" => "Virginia",
            "territory" => false,
        ],
        [
            "abbr" => "WA",
            "state" => "Washington",
            "territory" => false,
        ],
        [
            "abbr" => "WV",
            "state" => "West Virginia",
            "territory" => false,
        ],
        [
            "abbr" => "WI",
            "state" => "Wisconson",
            "territory" => false,
        ],
        [
            "abbr" => "WY",
            "state" => "Wyoming",
            "territory" => false,
        ],
        [
            "abbr" => "AE",
            "state" => 'Armed Forces Africa \ Canada \ Europe \ Middle East',
            "territory" => true,
        ],
        [
            "abbr" => "AA",
            "state" => "Armed Forces America (except Canada)",
            "territory" => true,
        ],
        [
            "abbr" => "AP",
            "state" => "Armed Forces Pacific",
            "territory" => true,
        ],
    ];

    public static $validPlaceholders = [
        'abbr' => [
            'abbreviation', 'a',
        ],
        'state' => [
            'usstate', 's',
        ],
        'territory' => [
            'terr', 't',
        ],
    ];

    /*
     * Gets the list of US States in a format of your choosing the available keywords are as follows:
     * 'state' => aliases = ['s', 'usstate'] - example "TEXAS"
     * 'abbr' => aliases =['a', 'abbreviation'] - example "TX"
     * 'territory' => aliases = ['t', 'terr']  - example false
     *
     * You can use the official placeholder or any of its aliases and it will populate your format array
     * For nested arrays within the parent array only values will be populated, keys will be left alone
     * You can also just put in a string or nothing at all
     *
     * Examples:
     *
     * UsStates::getStates(['state' => ['abbreviation' => 'abbr', 'territory' => 't']]) =>
     * ['Alabama' => ['abbreviation' => 'AL', 'territory' => false], ...]
     *
     * UsStates::getStates(['a', 's']) =>
     * [['AL', 'Alabama'], ['AK', 'Alaska'], ...]
     *
     * UsStates::getStates('usstate') =>
     * ['Alabama', 'Alaska', 'Arizona', ...]
     * 
     * UsStates::getStates() =>
     * [['abbr' => 'Alabama', 'state' => 'Alabama', 'territory' => false], ...]
     */
    public static function getStates ($format = null, $stateAllCaps = false, $includeTerritories = false) {
        $states = self::$usStates;
        $formatted = [];
        if (!isset($format)) {
            for ($i = 0; $i < count($states); $i++) {
                if (($states[$i]['territory'] && $includeTerritories) || $states[$i]['territory'] === false) {
                    $formatted[] = [
                        'abbr' => $states[$i]['abbr'],
                        'state' => $stateAllCaps ? strtoupper($states[$i]['state']) : $states[$i]['state'],
                    ];
                }
            }
            return $formatted;
        }
        elseif (is_string($format)) {
            $val = self::getPlaceholder(strtolower($format));
            if ($val === null) {
                throw new \Exception('String format not a valid placeholder for usStates: '.$format);
            }
            for ($i = 0; $i < count($states); $i++) {
                if (($states[$i]['territory'] && $includeTerritories) || $states[$i]['territory'] === false) {
                    if ($val === 'territory') {
                        $formatted[] = $states[$i][$val];
                    }
                    else {
                        $formatted[] = $stateAllCaps ? strtoupper($states[$i][$val]) : $states[$i][$val];
                    }
                }
            }
            return $formatted;
        }
        elseif (is_array($format)) {
            $j = 0;
            foreach ($format as $key => $value) {
                if ($j > 0) break;
                if (is_integer($key) && is_string($value)) {
                    if (isset($format[1])) {
                        for ($i = 0; $i < count($states); $i++) {
                            if (($states[$i]['territory'] && $includeTerritories) || $states[$i]['territory'] === false) {
                                $formatted[] = self::populateUsStateValues($states[$i], $format, $stateAllCaps);
                            }
                        }
                        return $formatted;
                    }
                    else {
                        return self::getStates($value, $stateAllCaps, $includeTerritories);
                    }
                }
                elseif(is_string($key)) {
                    $placeholderKey = self::getPlaceholder($key);
                    if (is_string($value)) {
                        $placeholderVal = self::getPlaceholder($value);
                        for ($i = 0; $i < count($states); $i++) {
                            if (($states[$i]['territory'] && $includeTerritories) || $states[$i]['territory'] === false) {
                                $thisKey = ($placeholderKey ? ($stateAllCaps && $placeholderKey === 'state') ? strtoupper($states[$i][$placeholderKey]) : $states[$i][$placeholderKey] : $key);
                                $formatted[$thisKey] = ($stateAllCaps && $value === 'state') ? strtoupper($states[$i][$placeholderVal]) : $states[$i][$placeholderVal];
                            }
                        }
                        return $formatted;
                    }
                    elseif (is_array($value)) {
                        $value = self::formatPlaceholdersValuesInArray($value);
                        for ($i = 0; $i < count($states); $i++) {
                            if (($states[$i]['territory'] && $includeTerritories) || $states[$i]['territory'] === false) {
                                $thisKey = ($placeholderKey ? ($stateAllCaps && $placeholderKey === 'state') ? strtoupper($states[$i][$placeholderKey]) : $states[$i][$placeholderKey] : $key);
                                $formatted[$thisKey] = self::populateUsStateValues($states[$i], $value, $stateAllCaps);
                            }
                        }
                        return $formatted;
                    }
                }
                else {
                    throw new \Exception('Invalid array format for usStates', 500);
                }
                $j++;
            }
        }
        else {
            throw new \Exception('Invalid format for getting usStates', 500);
        }
        return null;
    }

    public static function getPlaceholder ($val) {
        $val = strtolower($val);
        $placeholders = self::$validPlaceholders;
        $h = null;
        foreach ($placeholders as $holder => $values) {
            if ($val === $holder || in_array($val, $values)) {
                $h = $holder;
                break;
            }
        }
        return $h;
    }

    public static function formatPlaceholdersValuesInArray ($array) {
        foreach ($array as $key => &$value) {
            if (is_string($value)) {
                $value = self::getPlaceholder($value) ?: $value;
            }
            elseif (is_array($value)) {
                $value = self::formatPlaceholdersValuesInArray($value);
            }
        }
        return $array;
    }

    public static function populateUsStateValues($state, $array, $stateAllCaps = true)
    {
        foreach ($array as $key => $value) {
            if (is_string($value)) {
                $placeholder = self::getPlaceholder($value);
                if ($stateAllCaps && $placeholder === 'state') {
                    $array[$key] = strtoupper($state[$placeholder]);
                }
                elseif ($placeholder) {
                    $array[$key] = $state[$placeholder];
                }
                else {
                    $array[$key] = $value;
                }
            }
            elseif (is_array($value)) {
                $array[$key] = self::populateUsStateValues($state, $value, $stateAllCaps);
            }
        }
        return $array;
    }

}