Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
23 / 23
100.00%
7 / 7
 CRAP
100.00%
1 / 1
AddressValues
100.00%
23 / 23
100.00%
7 / 7
 8
100.00%
1 / 1
 getCommonRouteTypes
100.00%
5 / 5
100.00%
1 / 1
 1
 getRouteTypes
100.00%
9 / 9
100.00%
1 / 1
 2
 getDirections
100.00%
3 / 3
100.00%
1 / 1
 1
 getStates
100.00%
1 / 1
100.00%
1 / 1
 1
 getStateCodes
100.00%
1 / 1
100.00%
1 / 1
 1
 getStateNames
100.00%
1 / 1
100.00%
1 / 1
 1
 getUnitTypes
100.00%
3 / 3
100.00%
1 / 1
 1
1<?php
2/**
3 * Pop PHP Framework (https://www.popphp.org/)
4 *
5 * @link       https://github.com/popphp/popphp-framework
6 * @author     Nick Sagona, III <dev@noladev.com>
7 * @copyright  Copyright (c) 2009-2026 NOLA Interactive, LLC.
8 * @license    https://www.popphp.org/license     New BSD License
9 */
10
11/**
12 * @namespace
13 */
14namespace Pop\Parser\Address;
15
16/**
17 * Address values class
18 *
19 * @author     Mark Maher
20 * @copyright  Copyright (c) 2021
21 * @version    2.0.0
22 */
23class AddressValues
24{
25    /**
26     * A list of common route type designators provided by USPS
27     * @var array $commonRouteTypes
28     * */
29    protected static array $commonRouteTypes = [
30        "avenue", "boulevard", "circle", "drive", "highway", "lane", "park", "park drive", "park dr", "parkway drive",
31        "parkway dr", "parkway", "place", "place drive", "place dr", "road", "route", "square", "street", "terrace",
32        "trace", "ave", "av", "blvd", "boul", "cir", "dr", "hwy", "ln ", "pk", "pky", "pl", "rd", "rte", "sq", "st",
33        "terr", "trce",
34    ];
35
36    /**
37     * A list of route type designators provided by USPS
38     * @var array $routeTypes
39     * */
40    protected static array $routeTypes = [
41        "allee" => "aly","alley" => "aly","ally" => "aly","aly" => "aly","anex" => "anx","annex" => "anx",
42        "annx" => "anx","anx" => "anx","arc" => "arc","arcade" => "arc","bayoo" => "byu",
43        "bayou" => "byu","bch" => "bch","beach" => "bch","bend" => "bnd","bg" => "bg","bgs" => "bgs","blf" => "blf",
44        "blfs" => "blfs","bluf" => "blf","bluff" => "blf","bluffs" => "blfs","blvd" => "blvd","bnd" => "bnd",
45        "bot" => "btm","bottm" => "btm","bottom" => "btm",
46        "br" => "br","branch" => "br","brdge" => "brg","brg" => "brg","bridge" => "brg","brk" => "brk","brks" => "brks",
47        "brnch" => "br","brook" => "brk","brooks" => "brks","btm" => "btm","burg" => "bg","burgs" => "bgs",
48        "byp" => "byp","bypa" => "byp","bypas" => "byp","bypass" => "byp","byps" => "byp","byu" => "byu",
49        "camp" => "cp","canyn" => "cyn","canyon" => "cyn","cape" => "cpe","causeway" => "cswy","causway" => "cswy",
50        "cen" => "ctr","cent" => "ctr","center" => "ctr","centers" => "ctrs","centr" => "ctr","centre" => "ctr",
51        "ck" => "crk","clb" => "clb","clf" => "clf","clfs" => "clfs","cliff" => "clf","cliffs" => "clfs",
52        "club" => "clb","cmn" => "cmn","cmp" => "cp","cnter" => "ctr","cntr" => "ctr","cnyn" => "cyn",
53        "common" => "cmn","cor" => "cor","corner" => "cor","corners" => "cors","cors" => "cors","course" => "crse",
54        "court" => "ct","courts" => "cts","cove" => "cv","coves" => "cvs","cp" => "cp","cpe" => "cpe","cr" => "crk",
55        "crcl" => "cir","crcle" => "cir","crecent" => "cres","creek" => "crk","cres" => "cres","crescent" => "cres",
56        "cresent" => "cres","crest" => "crst","crk" => "crk","crossing" => "xing","crossroad" => "xrd",
57        "crscnt" => "cres","crse" => "crse","crsent" => "cres","crsnt" => "cres","crssing" => "xing","crssng" => "xing",
58        "crst" => "crst","crt" => "ct","cswy" => "cswy","ct" => "ct","ctr" => "ctr","ctrs" => "ctrs","cts" => "cts",
59        "curv" => "curv","curve" => "curv","cv" => "cv","cvs" => "cvs","cyn" => "cyn","dale" => "dl","dam" => "dm",
60        "div" => "dv","divide" => "dv","dl" => "dl","dm" => "dm","dv" => "dv","dvd" => "dv","est" => "est","estate" => "est",
61        "estates" => "ests","ests" => "ests","exp" => "expy","expr" => "expy","express" => "expy","expressway" => "expy",
62        "expw" => "expy","expy" => "expy","ext" => "ext","extension" => "ext","extensions" => "exts","extn" => "ext",
63        "extnsn" => "ext","exts" => "exts","falls" => "fls","ferry" => "fry","field" => "fld","fields" => "flds",
64        "flat" => "flt","flats" => "flts","fld" => "fld","flds" => "flds","fls" => "fls","flt" => "flt","flts" => "flts",
65        "ford" => "frd","fords" => "frds","forest" => "frst","forests" => "frst","forg" => "frg","forge" => "frg",
66        "forges" => "frgs","fork" => "frk","forks" => "frks","fort" => "ft","frd" => "frd","frds" => "frds",
67        "freeway" => "fwy","freewy" => "fwy","frg" => "frg","frgs" => "frgs","frk" => "frk","frks" => "frks",
68        "frry" => "fry","frst" => "frst","frt" => "ft","frway" => "fwy","frwy" => "fwy","fry" => "fry","ft" => "ft",
69        "fwy" => "fwy","garden" => "gdn","gardens" => "gdns","gardn" => "gdn","gateway" => "gtwy","gatewy" => "gtwy",
70        "gatway" => "gtwy","gdn" => "gdn","gdns" => "gdns","glen" => "gln","glens" => "glns","gln" => "gln",
71        "glns" => "glns","grden" => "gdn","grdn" => "gdn","grdns" => "gdns","green" => "grn","greens" => "grns",
72        "grn" => "grn","grns" => "grns","grov" => "grv","grove" => "grv","groves" => "grvs","grv" => "grv",
73        "grvs" => "grvs","gtway" => "gtwy","gtwy" => "gtwy","harb" => "hbr","harbor" => "hbr","harbors" => "hbrs",
74        "harbr" => "hbr","haven" => "hvn","havn" => "hvn","hbr" => "hbr","hbrs" => "hbrs","height" => "hts",
75        "heights" => "hts","hgts" => "hts","hill" => "hl","hills" => "hls",
76        "hiway" => "hwy","hiwy" => "hwy","hl" => "hl","hls" => "hls","hllw" => "holw","hollow" => "holw",
77        "hollows" => "holw","holw" => "holw","holws" => "holw","hrbor" => "hbr","ht" => "hts","hts" => "hts",
78        "hvn" => "hvn","hway" => "hwy","hwy" => "hwy","inlet" => "inlt","inlt" => "inlt","is" => "is","island" => "is",
79        "islands" => "iss","isle" => "isle","isles" => "isle","islnd" => "is","islnds" => "iss","iss" => "iss",
80        "jct" => "jct","jction" => "jct","jctn" => "jct","jctns" => "jcts","jcts" => "jcts","junction" => "jct",
81        "junctions" => "jcts","junctn" => "jct","juncton" => "jct","key" => "ky","keys" => "kys","knl" => "knl",
82        "knls" => "knls","knol" => "knl","knoll" => "knl","knolls" => "knls","ky" => "ky","kys" => "kys","la" => "ln",
83        "lake" => "lk","lakes" => "lks","landing" => "lndg","lck" => "lck",
84        "lcks" => "lcks","ldg" => "ldg","ldge" => "ldg","lf" => "lf","lgt" => "lgt","lgts" => "lgts","light" => "lgt",
85        "lights" => "lgts","lk" => "lk","lks" => "lks","ln" => "ln","lndg" => "lndg","lndng" => "lndg","loaf" => "lf",
86        "lock" => "lck","locks" => "lcks","lodg" => "ldg","lodge" => "ldg","loop" => "loop","loops" => "loop","manor" => "mnr",
87        "manors" => "mnrs","mdw" => "mdw","mdws" => "mdws","meadow" => "mdw","meadows" => "mdws","medows" => "mdws",
88        "mill" => "ml","mills" => "mls","mission" => "msn","missn" => "msn","ml" => "ml","mls" => "mls","mnr" => "mnr",
89        "mnrs" => "mnrs","mnt" => "mt","mntain" => "mtn","mntn" => "mtn","mntns" => "mtns","motorway" => "mtwy",
90        "mount" => "mt","mountain" => "mtn","mountains" => "mtns","mountin" => "mtn","msn" => "msn","mssn" => "msn",
91        "mt" => "mt","mtin" => "mtn","mtn" => "mtn","mtns" => "mtns","mtwy" => "mtwy","nck" => "nck","neck" => "nck",
92        "opas" => "opas","orch" => "orch","orchard" => "orch","orchrd" => "orch","oval" => "oval","overpass" => "opas",
93        "ovl" => "oval",
94        "pass" => "pass","passage" => "psge","path" => "path","paths" => "path","pike" => "pike","pikes" => "pike",
95        "pine" => "pne","pines" => "pnes","pk" => "park","plain" => "pln","plaines" => "plns","plains" => "plns",
96        "plaza" => "plz","pln" => "pln","plns" => "plns","plz" => "plz","plza" => "plz","pne" => "pne","pnes" => "pnes",
97        "point" => "pt","points" => "pts","port" => "prt","ports" => "prts","pr" => "pr","prairie" => "pr",
98        "prarie" => "pr","prk" => "park","prr" => "pr","prt" => "prt","prts" => "prts","psge" => "psge","pt" => "pt",
99        "pts" => "pts","rad" => "radl","radial" => "radl","radiel" => "radl","radl" => "radl","ranch" => "rnch",
100        "ranches" => "rnch","rapid" => "rpd","rapids" => "rpds","rd" => "rd","rdg" => "rdg","rdge" => "rdg",
101        "rdgs" => "rdgs","rds" => "rds","rest" => "rst","ridge" => "rdg","ridges" => "rdgs","riv" => "riv",
102        "river" => "riv","rivr" => "riv","rnch" => "rnch","rnchs" => "rnch","rpd" => "rpd","rpds" => "rpds",
103        "rst" => "rst","rte" => "rte","rvr" => "riv",
104        "row" => "row","shl" => "shl","shls" => "shls","shoal" => "shl","shoals" => "shls","shoar" => "shr",
105        "shoars" => "shrs","shore" => "shr","shores" => "shrs","shr" => "shr","shrs" => "shrs","skwy" => "skwy",
106        "skyway" => "skwy","smt" => "smt","spg" => "spg","spgs" => "spgs","spng" => "spg","spngs" => "spgs",
107        "spring" => "spg","springs" => "spgs","sprng" => "spg","sprngs" => "spgs","spur" => "spur","spurs" => "spur",
108        "sq" => "sq","sqr" => "sq","sqre" => "sq","sqrs" => "sqs","sqs" => "sqs","sta" => "sta","station" => "sta",
109        "statn" => "sta","stn" => "sta",
110        "str" => "st","stra" => "stra","strav" => "stra","strave" => "stra","straven" => "stra","stravenue" => "stra",
111        "stravn" => "stra","stream" => "strm","street" => "st","streets" => "sts","streme" => "strm","strm" => "strm",
112        "strt" => "st","strvn" => "stra","strvnue" => "stra","sts" => "sts","sumit" => "smt","sumitt" => "smt",
113        "summit" => "smt","throughway" => "trwy","tpk" => "tpke",
114        "tpke" => "tpke","tr" => "trl","track" => "trak","tracks" => "trak",
115        "trafficway" => "trfy","trail" => "trl","trails" => "trl","trak" => "trak","trce" => "trce","trfy" => "trfy",
116        "trk" => "trak","trks" => "trak","trl" => "trl","trls" => "trl","trnpk" => "tpke","trpk" => "tpke","trwy" => "trwy",
117        "tunel" => "tunl","tunl" => "tunl","tunls" => "tunl","tunnel" => "tunl","tunnels" => "tunl","tunnl" => "tunl",
118        "turnpike" => "tpke","turnpk" => "tpke","underpass" => "upas","un" => "un","union" => "un","unions" => "uns",
119        "uns" => "uns","upas" => "upas","valley" => "vly","valleys" => "vlys","vally" => "vly","vdct" => "via","via" => "via",
120        "viadct" => "via","viaduct" => "via","view" => "vw","views" => "vws","vill" => "vlg","villag" => "vlg",
121        "village" => "vlg","villages" => "vlgs","ville" => "vl","villg" => "vlg","villiage" => "vlg","vis" => "vis",
122        "vist" => "vis","vista" => "vis","vl" => "vl","vlg" => "vlg","vlgs" => "vlgs","vlly" => "vly","vly" => "vly",
123        "vlys" => "vlys","vst" => "vis","vsta" => "vis","vw" => "vw","vws" => "vws","walk" => "walk","walks" => "walk",
124        "way" => "way","well" => "wl","wells" => "wls","wl" => "wl","wls" => "wls","wy" => "way","xing" => "xing","xrd" => "xrd"
125    ];
126
127    /**
128     * A list of possible directional indicators
129     * @var array $directions
130     * */
131    protected static array $directions = [
132        'WSW'   => 'West-Southwest',
133        'ESE'   => 'East-Southeast',
134        'SSW'   => 'South-Southwest',
135        'SSE'   => 'South-Southeast',
136        'WNW'   => 'West-Northwest',
137        'ENE'   => 'East-Northeast',
138        'NNW'   => 'North-Northwest',
139        'NNE'   => 'North-Northeast',
140        'SW'    => 'Southwest',
141        'SE'    => 'Southeast',
142        'NW'    => 'Northwest',
143        'NE'    => 'Northeast',
144        ' N '   => 'North',
145        ' S '   => 'South',
146        ' E '   => 'East',
147        ' W '   => 'West',
148        'N.'    => 'North',
149        'S.'    => 'South',
150        'E.'    => 'East',
151        'W.'    => 'West',
152    ];
153
154    /**
155     * A list of states and state codes
156     * @var array $states
157     * */
158    protected static array $states = [
159        'US' => [
160            'AL' => 'Alabama',
161            'AK' => 'Alaska',
162            'AZ' => 'Arizona',
163            'AR' => 'Arkansas',
164            'CA' => 'California',
165            'CO' => 'Colorado',
166            'CT' => 'Connecticut',
167            'DE' => 'Delaware',
168            'DC' => 'District of Columbia',
169            'FL' => 'Florida',
170            'GA' => 'Georgia',
171            'HI' => 'Hawaii',
172            'ID' => 'Idaho',
173            'IL' => 'Illinois',
174            'IN' => 'Indiana',
175            'IA' => 'Iowa',
176            'KS' => 'Kansas',
177            'KY' => 'Kentucky',
178            'LA' => 'Louisiana',
179            'ME' => 'Maine',
180            'MD' => 'Maryland',
181            'MA' => 'Massachusetts',
182            'MI' => 'Michigan',
183            'MN' => 'Minnesota',
184            'MS' => 'Mississippi',
185            'MO' => 'Missouri',
186            'MT' => 'Montana',
187            'NE' => 'Nebraska',
188            'NV' => 'Nevada',
189            'NH' => 'New Hampshire',
190            'NJ' => 'New Jersey',
191            'NM' => 'New Mexico',
192            'NY' => 'New York',
193            'NC' => 'North Carolina',
194            'ND' => 'North Dakota',
195            'OH' => 'Ohio',
196            'OK' => 'Oklahoma',
197            'OR' => 'Oregon',
198            'PA' => 'Pennsylvania',
199            'PR' => 'Puerto Rico',
200            'RI' => 'Rhode Island',
201            'SC' => 'South Carolina',
202            'SD' => 'South Dakota',
203            'TN' => 'Tennessee',
204            'TX' => 'Texas',
205            'UT' => 'Utah',
206            'VT' => 'Vermont',
207            'VA' => 'Virginia',
208            'WA' => 'Washington',
209            'WV' => 'West Virginia',
210            'WI' => 'Wisconsin',
211            'WY' => 'Wyoming',
212        ],
213        'CA' => [
214            'AB' => 'Alberta',
215            'BC' => 'British Columbia',
216            'MB' => 'Manitoba',
217            'NB' => 'New Brunswick',
218            'NL' => 'Newfoundland and Labrador',
219            'NT' => 'Northwest Territories',
220            'NS' => 'Nova Scotia',
221            'NU' => 'Nunavut',
222            'ON' => 'Ontario',
223            'PE' => 'Prince Edward Island',
224            'QC' => 'Quebec',
225            'SK' => 'Saskatchewan',
226            'YT' => 'Yukon',
227        ]
228    ];
229
230    /**
231     * A list of possibly unit types
232     * @var array $unitTypes
233     * */
234    protected static array $unitTypes = [
235        'APARTMENT'  => 'APT',
236        'APT'        => 'APT',
237        'BASEMENT'   => 'BSMT',
238        'BSMT'       => 'BSMT',
239        'BLDG'       => 'BLDG',
240        'BUILDING'   => 'BLDG',
241        'DEPARTMENT' => 'DEPT',
242        'DEPT'       => 'DEPT',
243        'FL'         => 'FL',
244        'FLR'        => 'FL',
245        'FLOOR'      => 'FL',
246        'FRNT'       => 'FRNT',
247        'FRONT'      => 'FRNT',
248        'HANGAR'     => 'HNGR',
249        'HNGR'       => 'HNGR',
250        'LBBY'       => 'LBBY',
251        'LOBBY'      => 'LBBY',
252        'LOT'        => 'LOT',
253        'LOWER'      => 'LOWR',
254        'LOWR'       => 'LOWER',
255        'NO'         => 'NUMBER',
256        'OFC'        => 'OFC',
257        'OFFICE'     => 'OFC',
258        'PENTHOUSE'  => 'PH',
259        'PH'         => 'PH',
260        'PIER'       => 'PIER',
261        'REAR'       => 'REAR',
262        'RM'         => 'RM',
263        'ROOM'       => 'RM',
264        'SIDE'       => 'SIDE',
265        'SLIP'       => 'SLIP',
266        'SPACE'      => 'SPC',
267        'SPC'        => 'SPC',
268        'STE'        => 'STE',
269        'STOP'       => 'STOP',
270        'SUITE'      => 'STE',
271        'TRAILER'    => 'TRLR',
272        'TRLR'       => 'TRLR',
273        'UNIT'       => 'UNIT',
274        'UPPER'      => 'UPPR',
275        'UPPR'       => 'UPPR',
276        '#'          => '#',
277    ];
278
279
280    /**
281     * Getter method for accessing common route types list
282     *
283     * @return array
284     */
285    public function getCommonRouteTypes(): array
286    {
287        $routes = self::$commonRouteTypes;
288
289        usort($routes, function($a, $b) {
290            return strlen($b) - strlen($a);
291        });
292
293        return $routes;
294    }
295
296    /**
297     * Getter method for accessing route types list
298     *
299     * @param  bool $merge
300     * @return array
301     */
302    public function getRouteTypes(bool $merge = false): array
303    {
304        $routes = self::$routeTypes;
305
306        if ($merge) {
307            $keys   = array_keys($routes);
308            $values = array_values($routes);
309            $routes = array_unique(array_merge($keys, $values));
310
311            usort($routes, function($a, $b) {
312                return strlen($b) - strlen($a);
313            });
314        }
315
316        return $routes;
317    }
318
319    /**
320     * Getter method for accessing directionals associative array
321     *
322     * @return array
323     */
324    public function getDirections(): array
325    {
326        $directions = array_unique(array_merge(array_values(self::$directions), array_keys(self::$directions)));
327        usort($directions, function ($a, $b) {return strlen($b) - strlen($a);});
328        return $directions;
329    }
330
331    /**
332     * Getter method for accessing states associative array
333     *
334     * @param  string $country
335     * @return array
336     */
337    public function getStates(string $country = 'US'): array
338    {
339        return self::$states[$country];
340    }
341
342    /**
343     * Getter method for accessing two-letter state abbreviations
344     *
345     * @param  string $country
346     * @return array
347     */
348    public function getStateCodes(string $country = 'US'): array
349    {
350        return array_keys(self::$states[$country]);
351    }
352
353    /**
354     * Getter method for accessing full state names
355     *
356     * @param  string $country
357     * @return array
358     */
359    public function getStateNames(string $country = 'US'): array
360    {
361        return array_values(self::$states[$country]);
362    }
363
364    /**
365     * Getter method for accessing unit types list
366     *
367     * @return array
368     */
369    public function getUnitTypes(): array
370    {
371        $unitTypes = array_merge(array_values(self::$unitTypes), array_keys(self::$unitTypes));
372        usort($unitTypes, function ($a, $b) {return strlen($b) - strlen($a);});
373        return array_unique($unitTypes);
374    }
375
376}