README

Laravel Addressing

Laravel Addressing is a Laravel package providing addressing functionality based on commerceguys/addressing. It lets you easily work with addresses using data from CLDR and Google.

The primary focus of Laravel Addressing is:

Access to up-to-date lists of countries, states/provinces, etc
Easily validate address data
Format addresses to match a specific country's rules

If you find this package useful, you should check out Franklin, our universal address input that follows the same conventions as Laravel Addressing.

Installation

First, install the composer package:

composer require galahad/laravel-addressing

Basic Usage

Country

$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

Validators

You can use some custom validators in your Laravel app:

Countries

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"
     }
}

Thanks!

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

galahad / laravel-addressing

Maintainers

Details