commerceguys/addressing

Releases

1. ▸▾v2.3.123 Aug 2026

   Two fixes for bugs introduced in v2.3.0 :

   Two fixes for bugs introduced in v2.3.0:

   • getSubdivisionDepth() returned an error for some address formats due to a lack of a default value.
   • Guatemala (GT) subdivisions were not wired in (missing subdivision_data_fields).

   Full Changelog: v2.3.0...v2.3.1

   Open source →
2. ▸▾v2.3.023 Aug 2026Deprecated

   AddressFormat now has getSubdivisionDataFields() , replacing getSubdivisionDepth() which is now deprecated. Custom definitions using subdivision_depth…

   Address formats now declare which fields have subdivision data

   subdivision_depth has been replaced by subdivision_data_fields, which names the fields directly instead of encoding them as a count (#213):

   // Before: 1 meant "administrative areas", 2 meant "administrative areas and localities".
   'subdivision_depth' => 1,
   
   // After.
   'subdivision_data_fields' => ['administrativeArea'],

   AddressFormat now has getSubdivisionDataFields(), replacing getSubdivisionDepth() which is now deprecated. Custom definitions using subdivision_depth are still accepted and converted automatically.

   New subdivisions

   • Great Britain — the 217 counties from ISO 3166-2:GB, keyed by ISO code, with Welsh names as translations
   • Guatemala — the 22 departments, contributed by @jgalindosl (#242).

   Data corrections

   • AE - optional city field added; the missing hamza restored in the Umm Al Quwain local name.
   • CO - spelling of Guainía.
   • IT - province list updated and sorted alphabetically, thanks to @McAle16 (#237).
   • NG-— the State suffix dropped from Ogun.
   • PE - administrative areas are now labelled as regions, matching ISO 3166-2:PE.
   • RU - the Udmurt Republic now uses its official name.
   • TH - romanization fixed for Chumphon, Phatthalung and Suphan Buri; the changwat prefix
     dropped from the Bueng Kan local name.
   • TR - Afyon renamed to Afyonkarahisar.
   • VE - Distrito Federal renamed to Distrito Capital, its official and ISO 3166-2 name since
     1999; La Guaira moved to its alphabetical position after the rename from Vargas.
   • VN - the city prefix dropped from the Ho Chi Minh local name.

   Other improvements

   • Reworked DefaultFormatter's logic for rendering empty fields, fixing bugs where separators
     were sometimes left behind (affecting CO, GT, JP, MX, PY, TR, UY, VE).
   • Subdivision definitions with a locale now default local_name to name, for less verbosity.
   • Malformed subdivision definition files are ignored instead of raising errors (#246).
   • PostalCodeHelper accepts modifiers in regular expression rules, so /ZE[0-9]/i works (#164).
   • doctrine/collections 3 is now allowed, thanks to @Chris53897 (#241).
   • SubdivisionUpdater mappings for Vietnam now match VN.json, thanks to @eugene-brit (#240), and cover the VN renames shipped in v2.2.5.

   Full Changelog: v2.2.5...v2.3.0