NAME Validation::Class - Centralized Input Validation For Any Application VERSION version 0.110280 SYNOPSIS 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. The following is an example of that... use MyApp::Validation; my $input = MyApp::Validation->new($params); unless ($input->validate('login', 'password')){ return $input->errors; } Standard Validation Class package MyApp::Validation; use Validation::Class; field 'login' => { required => 1, min_length => 1, max_length => 255 }; field 'password' => { required => 1, min_length => 1, max_length => 255 }; 1; The field keyword creates validation blocks specific to the field which makes validation easy from your script or controller. e.g. use MyApp::Validation; my $input = MyApp::Validation->new($params); unless ($input->validate('login', 'password')){ return $input->errors; } Feeling lazy, have your validation class automatically find the appropriate fields to validate against (params must match field names). use MyApp::Validation; my $input = MyApp::Validation->new($params); unless ($input->validate){ return $input->errors; } Validation Class with Mixins and Grouping package MyApp::Validation; use Validation::Class; mixin 'cds => { required => 1, }; field 'cds:id' => { mixin => 'cds' }; mixin 'artists' => { required => 1, min_length => 1, max_length => 255 }; field 'artists:id' => { mixin => 'artists' }; field 'artists:email' => { mixin => 'artists' } field 'artists:login' => { mixin => 'artists' }; field 'artists:password' => { mixin => 'artists' }; 1; The mixin keyword creates a validation template that can be applied to any field. Fields defined using a delimiter (see above) such as (:, #, -) are referred to as grouped fields which have no programmatic significance other than clearly depicting how fields relate to one another. The following is an example of additional more advanced ways to validate. e.g. use MyApp::Validation; my $input = MyApp::Validation->new($params); unless ($input->validate('artists:login', 'artists:password')){ return $input->errors; } What happens when your input parameters don't match your validation field names? In that case we want to call the validate function with field mappings as follows: use MyApp::Validation; my $fields = { login => 'artists:login', password => 'artists:password' }; my $input = MyApp::Validation->new($params); unless ($input->validate($fields)){ return $input->errors; } Validation without Class And now for my second and final act, using Validation::Class outside of a package. This is useful for your one-off scripts that won't have classes shipped with it. #!/usr/bin/perl use Validation::Class; my $input = validation_schema( mixins => { default => { required => 1, min_length => 4, max_length => 255 } }, fields => { login => { label => 'user login', mixin => 'default', validation => sub { # error out for no good reason $_[0]->error($_[1], "Err..raaaarr, ..."); } }, password => { mixin_field => 'login', label => 'user password' } } )->setup($params); unless ($input->validate) { return $input->errors; } METHODS field The field function defines the validation rules for the specified parameter it is named after. field 'some_param' => { mixin => 'default', validation => sub { my ($self, $this, $params) = @_; $self->error($this, "im an error, when you see me .. run"); } }; 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: * name The name of the field (auto set) * value The value of the parameter matching the name of the field (auto set) * mixin The template to be used to copy directives from e.g. mixin 'template' => { required => 1 }; field 'a_field' => { mixin => 'template' } * mixin_field The field to be used as a mixin (template) to have directives copied from e.g. field 'a_field' => { required => 1, min_length => 2, max_length => 10 }; field 'b_field' => { mixin_field => 'a_field' }; * validation A custom validation routine. Please note that the return value is not important. Please register an error if validation fails e.g. field '...' => { validation => sub { my ($self, $this, $parameters) = @_; $self->error($this, "I failed") if $parameters->{something}; } }; * errors The collection of errors encountered during processing (auto set arrayref) * label An alias for the field name, something more human-readable, is also used in auto-generated error messages * error A custom error message, displayed instead of the generic ones * required Determines whether the field is required or not, takes 1 or 0 * min_length Determines the minimum length of characters allowed * max_length Determines the maximum length of characters allowed * ref_type Determines whether the field value is a valid perl reference variable * regex Determines whether the field value passes the supplied regular expression e.g. field 'c_field' => { label => 'a field labeled c', error => 'a field labeled c cannot be ...', required => 1, min_length => 2, max_length => 25, ref_type => 'array', regex => '^\d+$' }; * filter An alias for the filters directive * filters Set filters to manipulate the data before validation, e.g. field 'd_field' => { ..., filters => [ 'trim', 'strip' ] }; field 'e_field' => { filter => 'strip' }; field 'f_field' => { filters => [ 'trim', sub { $_[0] =~ s/(abc)|(123)//; } ] }; # the following filters can be set using the filter(s) keywords: field 'g_field' => { filters => [ 'trim', 'alpha', 'digit', 'strip', 'numeric ', 'lowercase', 'uppercase', 'titlecase', 'camelcase', 'lowercase', 'alphanumeric', sub { my $value = shift; } ] }; mixin The mixin function defines validation rule templates to be later reused within fields. mixin 'default' => { required => 1, min_length => 4, max_length => 255, ... }; error_fields The error_fields function is used to get a hash reference containing all fields with validation errors as keys and their corresponding error messages as values. error The error(s) 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. # return all errors encountered/set return $self->error(); # return all errors specific to the specified field return $self->error('some_param'); # set an error specific to the specified field $self->error($field_obj, "i am your error message"); validate The validate function sequentially checks the passed-in field names against their defined validation rules and returns 0 or 1 based on the existence of errors for each within each field. # find fields based on input parameters and validate them $input->validate; # validate specific fields (validates in the order specified) $input->validate('login', 'password'); # map parameters to fields then validate (no validation order) $input->validate({ 'login' => 'users:login', 'password' => 'users:password' }); params The params function is used to get a hash reference containing all the passed-in input paramters. This is useful and neccessary when your rules have filters that perform transformations and you want to use the altered values. validation_schema The validation_schema method encapsulates fields and mixins and returns a Validation::Class instance for further validation. This method exist for situations where Validation::Class is used outside of a specific validation package. my $i = validation_schema( mixins => { 'default' => { required => 1 } }, fields => { 'test1' => { mixin => 'default' } } )->setup({ test1 => '...' }); unless ($i->validate('test1')) { return $i->errors; } AUTHOR Al Newkirk COPYRIGHT AND LICENSE 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.