]>
Dogcows Code - chaz/p5-CGI-Ex/blob - lib/CGI/Ex/Validate.pm
1 package CGI
::Ex
::Validate
;
5 CGI::Ex::Validate - another form validator - but it does javascript in parallel
9 ###----------------------------------------------------------------###
10 # Copyright 2007 - Paul Seamons #
11 # Distributed under the Perl Artistic License without warranty #
12 ###----------------------------------------------------------------###
28 $QR_EXTRA = qr/^(\w+_error|as_(array|string|hash)_\w+|no_\w+)/;
29 @UNSUPPORTED_BROWSERS = (qr/MSIE\s+5.0\d/i);
31 ###----------------------------------------------------------------###
35 my $self = ref($_[0]) ? shift : {@_};
37 $self = {%DEFAULT_OPTIONS, %$self} if scalar keys %DEFAULT_OPTIONS;
39 return bless $self, $class;
42 ###----------------------------------------------------------------###
46 return $self->{'cgix'} ||= do {
52 ### the main validation routine
54 my $self = (! ref($_[0])) ? shift-
>new # $class->validate
55 : UNIVERSAL
::isa
($_[0], __PACKAGE__
) ? shift # $self->validate
56 : __PACKAGE__-
>new; # &validate
57 my $form = shift || die "Missing form hash";
58 my $val_hash = shift || die "Missing validation hash";
59 my $what_was_validated = shift; # allow for extra arrayref that stores what was validated
61 ### turn the form into a form hash if doesn't look like one already
62 die "Invalid form hash or cgi object" if ! ref $form;
63 if (ref $form ne 'HASH') {
64 local $self->{cgi_object
} = $form;
65 $form = $self->cgix->get_form($form);
68 ### make sure the validation is a hashref
69 ### get_validation handle odd types
70 if (ref $val_hash ne 'HASH') {
71 $val_hash = $self->get_validation($val_hash) if ref $val_hash ne 'SCALAR' || ! ref $val_hash;
72 die "Validation groups must be a hashref" if ref $val_hash ne 'HASH';
75 ### parse keys that are group arguments - and those that are keys to validate
77 my @field_keys = grep { /^(?:group|general)\s+(\w+)/
78 ? do {$ARGS{$1} = $val_hash->{$_} ; 0}
82 ### only validate this group if it is supposed to be checked
83 return if $ARGS{'validate_if'} && ! $self->check_conditional($form, $ARGS{'validate_if'});
85 ### Look first for items in 'group fields' or 'group order'
87 if ($fields = $ARGS{'fields'} || $ARGS{'order'}) {
88 my $type = $ARGS{'fields'} ? 'group fields' : 'group order';
89 die "Validation '$type' must be an arrayref when passed"
90 if ! UNIVERSAL
::isa
($fields, 'ARRAY');
92 foreach my $field (@$fields) {
93 die "Non-defined value in '$type'" if ! defined $field;
95 die "Found nonhashref value in '$type'" if ref($field) ne 'HASH';
96 die "Element missing \"field\" key/value in '$type'" if ! defined $field->{'field'};
98 } elsif ($field eq 'OR') {
101 die "No element found in '$type' for $field" if ! exists $val_hash->{$field};
102 die "Found nonhashref value in '$type'" if ref($val_hash->{$field}) ne 'HASH';
103 push @temp, { %{ $val_hash->{$field} }, field
=> $field }; # copy the values to add the key
108 ### limit the keys that need to be searched to those not in fields or order
109 my %found = map { $_->{'field'} => 1 } @temp;
110 @field_keys = grep { ! $found{$_} } @field_keys;
113 ### add any remaining field_vals from our original hash
114 ### this is necessary for items that weren't in group fields or group order
115 foreach my $field (@field_keys) {
116 die "Found nonhashref value for field $field" if ref($val_hash->{$field}) ne 'HASH';
117 if (defined $val_hash->{$field}->{'field'}) {
118 push @$fields, $val_hash->{$field}->{'field'};
120 push @$fields, { %{$val_hash->{$field}}, field
=> $field };
124 ### Finally we have our arrayref of hashrefs that each have their 'field' key
125 ### now lets do the validation
128 my $hold_error; # hold the error for a moment - to allow for an "OR" operation
129 foreach (my $i = 0; $i < @$fields; $i++) {
130 my $ref = $fields->[$i];
131 if (! ref($ref) && $ref eq 'OR') {
132 $i++ if $found; # if found skip the OR altogether
137 die "Missing field key during normal validation" if ! $ref->{'field'};
138 local $ref->{'was_validated'} = 1;
139 my $err = $self->validate_buddy($form, $ref->{'field'}, $ref);
140 if ($ref->{'was_validated'} && $what_was_validated) {
141 push @$what_was_validated, $ref;
144 ### test the error - if errors occur allow for OR - if OR fails use errors from first fail
146 if ($i < $#$fields && ! ref($fields->[$i + 1]) && $fields->[$i + 1] eq 'OR') {
149 push @errors, $hold_error ? @$hold_error : @$err;
156 push(@errors, @$hold_error) if $hold_error; # allow for final OR to work
159 ### optionally check for unused keys in the form
160 if ($ARGS{no_extra_fields
} || $self->{no_extra_fields
}) {
161 my %keys = map { ($_->{'field'} => 1) } @$fields; # %{ $self->get_validation_keys($val_hash) };
162 foreach my $key (sort keys %$form) {
164 push @errors, [$key, 'no_extra_fields', {}, undef];
168 ### return what they want
170 my @copy = grep {/$QR_EXTRA/o} keys %$self;
171 @ARGS{@copy} = @{ $self }{@copy};
172 unshift @errors, $ARGS{'title'} if $ARGS{'title'};
173 my $err_obj = $self->new_error(\
@errors, \
%ARGS);
174 die $err_obj if $ARGS{'raise_error'};
183 return CGI
::Ex
::Validate
::Error-
>new(@_);
186 ### allow for optional validation on groups and on individual items
187 sub check_conditional
{
188 my ($self, $form, $ifs, $ifs_match) = @_;
190 ### can pass a single hash - or an array ref of hashes
192 die "Need reference passed to check_conditional";
193 } elsif (! ref($ifs)) {
195 } elsif (UNIVERSAL
::isa
($ifs,'HASH')) {
199 local $self->{'_check_conditional'} = 1;
201 ### run the if options here
202 ### multiple items can be passed - all are required unless OR is used to separate
204 foreach (my $i = 0; $i <= $#$ifs; $i ++) {
205 my $ref = $ifs->[$i];
208 $i ++ if $found; # if found skip the OR altogether
212 if ($ref =~ s/^\s*!\s*//) {
213 $ref = {field
=> $ref, max_in_set
=> "0 of $ref"};
215 $ref = {field
=> $ref, required
=> 1};
221 ### get the field - allow for custom variables based upon a match
222 my $field = $ref->{'field'} || die "Missing field key during validate_if (possibly used a reference to a main hash *foo -> &foo)";
223 $field =~ s/\$(\d+)/defined($ifs_match->[$1]) ? $ifs_match->[$1] : ''/eg if $ifs_match;
225 my $errs = $self->validate_buddy($form, $field, $ref);
232 ### this is where the main checking goes on
235 my ($form, $field, $field_val, $ifs_match) = @_;
237 local $self->{'_recurse'} = ($self->{'_recurse'} || 0) + 1;
238 die "Max dependency level reached 10" if $self->{'_recurse'} > 10;
241 my $types = [sort keys %$field_val];
243 ### allow for not running some tests in the cgi
244 if ($field_val->{'exclude_cgi'}) {
245 delete $field_val->{'was_validated'};
249 ### allow for field names that contain regular expressions
250 if ($field =~ m/^(!\s*|)m([^\s\w])(.*)\2([eigsmx]*)$/s) {
251 my ($not,$pat,$opt) = ($1,$3,$4);
253 die "The e option cannot be used on validation keys on field $field" if $opt =~ /e/;
254 foreach my $_field (sort keys %$form) {
255 next if ($not && $_field =~ m/(?$opt:$pat)/) || (! $not && $_field !~ m/(?$opt:$pat)/);
256 my @match = (undef, $1, $2, $3, $4, $5); # limit to the matches
257 my $errs = $self->validate_buddy($form, $_field, $field_val, \
@match);
258 push @errors, @$errs if $errs;
260 return @errors ? \
@errors : 0;
263 my $values = UNIVERSAL
::isa
($form->{$field},'ARRAY') ? $form->{$field} : [$form->{$field}];
264 my $n_values = $#$values + 1;
266 ### allow for default value
267 if (exists $field_val->{'default'}) {
268 if ($n_values == 0 || ($n_values == 1 && (! defined($values->[0]) || ! length($values->[0])))) {
269 $form->{$field} = $values->[0] = $field_val->{'default'};
273 ### allow for a few form modifiers
275 foreach my $value (@$values) {
276 next if ! defined $value;
277 if (! $field_val->{'do_not_trim'}) { # whitespace
282 if ($field_val->{'trim_control_chars'}) {
284 $value =~ y/\x00-\x1F//d;
287 if ($field_val->{'to_upper_case'}) { # uppercase
290 } elsif ($field_val->{'to_lower_case'}) { # lowercase
295 # allow for inline specified modifications (ie s/foo/bar/)
296 foreach my $type (grep {/^replace_?\d*$/} @$types) {
297 my $ref = UNIVERSAL
::isa
($field_val->{$type},'ARRAY') ? $field_val->{$type}
298 : [split(/\s*\|\|\s*/,$field_val->{$type})];
299 foreach my $rx (@$ref) {
300 if ($rx !~ m/^\s*s([^\s\w])(.+)\1(.*)\1([eigsmx]*)$/s) {
301 die "Not sure how to parse that replace ($rx)";
303 my ($pat, $swap, $opt) = ($2, $3, $4);
304 die "The e option cannot be used in swap on field $field" if $opt =~ /e/;
305 my $global = $opt =~ s/g//g;
308 foreach my $value (@$values) {
309 $value =~ s
{(?$opt:$pat)}{
310 my @match = (undef, $1, $2, $3, $4, $5, $6); # limit on the number of matches
312 $copy =~ s/\$(\d+)/defined($match[$1]) ? $match[$1] : ""/ge;
314 $copy; # return of the swap
318 foreach my $value (@$values) {
319 next if ! defined $value;
320 $value =~ s
{(?$opt:$pat)}{
321 my @match = (undef, $1, $2, $3, $4, $5, $6); # limit on the number of matches
323 $copy =~ s/\$(\d+)/defined($match[$1]) ? $match[$1] : ""/ge;
325 $copy; # return of the swap
331 ### put them back into the form if we have modified it
333 if ($n_values == 1) {
334 $form->{$field} = $values->[0];
335 $self->{cgi_object
}->param(-name
=> $field, -value
=> $values->[0])
336 if $self->{cgi_object
};
338 ### values in @{ $form->{$field} } were modified directly
339 $self->{cgi_object
}->param(-name
=> $field, -value
=> $values)
340 if $self->{cgi_object
};
344 ### only continue if a validate_if is not present or passes test
347 foreach my $type (grep {/^validate_if_?\d*$/} @$types) {
349 my $ifs = $field_val->{$type};
350 my $ret = $self->check_conditional($form, $ifs, $ifs_match);
351 $needs_val ++ if $ret;
353 if (! $needs_val && $n_vif) {
354 delete $field_val->{'was_validated'};
358 ### check for simple existence
359 ### optionally check only if another condition is met
360 my $is_required = $field_val->{'required'} ? 'required' : '';
361 if (! $is_required) {
362 foreach my $type (grep {/^required_if_?\d*$/} @$types) {
363 my $ifs = $field_val->{$type};
364 next if ! $self->check_conditional($form, $ifs, $ifs_match);
365 $is_required = $type;
370 && ($n_values == 0 || ($n_values == 1 && (! defined($values->[0]) || ! length $values->[0])))) {
371 return [] if $self->{'_check_conditional'};
372 return [[$field, $is_required, $field_val, $ifs_match]];
376 my $n = exists($field_val->{'min_values'}) ? $field_val->{'min_values'} || 0 : 0;
377 if ($n_values < $n) {
378 return [] if $self->{'_check_conditional'};
379 return [[$field, 'min_values', $field_val, $ifs_match]];
383 $field_val->{'max_values'} = 1 if ! exists $field_val->{'max_values'};
384 $n = $field_val->{'max_values'} || 0;
385 if ($n_values > $n) {
386 return [] if $self->{'_check_conditional'};
387 return [[$field, 'max_values', $field_val, $ifs_match]];
390 ### max_in_set and min_in_set checks
391 my @min = grep {/^min_in_set_?\d*$/} @$types;
392 my @max = grep {/^max_in_set_?\d*$/} @$types;
393 foreach ([min
=> \
@min],
395 my ($minmax, $keys) = @$_;
396 foreach my $type (@$keys) {
397 $field_val->{$type} =~ m/^\s*(\d+)(?i:\s*of)?\s+(.+)\s*$/
398 || die "Invalid in_set check $field_val->{$type}";
400 foreach my $_field (split /[\s,]+/, $2) {
401 my $ref = UNIVERSAL
::isa
($form->{$_field},'ARRAY') ? $form->{$_field} : [$form->{$_field}];
402 foreach my $_value (@$ref) {
403 $n -- if defined($_value) && length($_value);
406 if ( ($minmax eq 'min' && $n > 0)
407 || ($minmax eq 'max' && $n < 0)) {
408 return [] if $self->{'_check_conditional'};
409 return [[$field, $type, $field_val, $ifs_match]];
414 ### at this point @errors should still be empty
415 my $content_checked; # allow later for possible untainting (only happens if content was checked)
417 ### loop on values of field
418 foreach my $value (@$values) {
420 ### allow for enum types
421 if (exists $field_val->{'enum'}) {
422 my $ref = ref($field_val->{'enum'}) ? $field_val->{'enum'} : [split(/\s*\|\|\s*/,$field_val->{'enum'})];
425 $found = 1 if defined($value) && $_ eq $value;
428 return [] if $self->{'_check_conditional'};
429 push @errors, [$field, 'enum', $field_val, $ifs_match];
431 $content_checked = 1;
434 ### field equality test
435 foreach my $type (grep {/^equals_?\d*$/} @$types) {
436 my $field2 = $field_val->{$type};
437 my $not = ($field2 =~ s/^!\s*//) ? 1 : 0;
439 if ($field2 =~ m/^([\"\'])(.*)\1$/) {
441 $success = (defined($value) && $value eq $test);
442 } elsif (exists($form->{$field2}) && defined($form->{$field2})) {
443 $success = (defined($value) && $value eq $form->{$field2});
444 } elsif (! defined($value)) {
445 $success = 1; # occurs if they are both undefined
447 if ($not ? $success : ! $success) {
448 return [] if $self->{'_check_conditional'};
449 push @errors, [$field, $type, $field_val, $ifs_match];
451 $content_checked = 1;
455 if (exists $field_val->{'min_len'}) {
456 my $n = $field_val->{'min_len'};
457 if (! defined($value) || length($value) < $n) {
458 return [] if $self->{'_check_conditional'};
459 push @errors, [$field, 'min_len', $field_val, $ifs_match];
464 if (exists $field_val->{'max_len'}) {
465 my $n = $field_val->{'max_len'};
466 if (defined($value) && length($value) > $n) {
467 return [] if $self->{'_check_conditional'};
468 push @errors, [$field, 'max_len', $field_val, $ifs_match];
472 ### now do match types
473 foreach my $type (grep {/^match_?\d*$/} @$types) {
474 my $ref = UNIVERSAL
::isa
($field_val->{$type},'ARRAY') ? $field_val->{$type}
475 : UNIVERSAL
::isa
($field_val->{$type}, 'Regexp') ? [$field_val->{$type}]
476 : [split(/\s*\|\|\s*/,$field_val->{$type})];
477 foreach my $rx (@$ref) {
478 if (UNIVERSAL
::isa
($rx,'Regexp')) {
479 if (! defined($value) || $value !~ $rx) {
480 push @errors, [$field, $type, $field_val, $ifs_match];
483 if ($rx !~ m/^(!\s*|)m([^\s\w])(.*)\2([eigsmx]*)$/s) {
484 die "Not sure how to parse that match ($rx)";
486 my ($not,$pat,$opt) = ($1,$3,$4);
488 die "The e option cannot be used on validation keys on field $field" if $opt =~ /e/;
489 if ( ( $not && ( defined($value) && $value =~ m/(?$opt:$pat)/))
490 || (! $not && (! defined($value) || $value !~ m/(?$opt:$pat)/))
492 return [] if $self->{'_check_conditional'};
493 push @errors, [$field, $type, $field_val, $ifs_match];
497 $content_checked = 1;
500 ### allow for comparison checks
501 foreach my $type (grep {/^compare_?\d*$/} @$types) {
502 my $ref = UNIVERSAL
::isa
($field_val->{$type},'ARRAY') ? $field_val->{$type}
503 : [split(/\s*\|\|\s*/,$field_val->{$type})];
504 foreach my $comp (@$ref) {
507 if ($comp =~ /^\s*(>|<|[><!=]=)\s*([\d\.\-]+)\s*$/) {
508 my $val = $value || 0;
510 if ($1 eq '>' ) { $test = ($val > $2) }
511 elsif ($1 eq '<' ) { $test = ($val < $2) }
512 elsif ($1 eq '>=') { $test = ($val >= $2) }
513 elsif ($1 eq '<=') { $test = ($val <= $2) }
514 elsif ($1 eq '!=') { $test = ($val != $2) }
515 elsif ($1 eq '==') { $test = ($val == $2) }
517 } elsif ($comp =~ /^\s*(eq|ne|gt|ge|lt|le)\s+(.+?)\s*$/) {
518 my $val = defined($value) ? $value : '';
519 my ($op, $value2) = ($1, $2);
520 $value2 =~ s/^([\"\'])(.*)\1$/$2/;
521 if ($op eq 'gt') { $test = ($val gt $value2) }
522 elsif ($op eq 'lt') { $test = ($val lt $value2) }
523 elsif ($op eq 'ge') { $test = ($val ge $value2) }
524 elsif ($op eq 'le') { $test = ($val le $value2) }
525 elsif ($op eq 'ne') { $test = ($val ne $value2) }
526 elsif ($op eq 'eq') { $test = ($val eq $value2) }
529 die "Not sure how to compare \"$comp\"";
532 return [] if $self->{'_check_conditional'};
533 push @errors, [$field, $type, $field_val, $ifs_match];
536 $content_checked = 1;
539 ### server side sql type
540 foreach my $type (grep {/^sql_?\d*$/} @$types) {
541 my $db_type = $field_val->{"${type}_db_type"};
542 my $dbh = ($db_type) ? $self->{dbhs
}->{$db_type} : $self->{dbh
};
544 die "Missing dbh for $type type on field $field" . ($db_type ? " and db_type $db_type" : "");
545 } elsif (UNIVERSAL
::isa
($dbh,'CODE')) {
546 $dbh = &$dbh($field, $self) || die "SQL Coderef did not return a dbh";
548 my $sql = $field_val->{$type};
549 my @args = ($value) x
$sql =~ tr/?//;
550 my $return = $dbh->selectrow_array($sql, {}, @args); # is this right - copied from O::FORMS
551 $field_val->{"${type}_error_if"} = 1 if ! defined $field_val->{"${type}_error_if"};
552 if ( (! $return && $field_val->{"${type}_error_if"})
553 || ($return && ! $field_val->{"${type}_error_if"}) ) {
554 return [] if $self->{'_check_conditional'};
555 push @errors, [$field, $type, $field_val, $ifs_match];
557 $content_checked = 1;
560 ### server side custom type
561 foreach my $type (grep {/^custom_?\d*$/} @$types) {
562 my $check = $field_val->{$type};
563 next if UNIVERSAL
::isa
($check, 'CODE') ? &$check($field, $value, $field_val, $type) : $check;
564 return [] if $self->{'_check_conditional'};
565 push @errors, [$field, $type, $field_val, $ifs_match];
566 $content_checked = 1;
569 ### do specific type checks
570 foreach my $type (grep {/^type_?\d*$/} @$types) {
571 if (! $self->check_type($value,$field_val->{'type'},$field,$form)){
572 return [] if $self->{'_check_conditional'};
573 push @errors, [$field, $type, $field_val, $ifs_match];
575 $content_checked = 1;
579 ### allow for the data to be "untainted"
580 ### this is only allowable if the user ran some other check for the datatype
581 if ($field_val->{'untaint'} && $#errors == -1) {
582 if (! $content_checked) {
583 push @errors, [$field, 'untaint', $field_val, $ifs_match];
585 ### generic untainter - assuming the other required content_checks did good validation
586 $_ = /(.*)/ ? $1 : die "Couldn't match?" foreach @$values;
587 if ($n_values == 1) {
588 $form->{$field} = $values->[0];
589 $self->{cgi_object
}->param(-name
=> $field, -value
=> $values->[0])
590 if $self->{cgi_object
};
592 ### values in @{ $form->{$field} } were modified directly
593 $self->{cgi_object
}->param(-name
=> $field, -value
=> $values)
594 if $self->{cgi_object
};
599 ### all done - time to return
600 return @errors ? \
@errors : 0;
603 ###----------------------------------------------------------------###
605 ### used to validate specific types
609 my $type = uc(shift);
611 ### do valid email address for our system
612 if ($type eq 'EMAIL') {
613 return 0 if ! $value;
614 my($local_p,$dom) = ($value =~ /^(.+)\@(.+?)$/) ? ($1,$2) : return 0;
616 return 0 if length($local_p) > 60;
617 return 0 if length($dom) > 100;
618 return 0 if ! $self->check_type($dom,'DOMAIN') && ! $self->check_type($dom,'IP');
619 return 0 if ! $self->check_type($local_p,'LOCAL_PART');
621 ### the "username" portion of an email address
622 } elsif ($type eq 'LOCAL_PART') {
623 return 0 if ! defined($value) || ! length($value);
624 return 0 if $value =~ m/[^a-z0-9.\-!&+]/;
625 return 0 if $value =~ m/^[\.\-]/;
626 return 0 if $value =~ m/[\.\-\&]$/;
627 return 0 if $value =~ m/(\.\-|\-\.|\.\.)/;
629 ### standard IP address
630 } elsif ($type eq 'IP') {
631 return 0 if ! $value;
632 return (4 == grep {!/\D/ && $_ < 256} split /\./, $value, 4);
634 ### domain name - including tld and subdomains (which are all domains)
635 } elsif ($type eq 'DOMAIN') {
636 return 0 if ! $value;
637 return 0 if $value =~ m/[^a-z0-9.\-]/;
638 return 0 if $value =~ m/^[\.\-]/;
639 return 0 if $value =~ m/(\.\-|\-\.|\.\.)/;
640 return 0 if length($value) > 255;
641 return 0 if $value !~ s/\.([a-z]+)$//;
644 if ($ext eq 'name') { # .name domains
645 return 0 if $value !~ /^[a-z0-9][a-z0-9\-]{0,62} \. [a-z0-9][a-z0-9\-]{0,62}$/x;
646 } else { # any other domains
647 return 0 if $value !~ /^([a-z0-9][a-z0-9\-]{0,62} \.)* [a-z0-9][a-z0-9\-]{0,62}$/x;
651 } elsif ($type eq 'URL') {
652 return 0 if ! $value;
653 $value =~ s
|^https
?://([^/]+)||i
|| return 0;
655 return 0 if ! $self->check_type($dom,'DOMAIN') && ! $self->check_type($dom,'IP');
656 return 0 if $value && ! $self->check_type($value,'URI');
658 ### validate a uri - the path portion of a request
659 } elsif ($type eq 'URI') {
660 return 0 if ! $value;
661 return 0 if $value =~ m/\s+/;
663 } elsif ($type eq 'CC') {
664 return 0 if ! $value;
665 ### validate the number
666 return 0 if $value =~ /[^\d\-\ ]/
667 || length($value) > 16
668 || length($value) < 13;
670 ### simple mod10 check
674 foreach my $digit ( reverse split //, $value ){
675 $switch = 1 if ++ $switch > 2;
676 my $y = $digit * $switch;
680 return 0 if $sum % 10;
687 ###----------------------------------------------------------------###
692 require CGI
::Ex
::Conf
;
693 return CGI
::Ex
::Conf
::conf_read
($val, {html_key
=> 'validation', default_ext
=> $DEFAULT_EXT});
696 ### returns all keys from all groups - even if group has validate_if
697 sub get_validation_keys
{
699 my $val_hash = shift;
700 my $form = shift; # with optional form - will only return keys in validated groups
702 ### turn the form into a form hash if doesn't look like one already
704 die "Invalid form hash or cgi object" if ! ref $form;
705 if (ref $form ne 'HASH') {
706 local $self->{cgi_object
} = $form;
707 $form = $self->cgix->get_form($form);
711 ### make sure the validation is a hashref
712 ### get_validation handle odd types
713 if (ref $val_hash ne 'HASH') {
714 $val_hash = $self->get_validation($val_hash) if ref $val_hash ne 'SCALAR' || ! ref $val_hash;
715 die "Validation groups must be a hashref" if ref $val_hash ne 'HASH';
718 ### parse keys that are group arguments - and those that are keys to validate
720 my @field_keys = grep { /^(?:group|general)\s+(\w+)/
721 ? do {$ARGS{$1} = $val_hash->{$_} ; 0}
723 sort keys %$val_hash;
725 ### only validate this group if it is supposed to be checked
726 return if $form && $ARGS{'validate_if'} && ! $self->check_conditional($form, $ARGS{'validate_if'});
728 ### Look first for items in 'group fields' or 'group order'
730 if (my $fields = $ARGS{'fields'} || $ARGS{'order'}) {
731 my $type = $ARGS{'fields'} ? 'group fields' : 'group order';
732 die "Validation '$type' must be an arrayref when passed"
733 if ! UNIVERSAL
::isa
($fields, 'ARRAY');
734 foreach my $field (@$fields) {
735 die "Non-defined value in '$type'" if ! defined $field;
737 die "Found nonhashref value in '$type'" if ref($field) ne 'HASH';
738 die "Element missing \"field\" key/value in '$type'" if ! defined $field->{'field'};
739 $keys{$field->{'field'}} = $field->{'name'} || 1;
740 } elsif ($field eq 'OR') {
742 die "No element found in '$type' for $field" if ! exists $val_hash->{$field};
743 die "Found nonhashref value in '$type'" if ref($val_hash->{$field}) ne 'HASH';
744 $keys{$field} = $val_hash->{$field}->{'name'} || 1;
749 ### add any remaining field_vals from our original hash
750 ### this is necessary for items that weren't in group fields or group order
751 foreach my $field (@field_keys) {
752 next if $keys{$field};
753 die "Found nonhashref value for field $field" if ref($val_hash->{$field}) ne 'HASH';
754 if (defined $val_hash->{$field}->{'field'}) {
755 $keys{$val_hash->{$field}->{'field'}} = $val_hash->{$field}->{'name'} || 1;
757 $keys{$field} = $val_hash->{$field}->{'name'} || 1;
764 ###----------------------------------------------------------------###
766 ### spit out a chunk that will do the validation
768 ### allow for some browsers to not receive the validation js
769 return "<!-- JS validation not supported in this browser $_ -->"
770 if $ENV{'HTTP_USER_AGENT'} && grep {$ENV{'HTTP_USER_AGENT'} =~ $_} @UNSUPPORTED_BROWSERS;
773 my $val_hash = shift || die "Missing validation";
774 my $form_name = shift || die "Missing form name";
775 my $js_uri_path = shift || $JS_URI_PATH;
776 $val_hash = $self->get_validation($val_hash);
778 ### store any extra items from self
780 $EXTRA{"general $_"} = $self->{$_} for grep {/$QR_EXTRA/o} keys %$self; # add 'general' to be used in javascript
782 my $js_uri_path_validate = $JS_URI_PATH_VALIDATE || do {
783 die "Missing \$js_uri_path" if ! $js_uri_path;
784 "$js_uri_path/CGI/Ex/validate.js";
787 if (! $self->{'no_jsondump'} && eval { require CGI
::Ex
::JSONDump
}) {
788 my $json = CGI
::Ex
::JSONDump-
>new({pretty
=> 1})->dump($val_hash);
789 return qq{<script src="$js_uri_path_validate"></script>
791 document.validation = $json;
792 if (document.check_form) document.check_form("$form_name");
796 } elsif (! $self->{'no_json'} && eval { require JSON
}) {
797 my $json = JSON-
>new(pretty
=> 1)->objToJson($val_hash);
799 return qq{<script src="$js_uri_path_validate"></script>
801 document.validation = $json;
802 if (document.check_form) document.check_form("$form_name");
806 } elsif (eval { require YAML
}) {
808 my $str = YAML
::Dump
((scalar keys %EXTRA) ? (\
%EXTRA) : () , $val_hash);
809 $str =~ s/(?<!\\)\\(?=[sSdDwWbB0-9?.*+|\-\^\${}()\[\]])/\\\\/g; # fix some issues with YAML
810 $str =~ s/\n/\\n\\\n/g; # allow for one big string that flows on multiple lines
811 $str =~ s/\"/\\\"/g; # quotify it
814 my $js_uri_path_yaml = $JS_URI_PATH_YAML || do {
815 die "Missing \$js_uri_path" if ! $js_uri_path;
816 "$js_uri_path/CGI/Ex/yaml_load.js";
819 ### return the string
820 return qq{<script src="$js_uri_path_yaml"></script>
821 <script src="$js_uri_path_validate"></script>
823 document.validation = "$str";
824 if (document.check_form) document.check_form("$form_name");
828 return '<!-- no JSON or YAML support found for JS validation -->';
832 ###----------------------------------------------------------------###
833 ### How to handle errors
835 package CGI
::Ex
::Validate
::Error
;
838 use overload
'""' => \
&as_string
;
841 my ($class, $errors, $extra) = @_;
842 die "Missing or invalid errors arrayref" if ref $errors ne 'ARRAY';
843 die "Missing or invalid extra hashref" if ref $extra ne 'HASH';
844 return bless {errors
=> $errors, extra
=> $extra}, $class;
849 my $extra = $self->{extra
} || {};
850 my $extra2 = shift || {};
852 ### allow for formatting
853 my $join = defined($extra2->{as_string_join
}) ? $extra2->{as_string_join
}
854 : defined($extra->{as_string_join
}) ? $extra->{as_string_join
}
856 my $header = defined($extra2->{as_string_header
}) ? $extra2->{as_string_header
}
857 : defined($extra->{as_string_header
}) ? $extra->{as_string_header
} : "";
858 my $footer = defined($extra2->{as_string_footer
}) ? $extra2->{as_string_footer
}
859 : defined($extra->{as_string_footer
}) ? $extra->{as_string_footer
} : "";
861 return $header . join($join, @{ $self->as_array($extra2) }) . $footer;
864 ### return an array of applicable errors
867 my $errors = $self->{errors
} || die "Missing errors";
868 my $extra = $self->{extra
} || {};
869 my $extra2 = shift || {};
871 my $title = defined($extra2->{as_array_title
}) ? $extra2->{as_array_title
}
872 : defined($extra->{as_array_title
}) ? $extra->{as_array_title
}
873 : "Please correct the following items:";
875 ### if there are heading items then we may end up needing a prefix
887 my $prefix = defined($extra2->{as_array_prefix
}) ? $extra2->{as_array_prefix
}
888 : defined($extra->{as_array_prefix
}) ? $extra->{as_array_prefix
}
889 : $has_headings ? ' ' : '';
891 ### get the array ready
893 push @array, $title if length $title;
897 foreach my $err (@$errors) {
902 my $text = $self->get_error_text($err);
903 next if $found{$text};
905 push @array, "$prefix$text";
912 ### return a hash of applicable errors
915 my $errors = $self->{errors
} || die "Missing errors";
916 my $extra = $self->{extra
} || {};
917 my $extra2 = shift || {};
919 my $suffix = defined($extra2->{as_hash_suffix
}) ? $extra2->{as_hash_suffix
}
920 : defined($extra->{as_hash_suffix
}) ? $extra->{as_hash_suffix
} : '_error';
921 my $join = defined($extra2->{as_hash_join
}) ? $extra2->{as_hash_join
}
922 : defined($extra->{as_hash_join
}) ? $extra->{as_hash_join
} : '<br />';
924 ### now add to the hash
927 foreach my $err (@$errors) {
930 my ($field, $type, $field_val, $ifs_match) = @$err;
931 die "Missing field name" if ! $field;
932 if ($field_val->{delegate_error
}) {
933 $field = $field_val->{delegate_error
};
934 $field =~ s/\$(\d+)/defined($ifs_match->[$1]) ? $ifs_match->[$1] : ''/eg if $ifs_match;
937 my $text = $self->get_error_text($err);
938 next if $found{$field}->{$text};
939 $found{$field}->{$text} = 1;
942 $return{$field} ||= [];
943 $return{$field} = [$return{$field}] if ! ref($return{$field});
944 push @{ $return{$field} }, $text;
947 ### allow for elements returned as
949 my $header = defined($extra2->{as_hash_header
}) ? $extra2->{as_hash_header
}
950 : defined($extra->{as_hash_header
}) ? $extra->{as_hash_header
} : "";
951 my $footer = defined($extra2->{as_hash_footer
}) ? $extra2->{as_hash_footer
}
952 : defined($extra->{as_hash_footer
}) ? $extra->{as_hash_footer
} : "";
953 foreach my $key (keys %return) {
954 $return{$key} = $header . join($join,@{ $return{$key} }) . $footer;
961 ### return a user friendly error message
965 my $extra = $self->{extra
} || {};
966 my ($field, $type, $field_val, $ifs_match) = @$err;
967 my $dig = ($type =~ s/(_?\d+)$//) ? $1 : '';
968 my $type_lc = lc($type);
970 ### allow for delegated field names - only used for defaults
971 if ($field_val->{delegate_error
}) {
972 $field = $field_val->{delegate_error
};
973 $field =~ s/\$(\d+)/defined($ifs_match->[$1]) ? $ifs_match->[$1] : ''/eg if $ifs_match;
976 ### the the name of this thing
977 my $name = $field_val->{'name'} || "The field $field";
978 $name =~ s/\$(\d+)/defined($ifs_match->[$1]) ? $ifs_match->[$1] : ''/eg if $ifs_match;
980 ### type can look like "required" or "required2" or "required100023"
981 ### allow for fallback from required100023_error through required_error
982 my @possible_error_keys = ("${type}_error");
983 unshift @possible_error_keys, "${type}${dig}_error" if length($dig);
985 ### look in the passed hash or self first
987 foreach my $key (@possible_error_keys){
988 $return = $field_val->{$key} || $extra->{$key} || next;
989 $return =~ s/\$(\d+)/defined($ifs_match->[$1]) ? $ifs_match->[$1] : ''/eg if $ifs_match;
990 $return =~ s/\$field/$field/g;
991 $return =~ s/\$name/$name/g;
992 if (my $value = $field_val->{"$type$dig"}) {
993 $return =~ s/\$value/$value/g if ! ref $value;
998 ### set default messages
1000 if ($type eq 'required' || $type eq 'required_if') {
1001 $return = "$name is required.";
1003 } elsif ($type eq 'min_values') {
1004 my $n = $field_val->{"min_values${dig}"};
1005 my $values = ($n == 1) ? 'value' : 'values';
1006 $return = "$name had less than $n $values.";
1008 } elsif ($type eq 'max_values') {
1009 my $n = $field_val->{"max_values${dig}"};
1010 my $values = ($n == 1) ? 'value' : 'values';
1011 $return = "$name had more than $n $values.";
1013 } elsif ($type eq 'enum') {
1014 $return = "$name is not in the given list.";
1016 } elsif ($type eq 'equals') {
1017 my $field2 = $field_val->{"equals${dig}"};
1018 my $name2 = $field_val->{"equals${dig}_name"} || "the field $field2";
1019 $name2 =~ s/\$(\d+)/defined($ifs_match->[$1]) ? $ifs_match->[$1] : ''/eg if $ifs_match;
1020 $return = "$name did not equal $name2.";
1022 } elsif ($type eq 'min_len') {
1023 my $n = $field_val->{"min_len${dig}"};
1024 my $char = ($n == 1) ? 'character' : 'characters';
1025 $return = "$name was less than $n $char.";
1027 } elsif ($type eq 'max_len') {
1028 my $n = $field_val->{"max_len${dig}"};
1029 my $char = ($n == 1) ? 'character' : 'characters';
1030 $return = "$name was more than $n $char.";
1032 } elsif ($type eq 'max_in_set') {
1033 my $set = $field_val->{"max_in_set${dig}"};
1034 $return = "Too many fields were chosen from the set ($set)";
1036 } elsif ($type eq 'min_in_set') {
1037 my $set = $field_val->{"min_in_set${dig}"};
1038 $return = "Not enough fields were chosen from the set ($set)";
1040 } elsif ($type eq 'match') {
1041 $return = "$name contains invalid characters.";
1043 } elsif ($type eq 'compare') {
1044 $return = "$name did not fit comparison.";
1046 } elsif ($type eq 'sql') {
1047 $return = "$name did not match sql test.";
1049 } elsif ($type eq 'custom') {
1050 $return = "$name did not match custom test.";
1052 } elsif ($type eq 'type') {
1053 my $_type = $field_val->{"type${dig}"};
1054 $return = "$name did not match type $_type.";
1056 } elsif ($type eq 'untaint') {
1057 $return = "$name cannot be untainted without one of the following checks: enum, equals, match, compare, sql, type, custom";
1059 } elsif ($type eq 'no_extra_fields') {
1060 $return = "$name should not be passed to validate.";
1064 die "Missing error on field $field for type $type$dig" if ! $return;
1069 ###----------------------------------------------------------------###
1078 use CGI::Ex::Validate;
1082 my $errobj = CGI::Ex::Validate->new->validate($form, $val_hash);
1086 my $form = CGI->new;
1088 my $form = CGI::Ex->new; # OR CGI::Ex->get_form;
1090 my $form = {key1 => 'val1', key2 => 'val2'};
1098 field => 'username',
1099 # field is optional in this case - will use key name
1106 validate_if => 'email',
1113 'group order' => [qw(username email email2)],
1114 username => {required => 1, max_len => 30},
1121 'group fields' => [{
1122 field => 'username', # field is not optional in this case
1131 validate_if => 'email',
1137 my $vob = CGI::Ex::Validate->new;
1138 my $errobj = $vob->validate($form, $val_hash);
1140 my $errobj = $vob->validate($form, "/somefile/somewhere.val"); # import config using yaml file
1142 my $errobj = $vob->validate($form, "/somefile/somewhere.pl"); # import config using perl file
1144 my $errobj = $vob->validate($form, "--- # a yaml document\n"); # import config using yaml str
1148 my $error_heading = $errobj->as_string; # OR "$errobj";
1149 my $error_list = $errobj->as_array; # ordered list of what when wrong
1150 my $error_hash = $errobj->as_hash; # hash of arrayrefs of errors
1152 # form passed validation
1155 ### will add an error for any form key not found in $val_hash
1156 my $vob = CGI::Ex::Validate->new({no_extra_keys => 1});
1157 my $errobj = $vob->validate($form, $val_hash);
1161 CGI::Ex::Validate is one of many validation modules. It aims to have
1162 all of the basic data validation functions, avoid adding all of the
1163 millions of possible types, while still giving the capability for the
1164 developer to add their own types.
1166 It also has full support for providing the same validation in javascript.
1167 It provides methods for attaching the javascript to existing forms.
1169 As opposed to other kitchen sync validation modules, CGI::Ex::Validate
1170 offers the simple types of validation, and makes it easy to add your
1179 Used to instantiate the object. Arguments are either a hash, or hashref,
1180 or nothing at all. Keys of the hash become the keys of the object.
1182 =item C<get_validation>
1184 Given a filename or YAML string will return perl hash. If more than one
1185 group is contained in the file, it will return an arrayref of hashrefs.
1187 my $ref = $self->get_validation($file);
1189 =item C<get_validation_keys>
1191 Given a filename or YAML string or a validation hashref, will return all
1192 of the possible keys found in the validation hash. This can be used to
1193 check to see if extra items have been passed to validate. If a second
1194 argument contains a form hash is passed, get_validation_keys will only
1195 return the keys of groups that were validated.
1197 my $key_hashref = $self->get_validation_keys($val_hash);
1199 The values of the hash are the names of the fields.
1203 Arguments are a form hashref or cgi object, a validation hashref or
1204 filename, and an optional what_was_validated arrayref (discussed
1205 further later on). If a CGI object is passed, CGI::Ex::get_form will
1206 be called on that object to turn it into a hashref. If a filename is
1207 given for the validation, get_validation will be called on that
1208 filename. If the what_was_validated_arrayref is passed - it will be
1209 populated (pushed) with the field hashes that were actually validated
1210 (anything that was skipped because of validate_if will not be in the
1213 If the form passes validation, validate will return undef. If it
1214 fails validation, it will return a CGI::Ex::Validate::Error object.
1215 If the 'raise_error' option has been set, validate will die
1216 with a CGI::Ex::validate::Error object as the value.
1218 my $err_obj = $self->validate($form, $val_hash);
1222 $self->{raise_error} = 1; # can also be listed in the val_hash
1223 eval { $self->validate($form, $val_hash) };
1224 if ($@) { my $err_obj = $@; }
1226 =item C<generate_js>
1228 Works with CGI::Ex::JSONDump, but can also work with JSON or YAML
1229 if desired (see L<JSON> or L<YAML>).
1231 Takes a validation hash, a form name, and an optional javascript uri
1232 path and returns Javascript that can be embedded on a page and will
1233 perform identical validations as the server side. The form name must be
1234 the name of the form that the validation will act upon - the name is
1235 used to register an onsubmit function. The javascript uri path is
1236 used to embed the locations of javascript source files included
1237 with the CGI::Ex distribution.
1239 The javascript uri path is highly dependent upon the server
1240 configuration and therefore must be configured manually. It may be
1241 passed to generate_js, or it may be specified in $JS_URI_PATH. There
1242 are two files included with this module that are needed -
1243 CGI/Ex/yaml_load.js and CGI/Ex/validate.js. When generating the js
1244 code, generate_js will look in $JS_URI_PATH_YAML and
1245 $JS_URI_PATH_VALIDATE. If either of these are not set, generate_js
1246 will default to "$JS_URI_PATH/CGI/Ex/yaml_load.js" and
1247 "$JS_URI_PATH/CGI/Ex/validate.js" (Note: yaml_load is only needed
1248 if the flags no_jsondump and no_json have been set).
1250 $self->generate_js($val_hash, 'my_form', "/cgi-bin/js")
1252 # would generate something like the following...
1254 <script src="/cgi-bin/js/CGI/Ex/validate.js"></script>
1255 ... more js follows ...
1257 $CGI::Ex::Validate::JS_URI_PATH = "/stock/js";
1258 $self->generate_js($val_hash, 'my_form')
1260 # would generate something like the following...
1262 <script src="/stock/js/CGI/Ex/validate.js"></script>
1263 ... more js follows ...
1265 Referencing yaml_load.js and validate.js can be done in any of
1266 several ways. They can be copied to or symlinked to a fixed location
1267 in the server's html directory. They can also be printed out by a cgi.
1268 The method C<-E<gt>print_js> has been provided in CGI::Ex for printing
1269 js files found in the perl hierarchy. See L<CGI::Ex> for more details.
1270 The $JS_URI_PATH of "/cgi-bin/js" could contain the following:
1277 ### path_info should contain something like /CGI/Ex/yaml_load.js
1278 my $info = $ENV{PATH_INFO} || '';
1279 die "Invalid path" if $info !~ m|^(/\w+)+.js$|;
1282 CGI::Ex->new->print_js($info);
1285 The print_js method in CGI::Ex is designed to cache the javascript in
1286 the browser (caching is suggested as they are medium sized files).
1290 Returns a CGI::Ex object. Used internally.
1294 =head1 VALIDATION HASH
1296 The validation hash may be passed as a hashref or as a
1297 filename, or as a YAML document string. If it is a filename, it will
1298 be translated into a hash using the %EXT_HANDLER for the extension on
1299 the file. If there is no extension, it will use $DEFAULT_EXT as a
1300 default. CGI::Ex::Conf is used for the reading of files.
1302 Keys matching the regex m/^(general|group)\s+(\w+)$/ are reserved and
1303 are counted as GROUP OPTIONS. Other keys (if any, should be field names
1304 that need validation).
1306 If the GROUP OPTION 'group validate_if' is set, the validation will only
1307 be validated if the conditions are met. If 'group validate_if' is not
1308 specified, then the validation will proceed.
1310 Each of the items listed in the validation will be validated. The
1311 validation order is determined in one of three ways:
1315 =item Specify 'group fields' arrayref.
1317 # order will be (username, password, 'm/\w+_foo/', somethingelse)
1319 'group title' => "User Information",
1321 {field => 'username', required => 1},
1322 {field => 'password', required => 1},
1323 {field => 'm/\w+_foo/', required => 1},
1325 somethingelse => {required => 1},
1328 =item Specify 'group order' arrayref.
1330 # order will be (username, password, 'm/\w+_foo/', somethingelse)
1332 'group title' => "User Information",
1333 'group order' => [qw(username password), 'm/\w+_foo/'],
1334 username => {required => 1},
1335 password => {required => 1},
1336 'm/\w+_foo/' => {required => 1},
1337 somethingelse => {required => 1},
1340 =item Do nothing - use sorted order.
1342 # order will be ('m/\w+_foo/', password, somethingelse, username)
1344 'group title' => "User Information",
1345 username => {required => 1},
1346 password => {required => 1},
1347 'm/\w+_foo/' => {required => 1},
1348 somethingelse => {required => 1},
1353 Optionally the 'group fields' or the 'group order' may contain the
1354 word 'OR' as a special keyword. If the item preceding 'OR' fails
1355 validation the item after 'OR' will be tested instead. If the item
1356 preceding 'OR' passes validation the item after 'OR' will not be
1359 'group order' => [qw(zip OR postalcode state OR region)],
1361 Each individual field validation hashref will operate on the field contained
1362 in the 'field' key. This key may also be a regular expression in the
1363 form of 'm/somepattern/'. If a regular expression is used, all keys
1364 matching that pattern will be validated. If the field key is
1365 not specified, the key from the top level hash will be used.
1367 foobar => { # "foobar" is not used as key because field is specified
1368 field => 'real_key_name',
1375 Each of the individual field validation hashrefs should contain the
1376 types listed in VALIDATION TYPES.
1378 =head1 VALIDATION TYPES
1380 This section lists the available validation types. Multiple instances
1381 of the same type may be used for some validation types by adding a
1382 number to the type (ie match, match2, match232, match_94). Multiple
1383 instances are validated in sorted order. Types that allow multiple
1400 =item C<validate_if>
1402 If validate_if is specified, the field will only be validated
1403 if the conditions are met. Works in JS.
1405 validate_if => {field => 'name', required => 1, max_len => 30}
1406 # Will only validate if the field "name" is present and is less than 30 chars.
1408 validate_if => 'name',
1410 validate_if => {field => 'name', required => 1},
1412 validate_if => '! name',
1414 validate_if => {field => 'name', max_in_set => '0 of name'},
1416 validate_if => {field => 'country', compare => "eq US"},
1417 # only if country's value is equal to US
1419 validate_if => {field => 'country', compare => "ne US"},
1420 # if country doesn't equal US
1422 validate_if => {field => 'password', match => 'm/^md5\([a-z0-9]{20}\)$/'},
1423 # if password looks like md5(12345678901234567890)
1426 field => 'm/^(\w+)_pass/',
1427 validate_if => '$1_user',
1430 # will validate foo_pass only if foo_user was present.
1432 The validate_if may also contain an arrayref of validation items. So that
1433 multiple checks can be run. They will be run in order. validate_if will
1434 return true only if all options returned true.
1436 validate_if => ['email', 'phone', 'fax']
1438 Optionally, if validate_if is an arrayref, it may contain the word
1439 'OR' as a special keyword. If the item preceding 'OR' fails validation
1440 the item after 'OR' will be tested instead. If the item preceding 'OR'
1441 passes validation the item after 'OR' will not be tested.
1443 validate_if => [qw(zip OR postalcode)],
1445 =item C<required_if>
1447 Requires the form field if the condition is satisfied. The conditions
1448 available are the same as for validate_if. This is somewhat the same
1451 validate_if => 'some_condition',
1454 required_if => 'some_condition',
1456 If a regex is used for the field name, the required_if
1457 field will have any match patterns swapped in.
1460 field => 'm/^(\w+)_pass/',
1461 required_if => '$1_user',
1464 This example would require the "foobar_pass" field to be set
1465 if the "foobar_user" field was passed.
1469 Requires the form field to have some value. If the field is not present,
1470 no other checks will be run.
1472 =item C<min_values> and C<max_values>
1474 Allows for specifying the maximum number of form elements passed.
1475 max_values defaults to 1 (You must explicitly set it higher
1476 to allow more than one item by any given name).
1478 =item C<min_in_set> and C<max_in_set>
1480 Somewhat like min_values and max_values except that you specify the
1481 fields that participate in the count. Also - entries that are not
1482 defined or do not have length are not counted. An optional "of" can
1483 be placed after the number for human readability.
1485 min_in_set => "2 of foo bar baz",
1486 # two of the fields foo, bar or baz must be set
1488 min_in_set => "2 foo bar baz",
1490 min_in_set => "2 OF foo bar baz",
1492 validate_if => {field => 'whatever', max_in_set => '0 of whatever'},
1493 # only run validation if there were zero occurrences of whatever
1497 Allows for checking whether an item matches a set of options. In perl
1498 the value may be passed as an arrayref. In the conf or in perl the
1499 value may be passed of the options joined with ||.
1502 field => 'password_type',
1503 enum => 'plaintext||crypt||md5', # OR enum => [qw(plaintext crypt md5)],
1508 Allows for comparison of two form elements. Can have an optional !.
1511 field => 'password',
1512 equals => 'password_verify',
1516 equals => '!domain2', # make sure the fields are not the same
1519 =item C<min_len and max_len>
1521 Allows for check on the length of fields
1531 Allows for regular expression comparison. Multiple matches may
1532 be concatenated with ||. Available in JS.
1536 match => 'm/^\d{1,3}(\.\d{1,3})3$/',
1537 match_2 => '!/^0\./ || !/^192\./',
1542 Allows for custom comparisons. Available types are
1543 >, <, >=, <=, !=, ==, gt, lt, ge, le, ne, and eq. Comparisons
1544 also work in the JS.
1547 field => 'my_number',
1548 match => 'm/^\d+$/',
1549 compare1 => '> 100',
1550 compare2 => '< 255',
1551 compare3 => '!= 150',
1556 SQL query based - not available in JS. The database handle will be looked
1557 for in the value $self->{dbhs}->{foo} if sql_db_type is set to 'foo',
1558 otherwise it will default to $self->{dbh}. If $self->{dbhs}->{foo} or
1559 $self->{dbh} is a coderef - they will be called and should return a dbh.
1562 field => 'username',
1563 sql => 'SELECT COUNT(*) FROM users WHERE username = ?',
1564 sql_error_if => 1, # default is 1 - set to 0 to negate result
1565 # sql_db_type => 'foo', # will look for a dbh under $self->{dbhs}->{foo}
1570 Custom value - not available in JS. Allows for extra programming types.
1571 May be either a boolean value predetermined before calling validate, or may be
1572 a coderef that will be called during validation. If coderef is called, it will
1573 be passed the field name, the form value for that name, and a reference to the
1574 field validation hash. If the custom type returns false the element fails
1575 validation and an error is added.
1578 field => 'username',
1580 my ($key, $val, $type, $field_val_hash) = @_;
1588 Custom value - only available in JS. Allows for extra programming types.
1589 May be either a boolean value pre-determined before calling validate, or may be
1590 section of javascript that will be eval'ed. The last value (return value) of
1591 the eval'ed javascript will determine if validation passed. A false value indicates
1592 the value did not pass validation. A true value indicates that it did. See
1593 the t/samples/js_validate_3.html page for a sample of usage.
1598 match => 'm|^\d\d\d\d/\d\d/\d\d$|',
1599 match_error => 'Please enter date in YYYY/MM/DD format',
1602 var y=t.getYear()+1900;
1603 var m=t.getMonth() + 1;
1605 if (m<10) m = '0'+m;
1606 if (d<10) d = '0'+d;
1607 (value > ''+y+'/'+m+'/'+d) ? 1 : 0;
1609 custom_js_error => 'The date was not greater than today.',
1614 Allows for more strict type checking. Currently supported types
1615 include CC (credit card). Other types will be added upon request provided
1616 we can add a perl and a javascript version.
1619 field => 'credit_card',
1625 =head1 SPECIAL VALIDATION TYPES
1631 Specify which field to work on. Key may be a regex in the form 'm/\w+_user/'.
1632 This key is required if 'group fields' is used or if validate_if or required_if
1633 are used. It can optionally be used with other types to specify a different form
1634 element to operate on. On errors, if a non-default error is found, $field
1635 will be swapped with the value found in field.
1637 The field name may also be a regular expression in the
1638 form of 'm/somepattern/'. If a regular expression is used, all keys
1639 matching that pattern will be validated.
1643 Name to use for errors. If a name is not specified, default errors will use
1644 "The field $field" as the name. If a non-default error is found, $name
1645 will be swapped with this name.
1647 =item C<delegate_error>
1649 This option allows for any errors generated on a field to delegate to
1650 a different field. If the field name was a regex, any patterns will
1651 be swapped into the delegate_error value. This option is generally only
1652 useful with the as_hash method of the error object (for inline errors).
1656 match => 'm/^\d{5}/',
1659 field => 'zip_plus4',
1660 match => 'm/^\d{4}/',
1661 delegate_error => 'zip',
1664 field => 'm/^(id_[\d+])_user$/',
1665 delegate_error => '$1',
1670 This allows the cgi to do checking while keeping the checks from
1671 being run in JavaScript
1679 =item C<exclude_cgi>
1681 This allows the js to do checking while keeping the checks from
1682 being run in the cgi
1692 =head1 MODIFYING VALIDATION TYPES
1694 The following types will modify the form value before it is processed.
1695 They work in both the perl and in javascript as well. The javascript
1696 version changes the actual value in the form on appropriate form types.
1700 =item C<do_not_trim>
1702 By default, validate will trim leading and trailing whitespace
1703 from submitted values. Set do_not_trim to 1 to allow it to
1706 {field => 'foo', do_not_trim => 1}
1708 =item C<trim_control_chars>
1710 Off by default. If set to true, removes characters in the
1711 \x00 to \x31 range (Tabs are translated to a single space).
1713 {field => 'foo', trim_control_chars => 1}
1717 Pass a swap pattern to change the actual value of the form.
1718 Any perl regex can be passed but it is suggested that javascript
1719 compatible regexes are used to make generate_js possible.
1721 {field => 'foo', replace => 's/(\d{3})(\d{3})(\d{3})/($1) $2-$3/'}
1725 Set item to default value if there is no existing value (undefined
1726 or zero length string).
1728 {field => 'country', default => 'EN'}
1730 =item C<to_upper_case> and C<to_lower_case>
1732 Do what they say they do.
1736 Requires that the validated field has been also checked with
1737 an enum, equals, match, compare, custom, or type check. If the
1738 field has been checked and there are no errors - the field is "untainted."
1740 This is for use in conjunction with perl's -T switch.
1746 Failed validation results in an error an error object created via the
1747 new_error method. The default error class is CGI::Ex::Validate::Error.
1749 The error object has several methods for determining what the errors were.
1755 Returns an array or arrayref (depending on scalar context) of errors that
1756 occurred in the order that they occurred. Individual groups may have a heading
1757 and the entire validation will have a heading (the default heading can be changed
1758 via the 'as_array_title' group option). Each error that occurred is a separate
1759 item and are pre-pended with 'as_array_prefix' (which is a group option - default
1760 is ' '). The as_array_ options may also be set via a hashref passed to as_array.
1761 as_array_title defaults to 'Please correct the following items:'.
1763 ### if this returns the following
1764 my $array = $err_obj->as_array;
1766 # ['Please correct the following items:', ' error1', ' error2']
1768 ### then this would return the following
1769 my $array = $err_obj->as_array({
1770 as_array_prefix => ' - ',
1771 as_array_title => 'Something went wrong:',
1774 # ['Something went wrong:', ' - error1', ' - error2']
1778 Returns values of as_array joined with a newline. This method is used as
1779 the stringification for the error object. Values of as_array are joined with
1780 'as_string_join' which defaults to "\n". If 'as_string_header' is set, it will
1781 be pre-pended onto the error string. If 'as_string_footer' is set, it will be
1782 appended onto the error string.
1784 ### if this returns the following
1785 my $string = $err_obj->as_string;
1786 # $string looks like
1787 # "Please correct the following items:\n error1\n error2"
1789 ### then this would return the following
1790 my $string = $err_obj->as_string({
1791 as_array_prefix => ' - ',
1792 as_array_title => 'Something went wrong:',
1793 as_string_join => '<br />',
1794 as_string_header => '<span class="error">',
1795 as_string_footer => '</span>',
1797 # $string looks like
1798 # '<span class="error">Something went wrong:<br /> - error1<br /> - error2</span>'
1802 Returns a hash or hashref (depending on scalar context) of errors that
1803 occurred. Each key is the field name of the form that failed
1804 validation with 'as_hash_suffix' added on as a suffix. as_hash_suffix
1805 is available as a group option and may also be passed in via a
1806 hashref as the only argument to as_hash. The default value is
1807 '_error'. The values of the hash are arrayrefs of errors that
1808 occurred to that form element.
1810 By default as_hash will return the values of the hash as arrayrefs (a
1811 list of the errors that occurred to that key). It is possible to also
1812 return the values as strings. Three options are available for
1813 formatting: 'as_hash_header' which will be pre-pended onto the error
1814 string, 'as_hash_footer' which will be appended, and 'as_hash_join'
1815 which will be used to join the arrayref. The only argument required
1816 to force the stringification is 'as_hash_join'.
1818 ### if this returns the following
1819 my $hash = $err_obj->as_hash;
1821 # {key1_error => ['error1', 'error2']}
1823 ### then this would return the following
1824 my $hash = $err_obj->as_hash({
1825 as_hash_suffix => '_foo',
1826 as_hash_join => '<br />',
1827 as_hash_header => '<span class="error">'
1828 as_hash_footer => '</span>'
1831 # {key1_foo => '<span class="error">error1<br />error2</span>'}
1835 =head1 GROUP OPTIONS
1837 Any key in a validation hash matching the pattern
1838 m/^(group|general)\s+(\w+)$/ is considered a group option (the reason
1839 that either group or general may be used is that CGI::Ex::Validate
1840 used to have the concept of validation groups - these were not
1841 commonly used so support has been deprecated as of the 2.10 release).
1842 Group options will also be looked for in the Validate object ($self)
1843 and can be set when instantiating the object ($self->{raise_error} is
1844 equivalent to $valhash->{'group raise_error'}). The current know
1847 Options may also be set globally before calling validate by
1848 populating the %DEFAULT_OPTIONS global hash.
1854 Used as a group section heading when as_array or as_string is called
1855 by the error object.
1857 'group title' => 'Title of errors',
1861 Order in which to validate key/value pairs of group.
1863 'group order' => [qw(user pass email OR phone)],
1867 Arrayref of validation items to validate.
1869 'group fields' => [{
1877 =item C<validate_if>
1879 If specified - the entire hashref will only be validated if
1880 the "if" conditions are met.
1882 'group validate_if => {field => 'email', required => 1},
1884 This group would only validate all fields if the email field
1887 =item C<raise_error>
1889 If raise_error is true, any call to validate that fails validation
1890 will die with an error object as the value.
1892 =item C<no_extra_fields>
1894 If no_extra_fields is true, validate will add errors for any field found
1895 in form that does not have a field_val hashref in the validation hash.
1896 Default is false. If no_extra_fields is set to 'used', it will check for
1897 any keys that were not in a group that was validated.
1899 An important exception to this is that field_val hashrefs or field names listed
1900 in a validate_if or required_if statement will not be included. You must
1901 have an explicit entry for each key.
1905 These items allow for an override of the default errors.
1907 'group required_error' => '$name is really required',
1908 'group max_len_error' => '$name must be shorter than $value characters',
1910 my $self = CGI::Ex::Validate->new({
1911 max_len_error => '$name must be shorter than $value characters',
1914 =item C<as_array_title>
1916 Used as the section title for all errors that occur, when as_array
1917 or as_string is called by the error object.
1919 =item C<as_array_prefix>
1921 Used as prefix to individual errors that occur, when as_array
1922 or as_string is called by the error object. Each individual error
1923 will be prefixed with this string. Headings will not be prefixed.
1926 =item C<as_string_join>
1928 When as_string is called, the values from as_array will be joined with
1929 as_string_join. Default value is "\n".
1931 =item C<as_string_header>
1933 If set, will be pre-pended onto the string when as_string is called.
1935 =item C<as_string_footer>
1937 If set, will be pre-pended onto the string when as_string is called.
1939 =item C<as_hash_suffix>
1941 Added on to key names during the call to as_hash. Default is '_error'.
1943 =item C<as_hash_join>
1945 By default, as_hash will return hashref values that are errors joined with
1946 the default as_hash_join value of <br />. It can also return values that are
1947 arrayrefs of the errors. This can be done by setting as_hash_join to a non-true value
1950 =item C<as_hash_header>
1952 If as_hash_join has been set to a true value, as_hash_header may be set to
1953 a string that will be pre-pended on to the error string.
1955 =item C<as_hash_footer>
1957 If as_hash_join has been set to a true value, as_hash_footer may be set to
1958 a string that will be postpended on to the error string.
1962 If set to true, the javascript validation will not attempt to generate inline
1963 errors. Default is true. Inline errors are independent of confirm and alert
1966 'general no_inline' => 1,
1970 If set to true, the javascript validation will try to use an alert instead
1971 of a confirm to inform the user of errors. Alert and confirm are independent
1972 or inline errors. Default is false.
1974 'general no_confirm' => 1,
1978 If set to true, the javascript validation will not show an alert box
1979 when errors occur. Default is false. This option only comes into
1980 play if no_confirm is also set. This option is independent of inline
1981 errors. Although it is possible to turn off all errors by setting
1982 no_inline, no_confirm, and no_alert all to 1, it is suggested that at
1983 least one of the error reporting facilities is left on.
1985 'general no_alert' => 1,
1991 CGI::Ex::Validate provides for having duplicate validation on the
1992 client side as on the server side. Errors can be shown in any
1993 combination of inline and confirm, inline and alert, inline only,
1994 confirm only, alert only, and none. These combinations are controlled
1995 by the group options no_inline, no_confirm, and no_alert.
1996 Javascript validation can be generated for a page using the
1997 C<-E<gt>generate_js> Method of CGI::Ex::Validate. It is also possible
1998 to store the validation inline with the html. This can be done by
1999 giving each of the elements to be validated an attribute called
2000 "validation", or by setting a global javascript variable called
2001 "document.validation" or "var validation". An html file containing this
2002 validation will be read in using CGI::Ex::Conf::read_handler_html.
2004 All inline html validation must be written in yaml.
2006 It is anticipated that the html will contain something like either of the
2009 <script src="/cgi-bin/js/CGI/Ex/yaml_load.js"></script>
2010 <script src="/cgi-bin/js/CGI/Ex/validate.js"></script>
2012 // \n\ allows all browsers to view this as a single string
2013 document.validation = "\n\
2014 general no_confirm: 1\n\
2015 general no_alert: 1\n\
2016 group order: [username, password]\n\
2024 if (document.check_form) document.check_form('my_form_name');
2027 Alternately we can use element attributes:
2029 <form name="my_form_name">
2031 Username: <input type=text size=20 name=username validation="
2035 <span class=error id=username_error>[% username_error %]</span><br>
2037 Password: <input type=text size=20 name=password validation="
2041 <span class=error id=password_error>[% password_error %]</span><br>
2047 <script src="/cgi-bin/js/CGI/Ex/yaml_load.js"></script>
2048 <script src="/cgi-bin/js/CGI/Ex/validate.js"></script>
2050 if (document.check_form) document.check_form('my_form_name');
2053 The read_handler_html from CGI::Ex::Conf will find either of these
2054 types of validation.
2056 If inline errors are asked for, each error that occurs will attempt
2057 to find an html element with its name as the id. For example, if
2058 the field "username" failed validation and created a "username_error",
2059 the javascript would set the html of <span id="username_error"></span>
2060 to the error message.
2062 It is suggested to use something like the following so that you can
2063 have inline javascript validation as well as report validation errors
2064 from the server side as well.
2066 <span class=error id=password_error>[% password_error %]</span><br>
2068 If the javascript fails for some reason, the form should still be able
2069 to submit as normal (fail gracefully).
2071 If the confirm option is used, the errors will be displayed to the user.
2072 If they choose OK they will be able to try and fix the errors. If they
2073 choose cancel, the form will submit anyway and will rely on the server
2074 to do the validation. This is for fail safety to make sure that if the
2075 javascript didn't validate correctly, the user can still submit the data.
2079 Thanks to Eamon Daly for providing bug fixes for bugs in validate.js
2080 caused by HTML::Prototype.
2088 This module may be distributed under the same terms as Perl itself.
This page took 0.178785 seconds and 5 git commands to generate.