Download the PHP package commerceguys/addressing without Composer
On this page you can find all versions of the php package commerceguys/addressing. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package addressing
Short Description Addressing library powered by CLDR and Google's address data.
License MIT
All versions of addressing with dependencies
Informations about the package addressing
addressing
A PHP 7.3+ 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 250 locales
- Address formats for over 200 countries
- Subdivisions (administrative areas, localities, dependent localities) for 44 countries
- Both latin and local subdivision names, when relevant (e.g: Okinawa / 沖縄県)
- Formatting, in HTML or plain text.
- Validation via symfony/validator
- Zones
The dataset is stored locally in JSON format. Countries are generated from CLDR v41. Address formats and subdivisions are generated from Google's Address Data Service.
Further backstory can be found in this blog post.
Also check out commerceguys/intl for CLDR-powered languages/currencies/number formatting.
Data model
The address interface represents a postal adddress, with getters for the following fields:
- Country code
- Administrative area
- Locality (City)
- Dependent Locality
- Postal code
- Sorting code
- Address line 1
- Address line 2
- Organization
- Given name (First name)
- Additional name (Middle name / Patronymic)
- Family name (Last name)
Field names follow the OASIS eXtensible Address Language (xAL) 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 or relies on an AddressBuilder. A default address value object is provided that can be used as an example, or mapped by Doctrine (preferably as an embeddable).
The address format 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 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 provides the following information:
- The subdivision code (used to represent the subdivison on a parcel/envelope, e.g. CA for California)
- The subdivison 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 prefix (used to ensure that a postal code begins with the expected characters)
Subdivisions are hierarchical and can have up to three levels: Administrative Area -> Locality -> Dependent Locality.
Formatters
Addresses are formatted according to the address format, in HTML or text.
DefaultFormatter
Formats an address for display, always adds the localized country name.
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:
- The postal code is prefixed with the destination's postal code prefix.
- 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.
Validator
Address validation relies on the 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).
Zones
Zones are territorial 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)