brick / postcode
A library to format and validate postcodes
Fund package maintenance!
BenMorel
Installs: 820 507
Dependents: 1
Suggesters: 0
Security: 0
Stars: 82
Watchers: 7
Forks: 16
Open Issues: 3
Requires
- php: ^7.4 || ^8.0
Requires (Dev)
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^9.0
- vimeo/psalm: 5.26.1
README
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