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 <awncorp@cpan.org>

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.

