PHPackages commerceguys/addressing - 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. [Localization & i18n](/categories/localization) 4. / 5. commerceguys/addressing ActiveLibrary[Localization & i18n](/categories/localization) commerceguys/addressing ======================= Addressing library powered by CLDR and Google's address data. v2.2.5(5mo ago)95931.7M↓42.8%151[11 issues](https://github.com/commerceguys/addressing/issues)[9 PRs](https://github.com/commerceguys/addressing/pulls)20MITPHPPHP >=8.0CI failing Since Feb 6Pushed 1mo ago31 watchersCompare [ Source](https://github.com/commerceguys/addressing)[ Packagist](https://packagist.org/packages/commerceguys/addressing)[ RSS](/packages/commerceguys-addressing/feed)WikiDiscussions main Synced 1w ago READMEChangelog (10)Dependencies (5)Versions (47)Used By (20) addressing ========== [](#addressing) [![Build Status](https://github.com/commerceguys/addressing/actions/workflows/build.yml/badge.svg)](https://github.com/commerceguys/addressing/actions/workflows/build.yml) A PHP 8.0+ addressing library, powered by CLDR and Google's address data. Manipulates postal addresses, meant to identify a precise recipient location for shipping or billing purposes. Features: - Countries, with translations for over 150 locales. Powered by [CLDR](http://cldr.unicode.org) v48. - Address formats for over 200 countries - Subdivisions (administrative areas, localities, dependent localities) for 60 countries - Both latin and local subdivision names, when relevant (e.g: Okinawa / 沖縄県) - Formatting, in HTML or plain text. - Validation via symfony/validator - Zones Address formats and subdivisions were initially generated from Google's [Address Data Service](https://chromium-i18n.appspot.com/ssl-address), and are now owned and maintained by the library. Also check out [commerceguys/intl](https://github.com/commerceguys/intl) for CLDR-powered languages/currencies/number formatting. Data model ========== [](#data-model) The [address interface](https://github.com/commerceguys/addressing/blob/main/src/AddressInterface.php) represents a postal address, with getters for the following fields: - Country code - Administrative area - Locality (City) - Dependent Locality - Postal code - Sorting code - Address line 1 - Address line 2 - Address line 3 - Organization - Given name (First name) - Additional name (Middle name / Patronymic) - Family name (Last name) Field names follow the OASIS [eXtensible Address Language (xAL)](http://www.oasis-open.org/committees/ciq/download.shtml) standard. The interface makes no assumptions about mutability. The implementing application can extend the interface to provide setters, or implement a value object that uses either [PSR-7 style with\* mutators](https://github.com/commerceguys/addressing/blob/main/src/ImmutableAddressInterface) or relies on an AddressBuilder. A default [address value object](https://github.com/commerceguys/addressing/blob/main/src/Address.php) is provided that can be used as an example, or mapped by Doctrine (preferably as an embeddable). The [address format](https://github.com/commerceguys/addressing/blob/main/src/AddressFormat/AddressFormat.php) provides the following information: - Which fields are used, and in which order - Which fields are required - Which fields need to be uppercased for the actual mailing (to facilitate automated sorting of mail) - The labels for the administrative area (state, province, parish, etc.), locality (city/post town/district, etc.), dependent locality (neighborhood, suburb, district, etc) and the postal code (postal code or ZIP code) - The regular expression pattern for validating postal codes The [country](https://github.com/commerceguys/addressing/blob/main/src/Country/Country.php) provides the following information: - The country name. - The numeric and three-letter country codes. - The official currency code, when known. - The timezones which the country spans. The [subdivision](https://github.com/commerceguys/addressing/blob/main/src/Subdivision/Subdivision.php) provides the following information: - The subdivision code (used to represent the subdivision on a parcel/envelope, e.g. CA for California) - The subdivision name (shown to the user in a dropdown) - The local code and name, if the country uses a non-latin script (e.g. Cyrilic in Russia). - The postal code pattern (if different from the one on the address format). Subdivisions are hierarchical and can have up to three levels: Administrative Area -> Locality -> Dependent Locality. ``` use CommerceGuys\Addressing\AddressFormat\AddressFormatRepository; use CommerceGuys\Addressing\Country\CountryRepository; use CommerceGuys\Addressing\Subdivision\SubdivisionRepository; $countryRepository = new CountryRepository(); $addressFormatRepository = new AddressFormatRepository(); $subdivisionRepository = new SubdivisionRepository(); // Get the country list (countryCode => name), in French. $countryList = $countryRepository->getList('fr-FR'); // Get the country object for Brazil. $brazil = $countryRepository->get('BR'); echo $brazil->getThreeLetterCode(); // BRA echo $brazil->getName(); // Brazil echo $brazil->getCurrencyCode(); // BRL print_r($brazil->getTimezones()); // Get all country objects. $countries = $countryRepository->getAll(); // Get the address format for Brazil. $addressFormat = $addressFormatRepository->get('BR'); // Get the subdivisions for Brazil. $states = $subdivisionRepository->getAll(['BR']); foreach ($states as $state) { $municipalities = $state->getChildren(); } // Get the subdivisions for Brazilian state Ceará. $municipalities = $subdivisionRepository->getAll(['BR', 'CE']); foreach ($municipalities as $municipality) { echo $municipality->getName(); } ``` Formatters ========== [](#formatters) Addresses are formatted according to the address format, in HTML or text. DefaultFormatter ---------------- [](#defaultformatter) Formats an address for display, always adds the localized country name. ``` use CommerceGuys\Addressing\Address; use CommerceGuys\Addressing\Formatter\DefaultFormatter; use CommerceGuys\Addressing\AddressFormat\AddressFormatRepository; use CommerceGuys\Addressing\Country\CountryRepository; use CommerceGuys\Addressing\Subdivision\SubdivisionRepository; $addressFormatRepository = new AddressFormatRepository(); $countryRepository = new CountryRepository(); $subdivisionRepository = new SubdivisionRepository(); $formatter = new DefaultFormatter($addressFormatRepository, $countryRepository, $subdivisionRepository); // Options passed to the constructor or format() allow turning off // html rendering, customizing the wrapper element and its attributes. $address = new Address(); $address = $address ->withCountryCode('US') ->withAdministrativeArea('CA') ->withLocality('Mountain View') ->withAddressLine1('1098 Alta Ave'); echo $formatter->format($address); /** Output: 1098 Alta Ave Mountain View, CA United States **/ ``` PostalLabelFormatter -------------------- [](#postallabelformatter) Takes care of uppercasing fields where required by the format (to facilitate automated mail sorting). Requires specifying the origin country code, allowing it to differentiate between domestic and international mail. In case of domestic mail, the country name is not displayed at all. In case of international mail: 1. The postal code is prefixed with the destination's postal code prefix. 2. The country name is added to the formatted address, in both the current locale and English. This matches the recommendation given by the Universal Postal Union, to avoid difficulties in countries of transit. ``` use CommerceGuys\Addressing\Address; use CommerceGuys\Addressing\Formatter\PostalLabelFormatter; use CommerceGuys\Addressing\AddressFormat\AddressFormatRepository; use CommerceGuys\Addressing\Country\CountryRepository; use CommerceGuys\Addressing\Subdivision\SubdivisionRepository; $addressFormatRepository = new AddressFormatRepository(); $countryRepository = new CountryRepository(); $subdivisionRepository = new SubdivisionRepository(); // Defaults to text rendering. Requires passing the "origin_country" // (e.g. 'FR') to the constructor or to format(). $formatter = new PostalLabelFormatter($addressFormatRepository, $countryRepository, $subdivisionRepository, ['locale' => 'fr']); $address = new Address(); $address = $address ->withCountryCode('US') ->withAdministrativeArea('CA') ->withLocality('Mountain View') ->withAddressLine1('1098 Alta Ave'); echo $formatter->format($address, ['origin_country' => 'FR']); /** Output: 1098 Alta Ave MOUNTAIN VIEW, CA 94043 ÉTATS-UNIS - UNITED STATES **/ ``` Validator ========= [](#validator) Address validation relies on the [Symfony Validator](https://github.com/symfony/validator) library. Checks performed: - All required fields are filled in. - All fields unused by the country's format are empty. - All subdivisions are valid (values matched against predefined subdivisions). - The postal code is valid (country and subdivision-level patterns). ``` use CommerceGuys\Addressing\Address; use CommerceGuys\Addressing\Validator\Constraints\AddressFormatConstraint; use CommerceGuys\Addressing\Validator\Constraints\CountryConstraint; use Symfony\Component\Validator\Validation; $address = new Address('FR'); $validator = Validation::createValidator(); // Validate the country code, then validate the rest of the address. $violations = $validator->validate($address->getCountryCode(), new CountryConstraint()); if (!$violations->count()) { $violations = $validator->validate($address, new AddressFormatConstraint()); } ``` Zones ===== [](#zones) [Zones](https://github.com/commerceguys/addressing/blob/main/src/Zone/Zone.php) are [territorial](https://github.com/commerceguys/addressing/blob/main/src/Zone/ZoneTerritory.php) groupings often used for shipping or tax purposes. For example, a set of shipping rates associated with a zone where the rates become available only if the customer's address belongs to the zone. A zone can match countries, subdivisions (states/provinces/municipalities), postal codes. Postal codes can also be expressed using ranges or regular expressions. Examples of zones: - California and Nevada - Belgium, Netherlands, Luxemburg - Germany and a set of Austrian postal codes (6691, 6991, 6992, 6993) - Austria without specific postal codes (6691, 6991, 6992, 6993) ``` use CommerceGuys\Addressing\Address; use CommerceGuys\Addressing\Zone\Zone; // Create the German VAT zone (Germany and 4 Austrian postal codes). $zone = new Zone([ 'id' => 'german_vat', 'label' => 'German VAT', 'territories' => [ ['country_code' => 'DE'], ['country_code' => 'AT', 'included_postal_codes' => '6691, 6991:6993'], ], ]); // Check if the provided austrian address matches the German VAT zone. $austrianAddress = new Address(); $austrianAddress = $austrianAddress ->withCountryCode('AT') ->withPostalCode('6992'); echo $zone->match($austrianAddress); // true ``` Integrations ============ [](#integrations) - [Drupal module](https://drupal.org/project/address) - [Symfony bundle](https://github.com/daften/addressing-bundle) ### Health Score 74 — ExcellentBetter than 100% of packages Maintenance81 Actively maintained with recent releases Popularity73 Solid adoption and visibility Community49 Growing community involvement Maturity81 Battle-tested with a long release history Bus Factor1 Top contributor holds 87% 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 ~88 days Recently: every ~137 days Total 46 Last Release 155d ago Major Versions v0.8.4 → v1.0.0-beta12016-09-26 v1.4.2 → v2.0.0-beta12023-04-18 PHP version history (6 changes)v0.5PHP >=5.4.0 v1.0.0-beta1PHP >=5.5.0 v1.0.7PHP >=7.0.8 v1.2.0PHP >=7.1.3 v1.3.0PHP >=7.3 v2.0.0-beta1PHP >=8.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/621c34dbc1ad3ea00e09f6006aa9607d0046bf862182d59c66f1f18cb51c0f15?d=identicon)[bojanz](/maintainers/bojanz) ![](https://www.gravatar.com/avatar/86a6bdd58eca36ebbb80ea79ca7ab3e6d870377453a3a7a867c85cd929e1492f?d=identicon)[jsacksick](/maintainers/jsacksick) --- Top Contributors [![bojanz](https://avatars.githubusercontent.com/u/330162?v=4)](https://github.com/bojanz "bojanz (328 commits)")[![Chris53897](https://avatars.githubusercontent.com/u/7104259?v=4)](https://github.com/Chris53897 "Chris53897 (10 commits)")[![jsacksick](https://avatars.githubusercontent.com/u/1007558?v=4)](https://github.com/jsacksick "jsacksick (5 commits)")[![Jbekker](https://avatars.githubusercontent.com/u/930668?v=4)](https://github.com/Jbekker "Jbekker (4 commits)")[![dnagirl](https://avatars.githubusercontent.com/u/808400?v=4)](https://github.com/dnagirl "dnagirl (2 commits)")[![karptonite](https://avatars.githubusercontent.com/u/132278?v=4)](https://github.com/karptonite "karptonite (2 commits)")[![lsolesen](https://avatars.githubusercontent.com/u/148026?v=4)](https://github.com/lsolesen "lsolesen (2 commits)")[![g-brodiei](https://avatars.githubusercontent.com/u/10040350?v=4)](https://github.com/g-brodiei "g-brodiei (1 commits)")[![gl2748](https://avatars.githubusercontent.com/u/3374538?v=4)](https://github.com/gl2748 "gl2748 (1 commits)")[![jaranetwork](https://avatars.githubusercontent.com/u/13411509?v=4)](https://github.com/jaranetwork "jaranetwork (1 commits)")[![josephzidell](https://avatars.githubusercontent.com/u/1812443?v=4)](https://github.com/josephzidell "josephzidell (1 commits)")[![joshuataylor](https://avatars.githubusercontent.com/u/225131?v=4)](https://github.com/joshuataylor "joshuataylor (1 commits)")[![jrbasso](https://avatars.githubusercontent.com/u/26548?v=4)](https://github.com/jrbasso "jrbasso (1 commits)")[![leevigraham](https://avatars.githubusercontent.com/u/25124?v=4)](https://github.com/leevigraham "leevigraham (1 commits)")[![lenamsoft](https://avatars.githubusercontent.com/u/264669?v=4)](https://github.com/lenamsoft "lenamsoft (1 commits)")[![lu3do](https://avatars.githubusercontent.com/u/482346?v=4)](https://github.com/lu3do "lu3do (1 commits)")[![McAle16](https://avatars.githubusercontent.com/u/26761531?v=4)](https://github.com/McAle16 "McAle16 (1 commits)")[![NickDickinsonWilde](https://avatars.githubusercontent.com/u/92694?v=4)](https://github.com/NickDickinsonWilde "NickDickinsonWilde (1 commits)")[![nicrodgers](https://avatars.githubusercontent.com/u/165700?v=4)](https://github.com/nicrodgers "nicrodgers (1 commits)")[![ohorbatiuk](https://avatars.githubusercontent.com/u/11755359?v=4)](https://github.com/ohorbatiuk "ohorbatiuk (1 commits)") --- Tags addresslocalizationinternationalizationpostal ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/commerceguys-addressing/health.svg) ``` [![Health](https://phpackages.com/badges/commerceguys-addressing/health.svg)](https://phpackages.com/packages/commerceguys-addressing) ``` ### Alternatives [symfony/intl Provides access to the localization data of the ICU library 2.6k208.8M1.3k](/packages/symfony-intl)[gettext/languages gettext languages with plural rules 7532.0M12](/packages/gettext-languages)[aplus/language Aplus Framework Language Library 2371.7M15](/packages/aplus-language)[punic/punic PHP-Unicode CLDR 1573.0M30](/packages/punic-punic)[aura/intl The Aura Intl package provides internationalization tools, specifically message translation. 928.4M4](/packages/aura-intl)[tractorcow/silverstripe-fluent Simple localisation for Silverstripe 91432.1k28](/packages/tractorcow-silverstripe-fluent) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)