FormValidator is a form validation libary derived from Perl’s Data::FormValidator module. When you are coding a web application one of the most tedious though crucial tasks is to validate user’s input (usually submitted by way of an HTML form). You have to check that each required field is present and that all fields have valid data. (Does the phone input looks like a phone number? Is this a plausible email address? For a simple form, this is not really a problem but as forms get more complex and you code more of them this task becames really boring and tedious.

FormValidator lets you define profiles which declare the required fields and their format. When you are ready to validate the user’s input, you tell FormValidator the profile to apply to the users data and you immediately know the valid, missing, invalid, and unknown fields. Instance variables are filled with the results of the validation run so you know which fields failed what tests.

For the past seven years, FormValidator has been tested heavily in the real world. It has been used alongside the Sinatra web framework for form validation purposes and outside of the web domain to validate environmental instrument data. It has also been used for data validation in a MUD framework. The conclusion from these real world tests is that it works well for a variety of validation requirements and should be free of any critical issues.

To create a FormValidator object, do one of the following:

# profile data will be fed in from a hash
fv = FormValidator.new
# profile data will be read from someprofile.rb
fv = FormValidator.new("someprofile.rb")

In the first case, a profile hash and form hash must be specified to the validate method(see below). In the second case, the input profile is loaded from somefile.rb, and a label would be given to the validate method to indicate which profile to apply to the form. If this sounds confusing, see the Usage section below, and you’ll get the idea.

For all allowable profile methods, please see FormValidator::InputProfile.

$ gem install formvalidator

The simplest and most common usage is to specify the profile in a hash and pass it along with the form data into the FormValidator::validate method.

require "formvalidator"

form = {
  "phone" => "home phone: (123) 456-7890",
  "zip"   => "32608-1234",
  "rogue" => "some unknown field"
}

profile = {
  :required      => [:name, :zip],
  :optional      => :phone,
  :filters       => :strip,
  :field_filters => { :phone => :phone },
  :constraints   => {
    :phone => :american_phone,
    :zip   => [
      :zip,
      {
        :name       => "pure_digit",
        :constraint => /^\d+$/
      }
    ]
  }
}

fv = FormValidator.new
fv.validate(form, profile)
fv.valid   # <== {"phone"=>"  (123) 456-7890"}
fv.invalid # <== {"zip"=>["pure_digit"]}
fv.missing # <== ["name"]
fv.unknown # <== ["rogue"]

require "formvalidator"

form = {
  "phone" => "home phone: (123) 456-7890",
  "zip"   => "32608-1234",
  "rogue" => "some unknown field"
}

fv = FormValidator.new("profile_file.rb")
fv.validate(form, :testinfo)

Contents of profile_file.rb
{
:testinfo =>
  {
    :required    => [:name, :zip],
    :optional    => [:arr, :phone],
    :filters     => :strip,
    :field_filters => { :phone => :phone },
    :constraints => {
      :phone => :american_phone,
      :zip => [
                :zip,
                {
                  :name       => "pure_digit",
                  :constraint => /^\d+$/
                }
              ]
    }
  }
}

When placing profile data in a separate file, you must tag each profile with a label such as testinfo in the example above. This allows multiple profiles to be stored in a single file for easy access.

FormValidator is written by Travis Whitton and is based on Perl’s Data::FormValidator, which was written by Francis J. Lacoste. The credit card validation portion was adapted from MiniVend, which is written by Bruce Albrecht.