Weave Code
Addressing Laravel Package
commerceguys/addressing
A PHP 8+ addressing library powered by CLDR and Google's address data. It provides address formats for 200+ countries, subdivisions, translations, HTML/plain-text formatting, validation via symfony/validator, and zones.
commerceguys/addressing is a PHP 8.0+ library for manipulating postal addresses, meant to identify a precise recipient location for shipping or billing. It is powered by CLDR v48 and Google's address data, and provides an AddressInterface with xAL-standard fields plus a default value object.
- Countries with translations for over 150 locales
- Address formats for 200+ countries, with field order and required fields
- Subdivisions (latin and local names) for 62 countries
- Formatting as HTML or plain text
- Validation via symfony/validator, plus zones
Frequently asked questions about Addressing
- Is commerceguys/addressing a Laravel package?
- No. It is a framework-agnostic PHP 8.0+ addressing library with no service provider, config file, facade, or Eloquent integration. In Laravel you use it in your domain layer for billing, shipping, or order addresses and wire repositories or formatters yourself.
- How do I install and configure commerceguys/addressing in Laravel?
- Install it with Composer as a normal dependency; there is no Laravel package discovery or service provider to register. It requires PHP 8.0 or newer and ships static data files, with no database, network service, API key, or rate limit. You can bind CountryRepository, AddressFormatRepository, SubdivisionRepository, and formatter instances as singletons in a service provider, optionally using a config file for locale and origin-country defaults.
- How do I use commerceguys/addressing with Eloquent models?
- Eloquent has no native embeddable concept, so you need an adapter layer. Store address fields on your model or a dedicated addresses table, then hydrate them into the library's Address value object via a cast, accessor, or mapper. Keep persistence concerns outside the value object and translate between the two at your model boundary.
- Does commerceguys/addressing integrate with Laravel validation?
- Not out of the box. The package's AddressFormatConstraint depends on symfony/validator, and Laravel's illuminate/validation has no constraint-object bridge. You can either run the Symfony constraint inside a custom Laravel rule or form request, or expose required fields, unused fields, postal-code patterns, and subdivision lists through native Laravel rules and Rule::in lookups.
- Which Laravel and PHP versions support commerceguys/addressing?
- The library requires PHP 8.0 or newer and is framework-agnostic rather than tied to a specific Laravel release. Any modern Laravel version running on PHP 8.0+ can use it as a Composer dependency, assuming your app's other dependencies also support that PHP version. Check the package's Composer constraints for the exact supported PHP range when upgrading.
- How do I format addresses in Blade with commerceguys/addressing?
- Use the package formatters instead of hand-building address strings. PostalLabelFormatter follows UPU-style international mail conventions such as per-country uppercasing, destination postal-code prefix, and dual-language country names, while the plain-text and HTML formatters handle display order. Bind formatter instances with your locale and origin-country options, then pass formatted output to Blade views for invoices, order confirmations, and admin screens.
- Can commerceguys/addressing verify that a real address is deliverable?
- No. It validates structural correctness against CLDR-derived country formats; it is not an address verification, AVRI/CASS, geocoding, autocomplete, or deduplication service. Stakeholders expecting deliverability validation should be told early that this library only checks format rules such as used fields, required fields, postal-code patterns, and subdivisions.
- Which countries have subdivision data in commerceguys/addressing?
- The README states subdivisions for 62 countries, covering administrative areas, localities, and dependent localities, though coverage is partial across the 200+ supported address formats. For countries without subdivision data there is no dropdown source or subdivision-value validation, so product needs an explicit free-text fallback rather than silent degradation. Do not assume every country has hierarchical subdivision data.
- What alternatives to commerceguys/addressing should Laravel developers consider?
- If you need actual address verification, geocoding, or autocomplete, choose a dedicated service rather than this library, because those capabilities are outside its scope. If you only need country lists or simple postal-code rules, a small Laravel-native implementation may be enough. For CLDR-derived address formats, postal formatting, subdivisions, and zones, commerceguys/addressing is the focused PHP option described here.
- What production concerns and testing steps matter for commerceguys/addressing in Laravel?
- Production risk is mainly validation strictness and data churn, not infrastructure: the library uses static PHP data with no DB, network, API keys, or rate limits. AddressFormatConstraint rejects fields unused by a country's format, so legacy free-text addresses may fail, and subdivision data is partial. Test adapters and rules with country data providers, and schedule Composer updates for CLDR and subdivision corrections with regression tests.
Weaver
How can I help you explore Laravel packages today?