README

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

✅ 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

  composer require lemonade/component_postcode

🔧 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

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

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

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

All notable changes are documented in the CHANGELOG.md.

🧪 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

lemonade / component_postcode

Maintainers

Details