PHPackages                             axlon/laravel-postal-code-validation - 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. axlon/laravel-postal-code-validation

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

axlon/laravel-postal-code-validation
====================================

Worldwide postal code validation for Laravel

v3.9.1(1mo ago)3893.6M↓43.5%32[1 issues](https://github.com/axlon/laravel-postal-code-validation/issues)1MITPHPPHP ^7.2 || ^8.0CI passing

Since Dec 7Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/axlon/laravel-postal-code-validation)[ Packagist](https://packagist.org/packages/axlon/laravel-postal-code-validation)[ RSS](/packages/axlon-laravel-postal-code-validation/feed)WikiDiscussions 4.x Synced 3w ago

READMEChangelog (7)Dependencies (18)Versions (32)Used By (1)

Laravel Postal Code Validation
==============================

[](#laravel-postal-code-validation)

Adds postal code validation to Laravel, based on [Google's libaddressinput](https://github.com/google/libaddressinput).

[![Codecov](https://camo.githubusercontent.com/4c2df0068b9276ce2490a33bec0fc92d590e8caed4800873c1dcc8010bc04b22/68747470733a2f2f636f6465636f762e696f2f67682f61786c6f6e2f6c61726176656c2d706f7374616c2d636f64652d76616c69646174696f6e2f67726170682f62616467652e7376673f746f6b656e3d6e6c726d735344356f70)](https://codecov.io/gh/axlon/laravel-postal-code-validation)[![Downloads](https://camo.githubusercontent.com/08ffe7b862a692fa3f03fcbc8bb7b59e14f112616cfd283a7a12de478cdca87f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61786c6f6e2f6c61726176656c2d706f7374616c2d636f64652d76616c69646174696f6e)](https://packagist.org/packages/axlon/laravel-postal-code-validation)[![Latest version](https://camo.githubusercontent.com/84e775c4c086dccf34931e7ef664425aee83649aa912861f4691bdd8e107e867/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61786c6f6e2f6c61726176656c2d706f7374616c2d636f64652d76616c69646174696f6e)](https://github.com/axlon/laravel-postal-code-validation/releases)[![License](https://camo.githubusercontent.com/af3ea783c9d505cf9b3ff9e3cbe2613b6573dba47252ef3d41055744ec6a8c21/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f61786c6f6e2f6c61726176656c2d706f7374616c2d636f64652d76616c69646174696f6e)](LICENSE.md)

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
    - [Available rules](#available-rules)
    - [Fluent API](#fluent-api)
    - [Adding an error message](#adding-an-error-message)
    - [Manually validating](#manually-validating)
    - [Overriding rules](#overriding-rules)
- [License](#license)
- [Attribution](#attribution)

Requirements
------------

[](#requirements)

This package has the following requirements:

- PHP 8.2 or greater
- Laravel 12 or greater

Installation
------------

[](#installation)

You can install this package with Composer, by running the command below:

```
composer require axlon/laravel-postal-code-validation
```

If you have package discovery enabled, that's it, continue to the [usage](#usage) section. If you want to register the package manually, you can do this by adding the following line to your `config/app.php` file:

```
'providers' => [
   ...
   Axlon\PostalCodeValidation\ValidationServiceProvider::class,
   ...
],
```

Usage
-----

[](#usage)

Postal code validation perfectly integrates into your Laravel application, you can use it just like you would any framework validation rule.

### Available rules

[](#available-rules)

This package adds the following validation rules:

#### postal\_code:foo,bar,...

[](#postal_codefoobar)

The field under validation must be a valid postal code in at least one of the given countries. Arguments must be countries in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.

```
'postal_code' => 'postal_code:NL,DE,FR,BE'
```

#### postal\_code\_with:foo,bar,...

[](#postal_code_withfoobar)

The field under validation must be a postal code in at least one of the countries in the given fields *only if* at least one of the specified fields is present.

```
'billing.country' => 'required|string|max:2',
...
'shipping.country' => 'nullable|string|max:2',
'shipping.postal_code' => 'postal_code_with:billing.country,shipping.country'
```

### Fluent API

[](#fluent-api)

If you prefer using a fluent object style over string based rules, that's also available:

```
'postal_code' => [
    PostalCode::for('NL')->or('BE'),
],
```

The same goes for the `postal_code_with` rule:

```
'billing.country' => 'required|string|max:2',
...
'shipping.country' => 'nullable|string|max:2',
'shipping.postal_code' => [
    PostalCode::with('billing.country')->or('shipping.country')
],
```

### Adding an error message

[](#adding-an-error-message)

To add a meaningful error message, add the following lines to `resources/lang/{your language}/validation.php`:

```
'postal_code' => 'Your message here',
'postal_code_with' => 'Your message here',
```

The following placeholders will be automatically filled for you:

PlaceholderDescription:attributeThe name of the field that was under validation:countriesThe countries that were validated against (e.g. `NL, BE`)\*:examplesExamples of allowed postal codes (e.g. `1234 AB, 4000`)\*\*The `:countries` and `:examples` placeholders may be empty if no valid countries are passed.

### Manually validating

[](#manually-validating)

If you want to validate postal codes manually outside of Laravel's validation system, you can call the validator directly, like so:

```
PostalCodes::passes($country, $postalCode); // returns a boolean
```

### Overriding rules

[](#overriding-rules)

Depending on your use case you may want to override the patterns used to validate postal codes for a country. You can do this by adding the code below in a central place in your application (e.g. a service provider):

```
PostalCodes::override('country', '/your pattern/');

// You can also pass overrides as an array

PostalCodes::override([
    'country 1' => '/pattern 1/',
    'country 2' => '/pattern 2/',
]);
```

**Important**: If you believe there is a bug in one of the patterns that this package ships with, please create an [issue](https://github.com/axlon/laravel-postal-code-validation/issues/new) in the issue tracker.

License
-------

[](#license)

This software is licenced under the [MIT license](LICENSE.md).

Attribution
-----------

[](#attribution)

This software contains data derived from Google's Address Validation Metadata. The original data is provided by [Google](https://github.com/google/libaddressinput) and is licensed under the [CC-BY 4.0 license](https://creativecommons.org/licenses/by/4.0/).

### Modifications

[](#modifications)

- Only data relevant to postal code validation is included
- Regular expressions found in the data are adjusted to be compatible with PHP's regex engine
- The resulting data is converted into PHP resource files

###  Health Score

68

—

FairBetter than 99% of packages

Maintenance91

Actively maintained with recent releases

Popularity62

Solid adoption and visibility

Community24

Small or concentrated contributor base

Maturity78

Established project with proven stability

 Bus Factor1

Top contributor holds 89.4% 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 ~89 days

Recently: every ~56 days

Total

32

Last Release

25d ago

Major Versions

v1.4.1 → v2.0.02019-07-06

v2.1.1 → v3.0.02020-08-31

v3.9.1 → 4.x-dev2026-06-29

PHP version history (6 changes)v1.0.0PHP ^7.0

v1.3.0PHP ^7.1.3

v1.3.1PHP ^7.1

v3.0.0PHP ^7.2

v3.2.0PHP ^7.2 || ^8.0

4.x-devPHP >=8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3661474?v=4)[Choraimy Kroonstuiver](/maintainers/axlon)[@axlon](https://github.com/axlon)

---

Top Contributors

[![axlon](https://avatars.githubusercontent.com/u/3661474?v=4)](https://github.com/axlon "axlon (152 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (6 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![schonhoff](https://avatars.githubusercontent.com/u/42345405?v=4)](https://github.com/schonhoff "schonhoff (3 commits)")[![realrashid](https://avatars.githubusercontent.com/u/15607685?v=4)](https://github.com/realrashid "realrashid (1 commits)")[![villfa](https://avatars.githubusercontent.com/u/2891564?v=4)](https://github.com/villfa "villfa (1 commits)")[![jpscharf](https://avatars.githubusercontent.com/u/1039984?v=4)](https://github.com/jpscharf "jpscharf (1 commits)")[![Luke-Shepp](https://avatars.githubusercontent.com/u/35956374?v=4)](https://github.com/Luke-Shepp "Luke-Shepp (1 commits)")[![mikemand](https://avatars.githubusercontent.com/u/745184?v=4)](https://github.com/mikemand "mikemand (1 commits)")

---

Tags

laravellaravel-packagelumenpostal-codevalidationzip-codelaravelvalidationlumenzip codepostal-codepost code

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/axlon-laravel-postal-code-validation/health.svg)

```
[![Health](https://phpackages.com/badges/axlon-laravel-postal-code-validation/health.svg)](https://phpackages.com/packages/axlon-laravel-postal-code-validation)
```

###  Alternatives

[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77922.3M186](/packages/laravel-mcp)[propaganistas/laravel-disposable-email

Disposable email validator

6023.0M7](/packages/propaganistas-laravel-disposable-email)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[sandermuller/laravel-fluent-validation

Fluent validation rule builders for Laravel

20720.5k4](/packages/sandermuller-laravel-fluent-validation)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M246](/packages/laravel-ai)[moonshine/moonshine

Laravel administration panel

1.3k253.1k86](/packages/moonshine-moonshine)

PHPackages © 2026

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