README

A postcode validator for Laravel.

Handles UK postcodes including the Isle of Man and the Channel Islands.

Designed to be used with Laravel's built-in form validation but also supports manual usage.

It works with Laravel versions 10 to 12.

Features

• Checks postcode against an external API
• Uses ONS and Ordnance Survey postcode data
• Determines postcode country
• Supports England, Wales, Scotland and Northern Ireland
• Supports the Isle of Man and the Channel Islands
• Falls back to regex validation if the external API is unavailable
• Allows countries or areas to be excluded

Installation

Install with composer:

composer require chisnall/postcode

Status Codes

Usage - Form Validation

The form validation messages can be customised from the status code returned.

There is a catch-all message: input.postcode
However, it is recommended to use the status code specific messages.
This provides a better user experience.

Use this in the controller which handles the form submission:

$validated = $request->validate([
    'input' => 'required|postcode',
],
[
    'input.required' => 'Please enter your postcode.',
    'input.postcode' => 'This will catch all errors if specific status codes are not handled.',
    'input.postcode.excluded' => 'The postcode or area is excluded.',
    'input.postcode.not_found' => 'The postcode is not found.',
    'input.postcode.not_valid' => 'The postcode format is not valid.',
    'input.postcode.service_error' => 'The external API is unavailable and regex fallback is disabled.',
]);

The priority in which the form messages are shown is:

1. Specific status code message (if defined)
2. The catch-all message (if defined)
3. Default system message

Configuration

The default configuration can be changed using ENV variables.

You may not be legally able to provide your services to certain countries.
Or you ship physical goods and the shipping cost is prohibitive to certain areas.

In these cases you can exclude countries or areas.

For form validation, this is done in the global configuration though ENV variables.

Notes

1. If you want to test the 503 service error, set the API endpoint so it is unreachable. For example, a path in localhost.
2. The list of countries to exclude is case-insensitive.
3. The list of areas to exclude is also case-insensitive.
4. The area is the first part of the postcode. For example, SW1A 1AA is in the area SW.

Usage - Manual

Validation can be done manually as a facade pattern.

Each facade call generates a new instance rather than reusing a cached one.

Global configuration from the ENV variables still applies when using the facade, but can be overridden using the facade methods.

Basic usage:

$postcode = Postcode::lookup('SW1A 1AA');

That will return an instance of the postcode object.

These methods are available and can be chained:

For example:

$postcode = Postcode::forceRegex()->lookup('SW1A 1AA')->getStatus();

These getters are available:

The getResult method returns an array with the following keys:

The admin district is "unknown" if the regex service is used.

Regex Fallback

If the external API is unavailable, the regex fallback will be used, unless disabled.

The regex can also be forced, which will disable the external API.

Caveats regarding the regex service:

1. Unable to determine if a postcode actually exists. Only if the format is correct.
2. Unable to determine the admin district. Always returns "unknown".
3. Cannot reliably determine a country. This uses the area part of the postcode and some postcode areas overlap countries.
   For example:
   CH (Chester) - overlaps England and Wales.
   SY (Shrewsbury) - overlaps England and Wales.
   TD (Galashiels) - overlaps Scotland and England.

This is where the external API should be used to reliably determine if the postcode actually exists and to get the correct country.

Publish

The configuration can be published to allow further customisation.

artisan vendor:publish --tag=postcode-config

The translations can be published to allow further customisation.

artisan vendor:publish --tag=lang