README

Laravel package providing addressing functionality based on commerceguys/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"
     }
}

Changelog

2.0.1

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.)

1.0.0

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

Thanks!

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