validation_kit

ActiveModel validators for email addresses, phone numbers, postal codes, and mixed-case text.

Add the gem to your Gemfile:

gem "validation_kit"

The validators are available in any class that includes ActiveModel::Validations, including ActiveRecord models. If your app defines its own validator with the same name (e.g. app/validators/email_validator.rb), yours is used instead.

Validates that an attribute is an email address.

class Person < ActiveRecord::Base
  validates :email, email: true
end

Person.new(email: "Bob").valid?            # => false
Person.new(email: "joe@foobar.com").valid? # => true

Addresses are limited to 254 characters, and 64 before the @ (RFC 5321). To check an address outside a model, use ValidationKit::EmailValidator.valid_address?("joe@foobar.com").

Validates that a string isn't all capitals or all lowercase. Values with fewer than three letters that have a case are skipped, so initials, digits, and scripts without case (e.g. Chinese) never fail.

class Person < ActiveRecord::Base
  validates :first_name, mixed_case: true
end

Person.new(first_name: "BOB").valid? # => false, "First name cannot be in all caps"
Person.new(first_name: "bob").valid? # => false, "First name cannot be in all lowercase"
Person.new(first_name: "Bob").valid? # => true

Strict validation for phone numbers in the United States (US), Canada (CA), and Australia (AU).

class Person < ActiveRecord::Base
  validates :phone, phone: { country: "US", set: true }, allow_blank: true
end

A US or Canadian number may end with an extension, which needs a marker in front of its digits: any letter (as in x, ext or extension), or #, ＃ or № ("212-555-1234 ext 5"). Digits right after the number with no marker, as in "212-555-12345", make it invalid.

Strict validation for postal and ZIP codes in the United States (US), Canada (CA), the United Kingdom (UK or GB), Australia (AU), and New Zealand (NZ).

class Person < ActiveRecord::Base
  validates :postal_code, postal_code: { country: "CA", set: true }, allow_blank: true
end

The phone and postal code validators need a country. Country codes are case-insensitive ("CA", "ca", or :CA), and validation is skipped when the country isn't supported.

# A fixed country code, as a string or a two-letter symbol
validates :phone, phone: { country: "CA" }
validates :phone, phone: { country: :ca }

# The name of a method on your model that returns the country code
validates :phone, phone: { country: :billing_country }

# Neither: the validator calls your model's country method
validates :phone, phone: true

A symbol is a method name if your model has that public method; otherwise a two-letter symbol is a country code. Any other symbol (such as a misspelled method name) raises ArgumentError when validating, rather than skipping validation. Two things that check can't catch: a misspelled two-letter method name is read as a country code (and skipped if that country isn't supported), and with allow_nil: or allow_blank: it only runs once the attribute has a value.

Errors are added with standard types, so the usual ActiveModel tools work:

person.errors.of_kind?(:email, :invalid)        # email, phone, postal code
person.errors.of_kind?(:first_name, :all_caps)  # mixed case (also :all_lowercase)

of_kind? checks the attribute and error type. added? also compares the error's options, and mixed case errors carry an item: option (the attribute's name, for messages that use %{item}; see Translation keys for how it's chosen), so for them added? only matches if you pass the same item:.

Pass message: (or all_caps: / all_lowercase: for mixed case) for a custom message, or translate it like any other Rails validation error:

en:
  activerecord:
    errors:
      models:
        person:
          attributes:
            email:
              invalid: "doesn’t look like an email address"
            first_name:
              all_caps: "can’t be all capitals"

Like Rails’ own messages, these leave out the attribute’s name, because full_messages adds it: "First name can’t be all capitals". Use activemodel instead of activerecord for classes that aren't ActiveRecord models. The gem includes English and French messages for the mixed case errors.

Each validator adds an error of the type below. Rails looks up its message in this order, using the first key it finds. These are the keys for an ActiveRecord model Person; use activemodel instead of activerecord for other ActiveModel classes:

1. activerecord.errors.models.person.attributes.<attribute>.<type>
2. activerecord.errors.models.person.<type>
3. activerecord.errors.messages.<type>
4. errors.attributes.<attribute>.<type>
5. errors.messages.<type>

A message: option (or all_caps: / all_lowercase:) skips the lookup.

Like Rails' own messages, the mixed case messages leave out the attribute's name, which full_messages adds: "First name cannot be in all caps". A custom message or translation can include it as %{item}: the attribute's translation at activerecord.attributes.person.<attribute>, then the attribute_name: option, then the humanized attribute name.

• Email, mixed case, and postal code validators: Paul Schreiber, 2010–2011.
• Phone validator: written by Kristina Lim, copyright © 2008 Syndeo Media. Paul Schreiber added US and Canada support (September 2010) and extension support (November 2010). It is named after, and was originally built on, Jerrod Blavos's validates_as_phone plugin.
• Gem: co-authored by Wes Morgan.

Released under the MIT License. See LICENSE.