Skip to content
master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 

LaravelPostcodes

Latest Version on Packagist Software License Build Status Coverage Status Quality Score Total Downloads

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 add https://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.