The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Dancer2-Plugin-DataTransposeValidator-0.201
River stage zero No dependents
/ Dancer2::Plugin::DataTransposeValidator

NAME

Dancer2::Plugin::DataTransposeValidator - Data::Transpose::Validator plugin for Dancer2

VERSION

Version 0.201

SYNOPSIS


            

              
              
use Dancer2::Plugin::DataTransposeValidator;
post '/' => sub {
    my $params = params;
    my $data = validator($params, 'myrule');
    if ( $data->valid ) { ... }
}

DESCRIPTION

Dancer2 plugin for for Data::Transpose::Validator

FUNCTIONS

This module exports the single function validator.

validator( $params, $rules, @additional_args? )

Where:

$params is a hash reference of parameters to be validated.

$rules is one of:

  • the name of a rule sub if you are using "rules_class"

  • the name of a rule file if you are using "rules_dir"

  • a hash reference of rules

  • a code reference that will return a hashref of rules

Any optional @additional_args are passed as arguments to code references/subs.

A Dancer2::Plugin::DataTransposeValidator::Validator object is returned with the following methods:

  • valid

    A boolean 1/0 showing whether the parameters validated correctly or not.

  • values

    The transposed values as a hash reference.

  • errors

    A hash reference containing one key for each parameter which failed validation. See "errors_hash" in "CONFIGURATION" for an explanation of what the value of each parameter key will be.

  • css

    A hash reference containing one key for each parameter which failed validation. The value for each parameter is a css class. See "css_error_class" in "CONFIGURATION".

NOTE: If you wish to return this object as JSON then you must ensure that you have configured the JSON serializer something like:


            

              
              
set engines => { serializer => { JSON => { convert_blessed => 1 } } };

so you can do something like:


            

              
              
post '/default' => sub {
    my $params = params;
    my $data   = validator( $params, 'rules1' );
    send_as JSON => $data;
};

CONFIGURATION

The following configuration settings are available (defaults are shown here):


            

              
              
plugins:
  DataTransposeValidator:
    css_error_class: has-error
    errors_hash: 0
    rules_class: MyApp::ValidationRules
    # OR:
    rules_dir: validation

css_error_class

The class returned as a value for parameters in the css key of the hash reference returned by "validator".

errors_hash

This can has a number of different values:

  • A false value (the default) means that only a single scalar error string will be returned for each parameter error. This will be the first error returned for the parameter by "errors_hash" in Data::Transpose::Validator.

  • joined

    All errors for a parameter will be returned joined by a full stop and a space.

  • arrayref

    All errors for a parameter will be returned as an array reference.

rules_class

This is much preferred over "rules_dir" since it does not eval external files.

This is a class (package) name such as MyApp::Validator::Rules. There should be one sub for each rule name inside that class which returns a hash reference. See "RULES CLASS" for examples.

rules_dir

Subdirectory of "appdir" in Dancer2::Config in which rules files are stored. NOTE: We recommend you do not use this approach since the rules files are eval'ed with all the security risks that entails. Please use "rules_class" instead. You have been warned. See "RULES DIR" for examples.

RULES CLASS

The rules class allows the "validator" to be configured using all options available in Data::Transpose::Validator. The rules class must contain one sub for each rule name which will be passed any @optional_args.


            

              
              
package MyApp::ValidationRules;
sub register {
    # simple hashref
    +{
        options => {
            stripwhite => 1,
            collapse_whitespace => 1,
            requireall => 1,
        },
        prepare => {
            email => {
                validator => "EmailValid",
            },
            email2 => {
                validator => "EmailValid",
            },
            emails => {
                validator => 'Group',
                fields => [ "email", "email2" ],
            },
        },
    };
}
sub change_password {
    # args and hashref
    my %args = @_;
    +{
        options => {
            requireall => 1,
        },
        prepare => {
            old_password => {
                required  => 1,
                validator => sub {
                    if ( $args{logged_in_user}->check_password( $_[0] ) ) {
                        return 1;
                    }
                    else {
                        return ( undef, "Password incorrect" );
                    }
                },
            },
            password => {
                required  => 1,
                validator => {
                    class   => 'PasswordPolicy',
                    options => {
                        username      => $args{logged_in_user}->username,
                        minlength     => 8,
                        maxlength     => 70,
                        patternlength => 4,
                        mindiffchars  => 5,
                        disabled      => {
                            digits   => 1,
                            mixed    => 1,
                            specials => 1,
                        }
                    }
                }
            },
            confirm_password => { required => 1 },
            passwords        => {
                validator => 'Group',
                fields    => [ "password", "confirm_password" ],
            },
        },
    };
}
1;

RULES DIR

The rules file format allows the "validator" to be configured using all options available in Data::Transpose::Validator. The rules file must contain a valid hash reference, e.g.:


            

              
              
{
    options => {
        stripwhite => 1,
        collapse_whitespace => 1,
        requireall => 0,
        unknown => "fail",
        missing => "undefine",
    },
    prepare => {
        email => {
            validator => "EmailValid",
            required => 1,
        },
        email2 => {
            validator => {
                class => "MyValidator::EmailValid",
                absolute => 1,
            }
        },
        field4 => {
            validator => {
                sub {
                    my $field = shift;
                    if ( $field =~ /^\d+/ && $field > 0 ) {
                        return 1;
                    }
                    else {
                        return ( undef, "Not a positive integer" );
                    }
                }
            }
        }
    }
}

Note that the value of the prepare key must be a hash reference since the array reference form of "prepare" in Data::Transpose::Validator is not supported.

As an alternative the rules file can contain a code reference, e.g.:


            

              
              
sub {
    my $username = shift;
    return {
        options => {
            stripwhite => 1,
        },
        prepare => {
            password => {
                validator => {
                    class => 'PasswordPolicy',
                    options => {
                        username  => $username,
                        minlength => 8,
                    }
                }
            }
        }
    };
}

The code reference receives the @additional_args passed to "validator". The code reference must return a valid hash reference.

SEE ALSO

Dancer2, Data::Transpose

ACKNOWLEDGEMENTS

Alexey Kolganov for Dancer::Plugin::ValidateTiny which inspired a number of aspects of the original version of this plugin.

Stefan Hornburg (Racke) for his valuable feedback.

AUTHOR

Peter Mottram (SysPete), <peter@sysnix.com>

COPYRIGHT AND LICENSE

Copyright 2015-2016 Peter Mottram (SysPete).

This program is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.