brick / postcode

A PHP library to validate and format postcodes

Brick\Postcode

A PHP library to validate and format postcodes.

Introduction

This library can format and validate postcodes for all countries having a postcode system.

Contributions are welcome, please feel free to open an issue or a pull request if you notice any mistake.

Installation

This library is installable via Composer:

composer require brick/postcode

Requirements

This library requires PHP 7.4 or later.

For PHP 7.1, 7.2 & 7.3 compatibility, you can use version 0.2. Note that these PHP versions are EOL and not supported anymore. If you're still using one of these PHP versions, you should consider upgrading as soon as possible.

Project status & release process

This library is still under development.

The current releases are numbered 0.x.y. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), y is incremented.

When a breaking change is introduced, a new 0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as 0.3.*.

If you need to upgrade to a newer release cycle, check the release history for a list of changes introduced by each further 0.x.0 version.

How to use it

use Brick\Postcode\PostcodeFormatter;

$formatter = new PostcodeFormatter();

$formatter->format('GB', 'WC2E9RZ'); // WC2E 9RZ
$formatter->format('US', '337014313'); // 33701-4313

Notes

• Postcodes are cleaned from optional separators (spaces and dashes) before validation. Misplaced or mismatched separators are not considered an error and will be ignored:

  $formatter->format('GB', 'WC-2E9RZ'); // WC2E 9RZ

• If format() is called with an unknown country code, an UnknownCountryException is thrown:

  $formatter->format('XX', '12345'); // UnknownCountryException

  Note that a country with no postcode system is considered as unknown, even if the country code is a valid ISO 3166 code.

• If format() is called with an invalid postcode for the given country, an InvalidPostcodeException is thrown:

  $formatter->format('GB', 'ABCDEFG'); // InvalidPostcodeException

postcode's Issues

Cleanup

postcode/src/PostcodeFormatter.php

Line 35 in 9fa8925

$postcode = str_replace([' ', '-'], '', $postcode);

I've been running a parcel shipping service for the past 10 years which imports a millions of very badly formatted user provided addresses from eBay and other sources. In my experience, your previous solution of stripping anything other than 0-9A-Z is far more robust. People will provide their postal code using all kinds of characters as separators including "." and even "~" more often than you would imagine.

Compatible with PHP 7.0?

Hi! This looks like a really useful repo but your composer.json requires PHP v7.1, which is not the default version in Ubuntu Xenial (16-04). Any chance it works on PHP v7.0? That might increase the uptake if you could downgrade the composer requirement to PHP v7.0... Thanks.

GB Formatter

The GB formatter currently validates and formats lots of invalid postcodes. The reason being is that only some characters are allowed in some positions.

I have a method that whilst still not 100% accurate is tried and tested over many years and millions of addresses

function verifyPostcode(&$postcode)
    {
        // Permitted letters depend upon their position in the postcode.
        $alpha1 = '[abcdefghijklmnoprstuwyz]'; // Character 1
        $alpha2 = '[abcdefghklmnopqrstuvwxy]'; // Character 2
        $alpha3 = '[abcdefghjkstuw]'; // Character 3
        $alpha4 = '[abehmnprvwxy]'; 
        $alpha5 = '[abdefghjlnpqrstuwxyz]';
        
       
        // Expression for postcodes: AN NAA, ANN NAA, AAN NAA, and AANN NAA
        $pcexp[0] = '/^('.$alpha1.'{1}'.$alpha2.'{0,1}[0-9]{1,2})([0-9]{1}'.$alpha5.'{2})$/';
        // Expression for postcodes: ANA NAA
        $pcexp[1] = '/^('.$alpha1.'{1}[0-9]{1}'.$alpha3.'{1})([0-9]{1}'.$alpha5.'{2})$/';
        // Expression for postcodes: AANA NAA
        $pcexp[2] = '/^('.$alpha1.'{1}'.$alpha2.'[0-9]{1}'.$alpha4.')([0-9]{1}'.$alpha5.'{2})$/';
        // Exception for the special postcode GIR 0AA
        $pcexp[3] = '/^(gir)(0aa)$/';
    
        // Load up the string to check, converting into lowercase and removing spaces
        $postcode = strtolower($postcode);
        $postcode = str_replace (' ', '', $postcode);
    
        // Assume we are not going to find a valid postcode
        $valid = false;
    
        // Check the string against the six types of postcodes
        foreach ($pcexp as $regexp) {
            if (preg_match($regexp, $postcode, $matches)) {
                $postcode = strtoupper ($matches[1] . ' ' . $matches [2]);
                $valid = true;
                break;
            }
        }
    
        return $valid;
    }

Would you be interested in me tidying this up as a new GB formatter? I think it can also be extended to check the district against a defined list to further remove any postcodes which technically use allowed characters in the first two positions but do not represent actual postcode areas. It's actually a fairly short list https://en.wikipedia.org/wiki/List_of_postcode_areas_in_the_United_Kingdom