juststeveking / laravel-postcodes
A service wrapper around postcodes.io
Fund package maintenance!
JustSteveKing
Installs: 52 325
Dependents: 0
Suggesters: 0
Security: 0
Stars: 77
Watchers: 3
Forks: 22
Open Issues: 2
Requires
- php: ~7.2|^8.0
- guzzlehttp/guzzle: ^6.3|^7.0
- illuminate/support: ~5.8|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- orchestra/testbench: ^4.0|^8.0|^9.0
- phpunit/phpunit: >=7.0
- squizlabs/php_codesniffer: ^3.0
README
LaravelPostcodes
A service wrapper around postcodes.io with validation rule and macro
Install
Via Composer
$ composer require juststeveking/laravel-postcodes
After installation, merge configuration for services using:
$ php artisan vendor:publish --provider="JustSteveKing\LaravelPostcodes\PostcodesServiceProvider"
If, for some reason, this doesn't work please use the following steps:
- Add the following into the
config/services.php
configuration file:
<?php 'postcodes' => [ 'url' => env('POSTCODES_URL', 'https://api.postcodes.io/') ],
- Add
POSTCODES_URL
to your.env
file and addhttps://api.postcodes.io/
as the value.
Basic Usage
You can use the validation rule:
<?php $this->validate($request, [ 'postcode' => [ 'required', 'string', new Postcode(resolve(PostcodeService::class)) ] ]);
Or you can use the validation Macro:
$this->validate($request, [ 'postcode' => [ 'required', 'string', Rule::postcode() ] ]);
If you want to interact with the service itself:
<?php use JustSteveKing\LaravelPostcodes\Service\PostcodeService; class SomeController extends Controller { protected $postcodes; public function __construct(PostcodeService $service) { $this->postcodes = $service; } public function store(Request $request) { // validation using example above $location = $this->postcodes->getPostcode($request->postcode); } }
Or use the facade:
<?php class SomeController extends Controller { public function store(Request $request) { // validation using example above $location = Postcode::getPostcode($request->postcode); } }
Validate
<?php $service = resolve(PostcodeService::class); $service->validate('AB10 1AB'); // You can also use the facade: Postcode::validate('AB10 1AB');
Validate Postcode
<?php $service = resolve(PostcodeService::class); $service->validate('AB10 1AB'); // You can also use the facade: Postcode::validate('AB10 1AB');
Get Postcode information
<?php $service = resolve(PostcodeService::class); $service->getPostcode('AB10 1AB'); // You can also use the facade: Postcode::getPostcode('AB10 1AB');
Bulk Lookup Postcodes
<?php $service = resolve(PostcodeService::class); $service->getPostcodes([ 'AB10 1AB', 'AB10 1AF', 'AB10 1AG', ]); // You can also use the facade: Postcode::getPostcodes([ 'AB10 1AB', 'AB10 1AF', 'AB10 1AG', ]);
Get nearest postcodes for a given longitude & latitude
<?php $service = resolve(PostcodeService::class); $service->nearestPostcodesForGivenLngAndLat( 0.629806, 51.792326 ); // You can also use the facade: Postcode::nearestPostcodesForGivenLngAndLat( 0.629806, 51.792326 );
Nearest postcodes for postcode
<?php $service = resolve(PostcodeService::class); $service->nearest('AB10 1AB'); // You can also use the facade: Postcode::nearest('AB10 1AB');
Autocomplete a postcode partial
<?php $service = resolve(PostcodeService::class); $service->autocomplete('AB10'); // You can also use the facade: Postcode::autocomplete('AB10');
Query for postcode
<?php $service = resolve(PostcodeService::class); $service->query('AB10 1AB'); // You can also use the facade: Postcode::query('AB10 1AB');
Lookup terminated postcode
<?php $service = resolve(PostcodeService::class); $service->getTerminatedPostcode('AB1 0AA'); // You can also use the facade: Postcode::getTerminatedPostcode('AB1 0AA');
Lookup Outward Code
<?php $service = resolve(PostcodeService::class); $service->getOutwardCode('N11'); // You can also use the facade: Postcode::getOutwardCode('N11');
Nearest outward code for outward code
<?php $service = resolve(PostcodeService::class); $limit = 80; // Limit needs to be less than 100 $radius = 15000; // Radius needs to be less than 25000 $service->getNearestOutwardCode('N11', $limit, $radius); // You can also use the facade: Postcode::getNearestOutwardCode('N11', $limit, $radius);
Get nearest outward codes for a given longitude & latitude
<?php $service = resolve(PostcodeService::class); $service->nearestOutwardCodesForGivenLngAndLat( 0.629806, 51.792326 ); // You can also use the facade: Postcode::nearestOutwardCodesForGivenLngAndLat( 0.629806, 51.792326 );
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email juststevemcd@gmail.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.