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