Validation::Class - Centralized Input Validation For Any Application
version 0.111910
use MyApp::Validation; my $input = MyApp::Validation->new(params => $params); unless ($input->validate){ return $input->errors->to_string; }
Validation::Class is a different approach to data validation, it attempts to simplify and centralize data validation rules to ensure DRY (don't repeat yourself) code. The primary intent of this module is to provide a simplistic validation work-flow and promote code (validation) reuse.
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; # a validation rule field 'login' => { label => 'user login', error => 'login invalid', validation => sub { my ($self, $this, $fields) = @_; return $this->{value} eq 'admin' ? 1 : 0; } }; # a validation rule field 'password' => { label => 'user password', error => 'password invalid', validation => sub { my ($self, $this, $fields) = @_; return $this->{value} eq 'pass' ? 1 : 0; } }; 1;
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; # a validation rule template mixin 'basic' => { required => 1, min_length => 1, max_length => 255, filters => ['lowercase', 'alphanumeric'] }; # a validation rule field 'user:login' => { mixin => 'basic', label => 'user login', error => 'login invalid', validation => sub { my ($self, $this, $fields) = @_; return $this->{value} eq 'admin' ? 1 : 0; } }; # a validation rule field 'user:password' => { mixin => 'basic', label => 'user login', error => 'login invalid', validation => sub { my ($self, $this, $fields) = @_; return $this->{value} eq 'pass' ? 1 : 0; } }; 1;
The mixin keyword creates a validation rules template that can be applied to any field using the mixin directive.
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; mixin 'constrain' => { required => 1, min_length => 1, max_length => 255, ... }; field 'login' => { mixin => 'constrain', ... };
The filter keyword creates custom filters to be used in your field definitions.
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; filter 'telephone' => sub { ... }; field 'telephone' => { filter => ['trim', 'telephone'], ... };
The directive keyword creates custom validator directives to be used in your field definitions. The routine is passed two parameters, the value of directive and the value of the field the validator is being processed against. The validator should return true or false.
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; directive 'between' => sub { my ($directive, $value, $field, $class) = @_; my ($min, $max) = split /\-/, $directive; unless ($value > $min && $value < $max) { my $handle = $field->{label} || $field->{name}; $class->error($field, "$handle must be between $directive"); return 0; } return 1; }; field 'hours' => { between => '00-24', ... };
The field keyword create a validation block and defines validation rules for reuse in code. The field keyword should correspond with the parameter name expected to be passed to your validation class.
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; field 'login' => { required => 1, min_length => 1, max_length => 255, ... };
The field keword takes two arguments, the field name and a hashref of key/values pairs. The keys are referred to as directives, those directives are as follows:
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; # a validation template mixin '...' => { ... }; # a validation rule field '...' => { mixin => '...', ... }; 1;
When building a validation class, the first encountered and arguably two most important keyword functions are field() and mixin() which are used to declare their respective properties. A mixin() declares a validation template where its properties are intended to be copied within field() declarations which declares validation rules and properties.
Both the field() and mixin() declarations/functions require two parameters, the first being a name, used to identify the declaration, and the second being a hashref of key/value pairs. The key(s) within a declaration are commonly referred to as directives.
The following is a list of default directives which can be used in field/mixin declarations:
# the label directive field 'foobar' => { label => 'Foo Bar', ... };
# the alias directive field 'foobar' => { alias => 'foo_bar', ... };
mixin 'abcxyz' => { ... }; # the mixin directive field 'foobar' => { mixin => 'abcxyz', ... };
# the mixin_field directive field 'foobar' => { mixin_field => '...', ... };
# the validation directive field 'foobar' => { validation => '...', ... };
# the error(s) directive field 'foobar' => { errors => '...', ... };
# the value directive field 'foobar' => { value => '...', ... };
# the name directive field 'foobar' => { name => '...', ... };
# the filter(s) directive field 'foobar' => { filter => '...', ... };
The following is a list of default filters that may be used with the filter directive:
field 'foobar' => { filter => 'trim', };
field 'foobar' => { filter => 'alpha', };
field 'foobar' => { filter => 'currency', };
field 'foobar' => { filter => 'strip', };
field 'foobar' => { filter => 'numeric', };
field 'foobar' => { filter => 'uppercase', };
field 'foobar' => { filter => 'titlecase', };
field 'foobar' => { filter => 'capitalize', };
field 'foobar' => { filter => 'lowercase', };
field 'foobar' => { filter => 'alphanumeric', };
# the required directive field 'foobar' => { required => '...', ... };
package MyApp::Validation; use Validation::Class; use base 'Validation::Class'; # a validation rule with validator directives field '...' => { min_length => '...', max_length => '...', pattern => '+# (###) ###-####', ... }; 1;
Validator directives are special directives with associated validation code that is used to validate common use-cases such as "checking the length of a parameter", etc.
The following is a list of the default validators which can be used in field/mixin declarations:
# the min_length directive field 'foobar' => { min_length => '...', ... };
# the max_length directive field 'foobar' => { max_length => '...', ... };
# the between directive field 'foobar' => { between => '1-5', ... };
# the length directive field 'foobar' => { length => 20, ... };
# the pattern directive field 'telephone' => { pattern => '### ###-####', ... }; field 'country_code' => { pattern => 'XX', filter => 'uppercase' ... };
# the matches directive field 'password' => { matches => 'password_confirmation', ... };
# the options directive field 'status' => { options => 'Active, Inactive', ... };
The following is an example of how to use you constructed validation class in other code, .e.g. Web App Controller, etc.
use MyApp::Validation; my $input = MyApp::Validation->new(params => $params); unless ($input->validate('field1','field2')){ return $input->errors->to_string; }
Feeling lazy, have your validation class automatically find the appropriate fields to validate against (params must match field names).
If you are using groups in your validation class you might validate your data like so ...
use MyApp::Validation; my $input = MyApp::Validation->new(params => $params); unless ($input->validate('user:login', 'user:password')){ return $input->errors->to_string; }
Although this means that the incoming parameters need to specify its parameter names using the same group naming convention. If this is not to your liking, the validate() method can assist you in mapping your incoming parameters to your grouped validation fields as shown here:
use MyApp::Validation; my $input = MyApp::Validation->new(params => $params); unless ($input->validate({ user => 'user:login', pass => 'user:password')){ return $input->errors->to_string; }
You can also map automatically by using field aliases whereby a field definition will have an alias attribute containing an arrayref of alternate parameters that can be matched against passed-in parameters as an alternative to the parameter mapping technique. The whole mapping technique can get cumbersome in larger projects.
package MyApp::Validation; field 'foo:bar' => { ..., alias => [ 'foo', 'bar', 'baz', 'bax' ] }; use MyApp::Validation; my $input = MyApp::Validation->new(params => { foo => 1 }); unless ($input->validate(){ return $input->errors->to_string; }
The new method instantiates and returns an instance of your validation class.
use MyApp::Validation; my $input = MyApp::Validation->new; $input->params($params); ...
or
my $input = MyApp::Validation->new(params => $params); ...
The fields attribute returns a hashref of defined fields, filtered and merged with thier parameter counterparts.
my $self = MyApp::Validation->new(fields => $fields); my $fields = $self->fields(); ...
The filters attribute returns a hashref of pre-defined filter definitions.
my $filters = $self->filters(); ...
The ignore_unknown boolean determines whether your application will live or die upon encountering unregistered fields during validation.
my $self = MyApp::Validation->new(params => $params, ignore_unknown => 1); $self->ignore_unknown(1); ...
The report_unknown boolean determines whether your application will report unregistered fields as class-level errors upon encountering unregistered fields during validation.
my $self = MyApp::Validation->new(params => $params, ignore_unknown => 1, report_unknown => 1); $self->report_unknown(1); ...
The params attribute gets/sets the parameters to be validated.
my $input = { ... }; my $self = MyApp::Validation->new(params => $input); $self->params($input); my $params = $self->params(); ...
The mixins attribute returns a hashref of defined validation templates.
my $mixins = $self->mixins(); ...
The validate method returns true/false depending on whether all specified fields passed validation checks.
use MyApp::Validation; my $input = MyApp::Validation->new(params => $params); # validate specific fields unless ($input->validate('field1','field2')){ return $input->errors->to_string; } # validate all fields, regardless of parameter existence unless ($input->validate()){ return $input->errors->to_string; } # validate all existing parameters unless ($input->validate(keys %{$input->params})){ return $input->errors->to_string; } # validate specific parameters (by name) after mapping them to other fields my $map = { param1 => 'field_abc', param2 => 'field_def' }; unless ($input->validate($map)){ return $input->errors->to_string; }
The following are convenience functions for handling your input data after processing and data validation.
The get_params method returns the values (in list form) of the parameters specified.
if ($self->validate) { my $name = $self->get_params('name'); my ($name, $email, $login, $password) = $self->get_params(qw/name email login password/); # you should note that if the params dont exist they will return undef # ... meaning you should check that it exists before checking its value # e.g. if (defined $name) { if ($name eq '') { print 'name parameter was passed but was empty'; } } else { print 'name parameter was never submitted'; } }
The most important part of any input validation framework is its ease-of-use and its error handling. Validation::Class gives you the ability to bypass, override and/or clear errors at-will without a hassle. The following methods assist you in doing just that.
The error_fields method returns a hashref of fields whose value is an arrayref of error messages.
unless ($self->validate) { my $fields = $self->error_fields(); }
The reset_errors method clears all errors, both at the class and individual field levels. This method is called automatically everytime the validate() method is triggered.
$self->reset_errors();
The error function is used to set and/or retrieve errors encountered during validation. The error function with no parameters returns the error message object which is an arrayref of error messages stored at class-level.
# return all errors encountered/set as an arrayref return $self->error(); # return all errors specific to the specified field (at the field-level) # as an arrayref return $self->error('some_param'); # set an error specific to the specified field (at the field-level) # using the field object (hashref not field name) $self->error($field_object, "i am your error message"); unless ($self->validate) { my $fields = $self->error(); }
The errors function returns a special class (Validation::Class::Errors) used to add convenience methods to the error objects. This class can be utilized as follows.
# by default uses errors specified at the class-level return $self->errors; # count() method returns the number of errors encoutered return $self->errors->count(); # to_string($delimiter) method strigifies the error arrayref object using # the specified delimiter or ', ' by default return $self->errors->to_string(); return $self->errors->to_string("<br/>\n"); # use errors at the field-level in the errors class return $self->errors($self->fields->{some_field})->count(); unless ($self->validate) { return $self->errors->to_string; }
Al Newkirk <awncorp@cpan.org>
This software is copyright (c) 2010 by awncorp.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Validation::Class, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Validation::Class
CPAN shell
perl -MCPAN -e shell install Validation::Class
For more information on module installation, please visit the detailed CPAN module installation guide.