README

A small Laravel package for validating UK postcodes. By default it checks the format only, which is fast and works offline. If you need more certainty you can optionally have it confirm the postcode actually exists by querying a postcodes.io instance — ideally one you self host.

Requirements

• PHP 8.2+
• Laravel 11, 12 or 13

Installation

composer require cladco/uk-postcode-validation

The service provider and the Postcode facade are registered automatically.

If you want to change any defaults, publish the config:

php artisan vendor:publish --tag=postcode-config

To customise the validation messages, publish the language file:

php artisan vendor:publish --tag=postcode-lang

Usage

Validation rule

Use the ValidPostcode rule wherever you validate input. On its own it checks the format only:

use Cladco\UkPostcode\Rules\ValidPostcode;

$request->validate([
    'postcode' => ['required', new ValidPostcode],
]);

To also confirm the postcode exists, use ValidPostcode::exists(). The format is always checked first, so a malformed value is rejected without making a network call:

$request->validate([
    'postcode' => ['required', ValidPostcode::exists()],
]);

Facade

For checks outside of validation, use the Postcode facade:

use Cladco\UkPostcode\Facades\Postcode;

Postcode::isValid('sw1a1aa');   // true
Postcode::format('sw1a1aa');    // "SW1A 1AA", or null if invalid
Postcode::exists('SW1A 1AA');   // true if found via postcodes.io

Standalone helper

PostcodeValidator has no framework dependencies, so you can use it directly, for example in a console command or a queued job:

use Cladco\UkPostcode\PostcodeValidator;

PostcodeValidator::isValid('B33 8TH');   // true
PostcodeValidator::normalise('b338th');  // "B33 8TH"

The optional postcodes.io check

Format validation only tells you a postcode looks right. The existence check goes a step further and confirms it is a real, current postcode.

postcodes.io is open source and runs off the ONS Postcode Directory. The public instance is fine for testing, but for production you should run your own so lookups stay on your own infrastructure and you are not subject to anyone else's rate limits. Point the package at it with one environment variable:

POSTCODES_IO_URL=https://postcodes.internal.cladco.co.uk

Lookup results are cached (by default for a day) to avoid repeat requests for the same postcode. The relevant settings:

POSTCODES_IO_URL=https://api.postcodes.io
POSTCODES_IO_TIMEOUT=5
POSTCODES_IO_CACHE_TTL=86400
POSTCODES_IO_CACHE_STORE=

The check relies on Laravel's HTTP client, so make sure guzzlehttp/guzzle is installed (most Laravel apps already have it):

composer require guzzlehttp/guzzle

Testing

composer install
vendor/bin/phpunit

License

Released under the MIT License. See LICENSE.md.