NAME

HTML::CheckArgs - Validate data passed to web applications

SYNOPSIS

  use HTML::CheckArgs;

  my @banned_domains = ( 'whitehouse.gov', 'gop.com' );
  my $config = {
    email_address => {
      as        => 'email',
      required  => 1,
      label     => 'Email Address',
      order     => 1,
      params    => { banned_domains => \@banned_domains },
    },
        num_tickets => {
          as        => 'integer',
          required  => 1,
          label     => 'Number of Tickets',
          order     => 2,
          params    => { min => 0, max => 10 },
        },
  };

  my $handler = HTML::CheckArgs->new( $config );
  my ( $error_message, $error_code );
  foreach my $field ( sort { $config->{$a}{order} <=> $config->{$b}{order} } keys %$config ) {
    if ( $handler->validate( $field, $ARGS{$field} ) ) {
      $ARGS{$field} = $handler->value;
    } else {
      push( @$error_message, $handler->error_message );
      push( @$error_code, $handler->error_code );
    }
  }

DESCRIPTION

HTML::CheckArgs validates data passed to web applications. Architecturally, it is based on CGI::Untaint, and we follow that model of extensibility as well.

Most of the work is done in the $config hashref. $config's keys are the fieldnames to be validated. The following parameters can be passed in:

as:

Name of the module that should be used to validate the data. The following modules are available:

cc_expiration

Passed a date string in the format YYYYMM, will determine if the string is valid, and if the date is in the future.

cc_number

Validates credit card numbers based on Luhn checksum.

country

Validates 2-character country code or full country name per Georgraphy::Countries.

date

Passed a date string, a format, and a regex of the format, will determine if the string represents a valid date.

dollar

Validates a dollar figure. Can optionally specify minimum and maximum vaues to check against.

email

Uses Email::Valid to check email addresses. Can optionally specify no administrative addresses (e.g. root@domain.com), no government addresses (me@dot.gov), or no addresses from a list of domains passed to the module.

integer

Determines if number is a valid interger. Can optionally specify minimum and maximum values to check against.

option

Determines if a value is a member of a list passed to the module. Useful when the form input is a select or a radio button.

phone

Determines if a string is valid phone number. Only does strict validation on US phone numbers, but other formats could be included.

postal_code

Validates a postal or ZIP code. Only does strict validation on US ZIP codes.

state

Validates a two-character state abbrieviation or full name. Only does strict validation on US values.

string

A catch-all class. Can format the string per the routines in HTML::FormatData, and can also do regex checks, checks on the number of character, number of words, etc.

url

Uses URL::Find to validate the URL. Can optionally check the URL via LWP::UserAgent.

required:

Set to 1 if the field is required. Default is 0 (not required).

order:

The order the fields should be evaluated in.

label:

Field name label to be used for user error messages.

private:

A flag that can be passed to your error reporting instrument as an indicator of whether the error should be displayed to the user. Default is 0.

params:

Extra parameters that should be passed to the specific module validating the data. Passing parameters to a module that does not support use this feature will cause it to 'die'. Passing unknown parameters will also cause it to 'die'.

noclean:

Determines if the value returned should be cleaned up if the value is validated. Set to 1 to preserve the original value. Default is 0 (value will be cleaned). Some modules do not support cleaning the input. If you pass 'noclean' to one of these modules, it will 'die'.

untaint:

Set to 1 if you want the value to be untainted. Default is 0 (don't untaint).

Please note that all untainting is done after a successful is_valid call to the specific validation module. If a value is_valid, we assume it is safe to untaint it without further checks, so the regex pattern /(.*)/s is used. If you want more rigorous checking, it is advisable that you improve the is_valid code or do alternate checks before untainting the value.

METHODS

new( $config [, $alt_messages ] )

This method creates a new HTML::CheckArgs object, using the $config hashref. Returns the blessed object.

An optional $alt_messages parameter -- a hashref of alternate error messages keyed error codes -- can be used to override the default error messages passed back from the modules that perform the actual verification.

accessors

The following data can be get/set:

error_code

Each error registered has a unique code attached to it, in the format name_of_module_xx, where xx is a numerical code.

error_message

Each error also has a text message suitable for presentation to the user. Creating a custom lookup list based on error codes is certainly possible if you wish to override the default values.

value

If there is an error, 'value' retains the value originally passed in. Otherwise, value has the original value or a cleaned-up version depending on the $config hashref settings.

config

This gets the $config hashref value for a particular key. This is then passed to the specific module called to validate a specific value.

alt_message

This gets the $alt_messages hashref value for a particular key. This is then used to override the default error message associated with a particular code.

validate( $field, $value )

Passes $field, $value and field-specific $config info to the proper module for validation.

Returns true if validation was successful, otherwise false.

AUTHOR

Eric Folley, <eric@folley.net>

COPYRIGHT AND LICENSE

Copyright 2004-2005 by Eric Folley

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.