PHPackages                             lemonade/component\_postcode - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. lemonade/component\_postcode

ActiveLibrary[Validation & Sanitization](/categories/validation)

lemonade/component\_postcode
============================

A lightweight PHP library for validating and formatting international postal codes (ZIP/PSC).

v3.0.0(7mo ago)12MITPHPPHP >=8.1 <8.5

Since Sep 30Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/johnnyxlemonade/component_postcode)[ Packagist](https://packagist.org/packages/lemonade/component_postcode)[ RSS](/packages/lemonade-component-postcode/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (3)Versions (5)Used By (0)

Lemonade Postcode
=================

[](#lemonade-postcode)

[![Packagist](https://camo.githubusercontent.com/fb41d334a1f64a8f01eb8ebbe676f4eb9cb49130dc798146d6cc6b3381b830a1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c656d6f6e6164652f636f6d706f6e656e745f706f7374636f64652e737667)](https://packagist.org/packages/lemonade/component_postcode)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/9007d447c89b966eefd6475133b31d3317c885e95fda2cc225767b68e8f25097/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312532302d2d253230382e352d626c7565)](https://camo.githubusercontent.com/9007d447c89b966eefd6475133b31d3317c885e95fda2cc225767b68e8f25097/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312532302d2d253230382e352d626c7565)[![Tests](https://camo.githubusercontent.com/3ab4882a1b7d64e5eb5168ad0b0b9cdfd53f59f114ee5f727958504214a5789c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d70617373696e672d627269676874677265656e2e737667)](vendor/bin/phpunit)[![Coverage](https://camo.githubusercontent.com/b3545ae1bcdb4ea486f71f87b43001e82dd21933bc8035d44601706c851265da/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d3130302532352d627269676874677265656e2e737667)](#)

A lightweight PHP library for validating and formatting international postal codes (ZIP/PSC).
Provides country-specific formatters, unified exception handling, and clear error codes for integration in forms, APIs, and e-commerce applications.

---

✨ Features
----------

[](#-features)

- ✅ Validation and normalization of postal codes for multiple countries
- ✅ Country-specific formatters (`CZ`, `SK`, `DE`, `GB`, `FR`, `IT`, `…`)
- ✅ Unified API via `PostcodeFormatter`
- ✅ Strict typing (PHP 8.1+)
- ✅ Consistent error handling with `PostcodeException` and `PostcodeErrorCode` enum
- ✅ Ready for localization (`messageKey()` for translation keys)
- ✅ PSR-4 autoloading
- ✅ PHPUnit test coverage
- ✅ PHPStan **Level 10 + Strict Rules**
- ✅ Verified with **100% PHPUnit coverage**
- ✅ Includes support for all **249 ISO 3166-1 alpha-2 country codes**

---

🚀 Installation
--------------

[](#-installation)

```
  composer require lemonade/component_postcode
```

---

🔧 Usage
-------

[](#-usage)

```
use Lemonade\Postcode\PostcodeFormatter;
use Lemonade\Postcode\CountryCode;
use Lemonade\Postcode\Exception\PostcodeException;
use Lemonade\Postcode\FormatterRegistry;

// initialize with default formatters
$registry  = new FormatterRegistry();          // IMMUTABLE REGISTRY
$formatter = new PostcodeFormatter($registry); // READONLY REFERENCE

try {
    $postcode = $formatter->format(CountryCode::CZ, '12000');
    // "120 00"
} catch (PostcodeException $e) {
    echo $e->getValue() . ' is invalid: ' . $e->getMessage();
}
```

➕ Custom Formatters
-------------------

[](#-custom-formatters)

You can easily extend the library with your own country-specific formatters.
Simply implement `CountryPostcodeFormatter` and register it via `FormatterRegistry`.

Example with an **anonymous class**:

```
use Lemonade\Postcode\CountryCode;
use Lemonade\Postcode\CountryPostcodeFormatter;
use Lemonade\Postcode\Exception\InvalidPostcodeException;
use Lemonade\Postcode\FormatterRegistry;
use Lemonade\Postcode\PostcodeFormatter;

$registry = new FormatterRegistry();

// Add custom formatter for Antarctica (AQ)
$registry = $registry->register(CountryCode::AQ, new class implements CountryPostcodeFormatter {
    public function format(string $postcode): string
    {
        if (preg_match('/^[0-9]{4}$/', $postcode) !== 1) {
            throw new InvalidPostcodeException($postcode);
        }
        return strtoupper($postcode);
    }
});

$formatter = new PostcodeFormatter($registry);

try {
    echo $formatter->format(CountryCode::AQ, '1231');
    // outputs "1231"
} catch (InvalidPostcodeException $e) {
    echo $e->getValue() . ' is invalid: ' . $e->getMessage();
}
```

---

📦 Country Formatters
--------------------

[](#-country-formatters)

Each country has its own `Formatter` class under `Lemonade\Postcode\Formatter`.
Examples:

- **CZ\_Formatter** – `12000` → `120 00`
- **SK\_Formatter** – `81101` → `811 01`
- **PL\_Formatter** – `01001` → `01-001`
- **GB\_Formatter** – `SW1A1AA` → `SW1A 1AA`
- **LT\_Formatter** – supports both `12345` and `LT12345`

---

⚠️ Exceptions
-------------

[](#️-exceptions)

All errors are reported using dedicated exception classes.
This makes it easy to distinguish between invalid input and unsupported countries.

- **`InvalidPostcodeException`**
    Thrown when the postcode does not match the expected format
    or contains an unsupported value.
    Example: `"ABCDE"` for `CZ`.
- **`UnknownCountryException`**
    Thrown when trying to format a postcode for an unsupported
    or unrecognized ISO 3166-1 alpha-2 country code.
    Example: `"XX"`.
- **`UnsupportedCountryException`**
    Thrown when the country code is valid, but no formatter is registered for it.

    Example: `"AQ"` (valid ISO code, but not implemented in `FormatterMapper`)..

All exceptions implement the `PostcodeException` interface, which provides:

- `getValue()` → returns the original input (`postcode` or `country`)
- `getCode()` → stable numeric error code (`PostcodeErrorCode`)
- `getMessage()` → translation key for localization

---

📖 Changelog
-----------

[](#-changelog)

All notable changes are documented in the [CHANGELOG.md](CHANGELOG.md).

---

🧪 Development & Testing
---------------------------

[](#-development--testing)

This package is fully covered by PHPUnit tests and verified with **PHPStan Level 10**.

Run PHPUnit tests:

```
  composer install
  vendor/bin/phpunit
  vendor/bin/phpunit -c vendor/lemonade/component_postcode/phpunit.xml --bootstrap vendor/autoload.php
```

Run static analysis (PHPStan Level 10 + Strict Rules):

```
  vendor/bin/phpstan analyse vendor/lemonade/component_postcode/src \
    --configuration=vendor/lemonade/component_postcode/phpstan.neon.dist \
    --memory-limit=1G
```

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance75

Regular maintenance activity

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

229d ago

Major Versions

v1.0.0 → v2.0.02025-10-01

v2.0.0 → v3.0.02025-10-01

### Community

Maintainers

![](https://www.gravatar.com/avatar/c700bffd26445bd0b6d5a6de15fade3c711fa33c924c1f91ef494dac3e44f8c6?d=identicon)[johnnyxlemonade](/maintainers/johnnyxlemonade)

---

Top Contributors

[![johnnyxlemonade](https://avatars.githubusercontent.com/u/3079458?v=4)](https://github.com/johnnyxlemonade "johnnyxlemonade (10 commits)")

---

Tags

formattervalidatorpostalzipcodepostcodelemonade

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/lemonade-component-postcode/health.svg)

```
[![Health](https://phpackages.com/badges/lemonade-component-postcode/health.svg)](https://phpackages.com/packages/lemonade-component-postcode)
```

###  Alternatives

[respect/validation

The most awesome validation engine ever created for PHP

5.9k37.4M383](/packages/respect-validation)[seld/jsonlint

JSON Linter

1.3k217.8M205](/packages/seld-jsonlint)[composer/spdx-licenses

SPDX licenses list and validation library.

1.4k184.2M25](/packages/composer-spdx-licenses)[ronanguilloux/isocodes

PHP library - Validators for standards from ISO, International Finance, Public Administrations, GS1, Book and Music Industries, Phone numbers & Zipcodes for many countries

8013.3M23](/packages/ronanguilloux-isocodes)[opis/json-schema

Json Schema Validator for PHP

64736.9M186](/packages/opis-json-schema)[laminas/laminas-validator

Validation classes for a wide range of domains, and the ability to chain validators to create complex validation criteria

15644.9M188](/packages/laminas-laminas-validator)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)