Addressing

Addressing (commerceguys/addressing) is a PHP 8.0+ library for working with postal addresses used in shipping, billing, and checkout flows. It ships address formats for over 200 countries, subdivisions for 60 countries, and country translations for more than 150 locales, all powered by Unicode CLDR and Google’s address data.

Beyond raw data, the library provides HTML and plain-text formatters, Symfony-based validation, and territorial zones for grouping countries, subdivisions, and postal codes for tax or shipping purposes. It is the addressing engine behind Drupal Commerce and is widely used across the PHP e-commerce ecosystem.

What You Get

• Address formats for 200+ countries and subdivision data for 60 countries
• Country lists translated into 150+ locales via Unicode CLDR
• HTML and plain-text address formatters, including postal-label uppercasing
• Address validation built on the Symfony Validator component
• Zones for grouping countries, subdivisions, and postal-code ranges

Common Use Cases

• Rendering correctly formatted shipping and billing addresses in a storefront
• Validating checkout address forms against per-country field and postal-code rules
• Building tax or shipping zones that match customers by country, state, or postal code
• Populating country and state dropdowns localized to the user’s language

Under The Hood

Architecture - The library is organized under the CommerceGuys\Addressing PSR-4 namespace with clear domain boundaries: Country, AddressFormat, Subdivision, Formatter, Validator, and Zone. Repositories (CountryRepository, AddressFormatRepository, SubdivisionRepository) load definition data from JSON resources and hydrate value objects, while the Address class implements an immutable AddressInterface with PSR-7 style with* mutators. Formatters compose these repositories to render addresses, and validators plug into Symfony’s constraint system.

Tech Stack - Written for PHP 8.0+, its only runtime dependency is doctrine/collections; symfony/validator is an optional (suggested) dependency used only for validation. Address and subdivision data ship as JSON resources generated from CLDR v48 and Google’s Address Data Service. Development tooling includes PHPUnit 9.6, vfsStream, and PHP_CodeSniffer.

Code Quality - The codebase is mature and well-tested, with a tests/ tree mirroring the src/ structure (AddressTest, LocaleTest, PostalCodeHelperTest, plus per-domain suites). PSR-4 autoloading, an enforced phpcs ruleset, and typed value objects reflect disciplined engineering, though recent commit activity is low as the project has stabilized.

API Design - The public API is ergonomic and discoverable: repositories expose simple get/getAll/getList methods, addresses use fluent withX() mutators, and formatters take an options array. The README documents every subsystem with runnable examples, keeping the getting-started boilerplate minimal for a domain this complex.