Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Laravel Addressing

Build Status Coverage Status Latest Stable Version License

Laravel package providing addressing functionality based on commerceguys/addressing


First, install the composer package:

composer require galahad/laravel-addressing

Basic Usage


$country = Addressing::country('US');
echo $country->getName(); // "United States"
echo $country->getCountryCode(); // "US"

Administrative Area (typically states or provinces)

$usa = Addressing::country('US');

echo $usa->administrativeArea('AL')->getName(); // "Alabama"
echo $usa->administrativeArea('AL')->getCode(); // "AL"

typeof $usa->administrativeAreas() // AdministrativeAreaCollection


You can use some custom validators in your Laravel app:


You can use country, country_code, or country_name to validate country input:

$this->validate($request, [
    'country' => 'required|country_code', // Must be a 2-letter ISO code, such as "US"

$this->validate($request, [
    'country' => 'required|country_name', // Must be the full country name, such as "United States"

$this->validate($request, [
    'country' => 'required|country', // Must be the full country name or 2-letter ISO code

Administrative Areas

You can use administrative_area, administrative_area_code, or administrative_area_name to validate administrative area input:

// "country_field" is the form input that represents the country to validate against

$this->validate($request, [
    'state' => 'required|administrative_area_code:name_of_country_field',

$this->validate($request, [
    'state' => 'required|administrative_area_name:country_field',

$this->validate($request, [
    'state' => 'required|administrative_area:country_field',

Postal Code

You can use postal_code to validate the zip/postal code:

$this->validate($request, [
    'postal_code' => 'required|postal_code:country_field,administrative_area_field',

HTTP Endpoints

Laravel Addressing publishes two routes by default, which can be disabled in the config file. The prefix (/galahad/addressing) can also be configured.

GET /galahad/addressing/countries

    "label": "Countries",
    "options": {
        "AF": "Afghanistan",
        "..": "...",
        "ZW": "Zimbabwe"

GET /galahad/addressing/countries/us/administrative-areas

     "label": "States",
     "country_code": "US",
     "options": {
        "AL": "Alabama",
        "**": "*******",
        "WY": "Wyoming"



This release adds Laravel 7 support and also is more permissive in its validators:

  • If we don't have a known list of administrative areas for a country, we just allow any value
  • If a country does not require an administrative area, we allow an empty string
  • If a country does not require a postal code, we allow an empty string

(The 2.0.0 release had a bug that failed to allow admin areas when we don't have data.)


This is the first stable release, with lots of breaking changes since 0.5.*

  • Minimum supported Laravel version is now 5.7 and the minimum supported PHP version is now 7.1.3
  • Galahad\LaravelAddressing\ServiceProvider has been moved to Galahad\LaravelAddressing\Support\AddressingServiceProvider, so if you were manually registering the service provider, please update your app.php config file.
  • Galahad\LaravelAddressing\Facades\Addressing has been moved to Galahad\LaravelAddressing\Support\Facades\Addressing, so if you were manually registering the service provider, please update your app.php config file.
  • The previously-deprecated Galahad\LaravelAddressing\AddressFacade has been removed
  • All custom repository classes (AddressFormatRepository, AdministrativeAreaRepository, CountryRepository) have been removed. Instead, countries are accessed via the facade or LaravelAddressing class, and everything else is loaded via its parent.
  • Most custom methods have been removed from CountryCollection and AdministrativeAreaCollection (getCountryCode(), etc) in favor of just calling getCountry() on the collection and then accessing the Country entity directly.
  • LaravelAddressing::getCountryList() has been removed in favor of countries()->toSelectArray()
  • Country::getAdministrativeAreasList() has been removed in favor of administrativeAreas()->toSelectArray()
  • Entity\Country no longer extends CommerceGuys\Addressing\Country (which is now a final class), and instead provides a similar/decorated API
  • Entity\AdministrativeArea no longer extends CommerceGuys\Addressing\Subdivision\Subdivision, and instead extends Entity\Subdivision and provides a similar/decorated API
  • Administrative areas are no longer keyed by compound codes (i.e. US-PA) and instead by their country-specific codes (i.e. PA)
  • Galahad\LaravelAddressing\Controller has been split up into separate controllers. If you're extending this, please see the Support/Http/ directory.
  • $country->getPostalCodePattern() has been removed in favor of $country->addressFormat()->getPostalCodePattern()
  • All validation logic has been refactored. The API is the same as long as you were using string-based validations (i.e. 'country_input' => 'country_code'). If not, see src/Support/Validation/ for details.
  • The /{country}/administrative-areas HTTP endpoint no longer returns an expected_length value and country has been renamed to country_code
  • The config addressing.route.prefix has been renamed addressing.routes.prefix and addressing.routes.enabled has been added
  • The UnknownCountryException is no longer thrown, and NULL is returned instead


Special thanks to Commerce Guys for their amazing addressing and intl packages, which this project relies heavily on.


Laravel package providing addressing functionality




No packages published