galahad / laravel-addressing
Laravel package providing addressing functionality
Installs: 16 901
Dependents: 0
Suggesters: 0
Security: 0
Stars: 17
Watchers: 4
Forks: 7
Open Issues: 1
Requires
- php: ^7.1.3|^8.0
- commerceguys/addressing: ^1.0
- commerceguys/intl: ^1.0
- illuminate/contracts: ~5.7.0|~5.8.0|^6.0|^7.0|^8.0
- illuminate/http: ~5.7.0|~5.8.0|^6.0|^7.0|^8.0
- illuminate/routing: ~5.7.0|~5.8.0|^6.0|^7.0|^8.0
- illuminate/support: ~5.7.0|~5.8.0|^6.0|^7.0|^8.0
- illuminate/validation: ~5.7.0|~5.8.0|^6.0|^7.0|^8.0
- symfony/intl: ^4.2|^5.0
Requires (Dev)
- ext-json: *
- orchestra/testbench: ~3.7.0|~3.8.0|~3.9.0|^4.0|^5.0|^6.0
- phpunit/phpunit: ^7.0|^8.0
- dev-master
- 2.2.0
- 2.1.0
- 2.0.1
- 2.0.0
- 1.0.x-dev
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0-beta
- v0.5.x-dev
- 0.5.1
- 0.5.0
- 0.5.0-beta2
- 0.5.0-beta1
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.1
- 0.1.0
- dev-dependabot/composer/symfony/http-kernel-4.4.17
- dev-remove-routes-file
- dev-development
- dev-postal-validation-fix
This package is auto-updated.
Last update: 2021-03-29 00:37:19 UTC
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 now7.1.3
Galahad\LaravelAddressing\ServiceProvider
has been moved toGalahad\LaravelAddressing\Support\AddressingServiceProvider
, so if you were manually registering the service provider, please update yourapp.php
config file.Galahad\LaravelAddressing\Facades\Addressing
has been moved toGalahad\LaravelAddressing\Support\Facades\Addressing
, so if you were manually registering the service provider, please update yourapp.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 orLaravelAddressing
class, and everything else is loaded via its parent. - Most custom methods have been removed from
CountryCollection
andAdministrativeAreaCollection
(getCountryCode()
, etc) in favor of just callinggetCountry()
on the collection and then accessing the Country entity directly. LaravelAddressing::getCountryList()
has been removed in favor ofcountries()->toSelectArray()
Country::getAdministrativeAreasList()
has been removed in favor ofadministrativeAreas()->toSelectArray()
Entity\Country
no longer extendsCommerceGuys\Addressing\Country
(which is now afinal
class), and instead provides a similar/decorated APIEntity\AdministrativeArea
no longer extendsCommerceGuys\Addressing\Subdivision\Subdivision
, and instead extendsEntity\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 theSupport/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, seesrc/Support/Validation/
for details. - The
/{country}/administrative-areas
HTTP endpoint no longer returns anexpected_length
value andcountry
has been renamed tocountry_code
- The config
addressing.route.prefix
has been renamedaddressing.routes.prefix
andaddressing.routes.enabled
has been added - The
UnknownCountryException
is no longer thrown, andNULL
is returned instead
Thanks!
Special thanks to Commerce Guys for their amazing addressing and intl packages, which this project relies heavily on.