Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/axlon/laravel-postal-code-validation
Worldwide postal code validation for Laravel and Lumen
https://github.com/axlon/laravel-postal-code-validation
laravel laravel-package lumen postal-code validation zip-code
Last synced: about 2 months ago
JSON representation
Worldwide postal code validation for Laravel and Lumen
- Host: GitHub
- URL: https://github.com/axlon/laravel-postal-code-validation
- Owner: axlon
- License: mit
- Created: 2018-12-06T17:58:43.000Z (almost 6 years ago)
- Default Branch: 3.x
- Last Pushed: 2024-03-12T16:25:44.000Z (6 months ago)
- Last Synced: 2024-07-18T21:48:27.197Z (2 months ago)
- Topics: laravel, laravel-package, lumen, postal-code, validation, zip-code
- Language: PHP
- Homepage:
- Size: 136 KB
- Stars: 366
- Watchers: 4
- Forks: 29
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Laravel Postal Code Validation
Worldwide postal code validation for Laravel, based on Google's Address Data Service.
- [Requirements](#requirements)
- [Installation](#installation)
- [Lumen](#lumen)
- [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)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)
## Requirements
This package has the following requirements:
- PHP 7.2 or higher
- Laravel (or Lumen) 5.5 or higher
| Laravel / Lumen version | Package version |
|-------------------------|-----------------|
| 5.1 - 5.4 | [2.x](https://github.com/axlon/laravel-postal-code-validation/tree/2.x) |
| 5.5 and greater | 3.x |
## Installation
You can install this package with Composer, by running the command below:
```bash
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:
```php
'providers' => [
...
Axlon\PostalCodeValidation\ValidationServiceProvider::class,
...
],
```
### Lumen
If you are using Lumen, register the package by adding the following line to your `bootstrap/app.php` file:
```php
$app->register(Axlon\PostalCodeValidation\ValidationServiceProvider::class);
```
## Usage
Postal code validation perfectly integrates into your Laravel application, you can use it just like you would any
framework validation rule.
### Available rules
This package adds the following validation rules:
#### postal_code:foo,bar,...
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.
```php
'postal_code' => 'postal_code:NL,DE,FR,BE'
```
#### postal_code_with:foo,bar,...
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.
```php
'billing.country' => 'required|string|max:2',
...
'shipping.country' => 'nullable|string|max:2',
'shipping.postal_code' => 'postal_code_with:billing.country,shipping.country'
```
### Fluent API
If you prefer using a fluent object style over string based rules, that's also available:
```php
'postal_code' => [
PostalCode::for('NL')->or('BE'),
],
```
The same goes for the `postal_code_with` rule:
```php
'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
To add a meaningful error message, add the following lines to `resources/lang/{your language}/validation.php`:
```php
'postal_code' => 'Your message here',
'postal_code_with' => 'Your message here',
```
The following placeholders will be automatically filled for you:
Placeholder | Description
------------|------------
:attribute | The name of the field that was under validation
:countries | The countries that were validated against (e.g. `NL, BE`)*
:examples | Examples 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
If you want to validate postal codes manually outside of Laravel's validation system, you can call the validator
directly, like so:
```php
PostalCodes::passes($country, $postalCode); // returns a boolean
```
### 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):
```php
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.
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Credits
- [Choraimy Kroonstuiver](https://github.com/axlon)
- [All contributors](https://github.com/axlon/laravel-postal-code-validation/contributors)
## License
This open-source software is licenced under the [MIT license](LICENSE.md). This software contains code generated from
Google's Address Data Service, more information on this service can be found
[here](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata).