https://github.com/notus-sh/postcode_validator
A simple postcode validator based on the Unicode CLDR project, with an optional integration with ActiveModel.
https://github.com/notus-sh/postcode_validator
geography rails ruby validations
Last synced: 4 months ago
JSON representation
A simple postcode validator based on the Unicode CLDR project, with an optional integration with ActiveModel.
- Host: GitHub
- URL: https://github.com/notus-sh/postcode_validator
- Owner: notus-sh
- License: other
- Created: 2018-03-29T12:29:21.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2025-10-23T09:38:35.000Z (8 months ago)
- Last Synced: 2025-10-23T11:21:10.097Z (8 months ago)
- Topics: geography, rails, ruby, validations
- Language: Ruby
- Size: 68.4 KB
- Stars: 0
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# PostcodeValidator
[](https://github.com/notus-sh/postcode_validator/actions/workflows/unit-tests.yml)
[](https://badge.fury.io/rb/postcode_validator)
A simple postcode validator based on the Unicode CLDR project, with an optional integration with ActiveModel.
## Installation
`PostcodeValidator` is distributed as a gem and available on [rubygems.org](https://rubygems.org/gems/postcode_validator) so you can add it to your `Gemfile` or install it manually with:
```ruby
gem install postcode_validator
```
## Usage
You can use `PostcodeValidator` either as a stand-alone validator or integrated with ActiveModel.
### Stand-alone
```ruby
require 'postcode_validator'
validator = PostcodeValidator.new
validator.valid?('98025', country: 'FR') # True
validator.valid?('AB21 9BG', country: :GB) # True
validator.valid?('AB21 9BG', country: :DE) # False
validator.valid?('', country: 'PA') # True - Panama does not use postcodes.
```
The `:country` option is **required**. It can be anything that respond to `to_s`.
If the supplied `:country` is not a valid [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), a `PostcodeValidator::Error` will be raised.
### ActiveModel integration
```ruby
class Address < ActiveRecord::Base
# With a dedicated helper
validates_as_postcode :zipcode, country: :US
# Or through the generic `validates` class method, mixed with other validators
validates :post_code,
presence: true,
postcode: { allow_nil: true, country: -> { |record| record.country_code } }
end
```
The ActiveModel validator supports the same common arguments others standard validators do (`:if`, `:unless`, `:on`, `:allow_nil`, `:allow_blank` and `:strict`).
The `:country` argument is **required**. It can be either a static value (anything that respond to `to_s`) or a lambda. The lambda will be called with the will be validated record as its first argument.
If the supplied `:country` is not a valid [ISO-3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2), the postcode validation will be skipped (It's your responsability to validate the value of `:country`).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/notus-sh/postcode_validator.