brick/postcode

A library to format and validate postcodes

Brick\Postcode

, _(*1)

A PHP library to validate and format postcodes., _(*2)

, _(*3)

Introduction

This library can format and validate postcodes for all countries having a postcode system., _(*4)

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

Installation

This library is installable via Composer:, _(*6)

composer require brick/postcode

Requirements

This library requires PHP 8.1 or later., _(*7)

Project status & release process

This library is still under development., _(*8)

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., _(*9)

When a breaking change is introduced, a new 0.x version cycle is always started., _(*10)

It is therefore safe to lock your project to a given release cycle, such as 0.5.*., _(*11)

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., _(*12)

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:, _(*13)

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

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

  $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., _(*15)

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

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