A PHP library to validate and format postcodes
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A PHP library to validate and format postcodes.

Build Status Coverage Status Latest Stable Version License


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.


This library is installable via Composer. Just run:

composer require brick/postcode

or manually define the following requirement in your composer.json file:

    "require": {
        "brick/postcode": "0.2.*"


This library requires PHP 7.1 or later.

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.2.*.

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


  • 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