PHPackages jstewmc/usps-address - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. jstewmc/usps-address ActiveLibrary[Utility & Helpers](/categories/utility) jstewmc/usps-address ==================== A simple PHP class for United States Postal Service (USPS) addresses v0.2.0(4y ago)1211.0k1MITPHPPHP ^7.4 || ^8.0 Since Oct 19Pushed 4y ago1 watchersCompare [ Source](https://github.com/jstewmc/usps-address)[ Packagist](https://packagist.org/packages/jstewmc/usps-address)[ RSS](/packages/jstewmc-usps-address/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (4)Versions (3)Used By (0) [![CircleCI](https://camo.githubusercontent.com/7f9c7bc969ceecc15535dcba4cab0d77baf8671a8d4ba4bc6e73c7c6fe63f62b/68747470733a2f2f636972636c6563692e636f6d2f67682f6a737465776d632f757370732d616464726573732e7376673f7374796c653d737667)](https://circleci.com/gh/jstewmc/usps-address) [![codecov](https://camo.githubusercontent.com/6f15591b41a146339d25394e4da7b54783db3fc46fe2492bd3be5b399e51c4ad/68747470733a2f2f636f6465636f762e696f2f67682f6a737465776d632f757370732d616464726573732f6272616e63682f6d61737465722f67726170682f62616467652e7376673f746f6b656e3d31413857637261437173)](https://codecov.io/gh/jstewmc/usps-address) USPS Address ============ [](#usps-address) A library for normalizing and comparing United States Postal Service (USPS) addresses in PHP. Comparing addresses is tricky. There are many different ways to represent the same physical address. For example, "123 *First* St" is the same address as "123 *1st* St". However, to a computer, those are two different things. This library attempts to normalize addresses so that different forms of the same physical address can be compared. For example, "17 First Street" and "17 1st st" will be considered equal. There are a few caveats: 1. A normalized address should not be displayed to users. It's formatted to help a computer compare addresses for equality, and it's not "pretty". 2. A normalized address should not be saved over the original address. The normalized version of an address may change as this library's algorithm improves, but once you overwrite the original address, it's gone forever. 3. A normalized address should not be considered *authentic*. This library will normalize and compare whatever address you give it, regardless of whether or not it actually exists. If you don't mind using a web service, there are APIs available that can normalize, validate, and authenticate addresses for you. Installation ------------ [](#installation) This library requires [PHP 7.4+](https://secure.php.net). It is multi-platform, and we strive to make it run equally well on Windows, Linux, and OSX. It should be installed via [Composer](https://getcomposer.org). To do so, add the following line to the `require` section of your `composer.json` file, and run `composer update`: ``` { "require": { "jstewmc/usps-address": "^0.2" } } ``` Usage ----- [](#usage) This library defines an interface for USPS addresses, `AddressInterface`, which supports a two-line street address, a city, a state, and a zip code, for example: ``` 123 Foo St Apt 456 Baton Rouge, LA 12345 ``` All components are optional to support partial data. This library provides an implementation of the interface, `Address`, as well as a `trait`, `Addressable`, which you can use in your own classes to implement the interface. ### Using your implementation [](#using-your-implementation) When using your implementation of `AddressInterface` (let's call it `MyAddress`), you can use this library's `Compare` service to compare addresses: ``` use Jstewmc\UspsAddress\Compare; // instantiate the compare service (ideally, from your service manager) $compare = new Compare(); // instantiate your address $address1 = (new MyAddress()) ->setStreet1('Thirty-one Spooner Street') ->setCity('Quahog') ->setState('Rhode Island') ->setZip('12345'); // instantiate a same-but-different address $address2 = (new MyAddress()) ->setStreet1('31 Spooner St') ->setCity('Quahog') ->setState('RI') ->setZip('12345'); $compare($address1, $address2); // returns true ``` If you'd like to access a lower-level normalized address, you can use the `Normalize` service to do so. Keep in mind, this service will accept any implementation of the `AddressInterface`, and it will return an instance of our own implementation, `Address`: ``` use Jstewmc\UspsAddress\Normalize; // instantiate the normalize service (ideally, from your service manager) $normalize = new Normalize(); // create an instance of your implementation $address = (new MyAddress()) ->setStreet1('Thirty-one Spooner Street') ->setCity('Quahog') ->setState('Rhode Island') ->setZip('12345'); $norm = $normalize($address); $norm->getStreet1(); // returns "31 spooner st" $norm->getCity(); // returns "quahog" $norm->getState(); // returns "rhode island" $norm->getZip(); // returns "12345" $norm instanceof \Jstewmc\UspsAddress\Address; // returns true ``` If you're using both services, you can inject your instance of the `Normalize` service into your instance of the `Compare` service. Otherwise, the `Compare` service will instantiate its own copy of the `Normalize` service: ``` use Jstewmc\UspsAddress\{Compare, Normalize}; $normalize = new Normalize(); $compare = new Compare($normalize); ``` ### Using our implementation [](#using-our-implementation) Our implementation of `AddressInterface`, `Address`, provides two methods - `equals()` and `normalize()` - for convenience. These methods are reasonable shortcuts to managing the services if you aren't processing a large number of addresses. With large enough datasets, the methods' instantiating and discarding single-use objects may affect memory and performance. ``` use Jstewmc\UspsAddress\Address; // create an address using our implementation $address1 = (new Address()) ->setStreet1('Thirty-one Spooner Street') ->setCity('Quahog') ->setState('Rhode Island') ->setZip('12345'); // create a same-but-different address $address2 = (new Address()) ->setStreet1('31 Spooner St') ->setCity('Quahog') ->setState('RI') ->setZip('12345'); $address1->equals($address2); // returns true $norm = $address1->normalize(); $norm->getStreet1(); // returns "31 spooner st" $norm->getCity(); // returns "quahog" $norm->getState(); // returns "rhode island" $norm->getZip(); // returns "12345" ``` Our implementation also allows you to instantiate an address using the constructor alone: ``` use Jstewmc\UspsAddress\Address; // Like an address, the arguments, in order, are: street 1, street 2, city, state, and zip new Address('31 Spooner St', null, 'Quahog', 'RI', '12345'); ``` Migrating from `0.1` -------------------- [](#migrating-from-01) This library changed substantially from `0.1` to `0.2`: 1. We moved previously `public static` properties to private constants to better encapsulate them. 2. We moved previously `public static` methods to a service for a service-friendly, easier-to-test solution. 3. We programmed to an interface, not an implementation, and provided a trait to make the library easier to use with your own code. 4. We removed the `Usps` prefix from class names, because it didn't add information not already obvious from the library's name. As a result, migrating from `0.1` to `0.2` involves a number of breaking changes. Although painful, we believe it will make the library easier to use and maintain in the future. Contributing ------------ [](#contributing) Contributions are welcome! ``` # Clone the repository (assuming you have Git installed). ~/path/to $ git clone git@github.com:jstewmc/usps-address.git # Install dependencies (assuming you are using Composer locally). ~/path/to/usps-address $ php composer.phar install # Run the tests. ~/path/to/usps-address $ ./vendor/bin/phpunit # Create and checkout a new branch. ~/path/to/usps-address $ git branch -c YOUR_BRANCH_NAME # Make your changes... # Run the tests again. ~/path/to/usps-address $ ./vendor/bin/phpunit # Lint your changes. ~/path/to/usps-address $ ./vendor/bin/phpcs . # Push your changes to Github and create a pull request. ~/path/to/usps-address $ git push origin YOUR_BRANCH_NAME ``` License ------- [](#license) This library is released under the [MIT License](LICENSE). ### Health Score 32 — LowBetter than 72% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity26 Limited adoption so far Community8 Small or concentrated contributor base Maturity59 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2544 days Total 2 Last Release 1678d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/50fecae0a7fd2119681bc133e496e7166b01a59f850a3c909e100bd427c6b28b?d=identicon)[Jstewmc](/maintainers/Jstewmc) --- Top Contributors [![jstewmc](https://avatars.githubusercontent.com/u/1192893?v=4)](https://github.com/jstewmc "jstewmc (18 commits)") --- Tags phpaddresspostalservicestatesuspsunited ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/jstewmc-usps-address/health.svg) ``` [![Health](https://phpackages.com/badges/jstewmc-usps-address/health.svg)](https://phpackages.com/packages/jstewmc-usps-address) ``` ### Alternatives [tapp/filament-google-autocomplete-field Filament plugin that provides a Google Autocomplete field 3098.1k](/packages/tapp-filament-google-autocomplete-field)[prevailexcel/laravel-action-service-trait A simple Laravel package to create actions, traits and services using artisan commands 143.0k](/packages/prevailexcel-laravel-action-service-trait) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)