Data::Transpose::Validator plugin for Dancer2
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib/Dancer2/Plugin
t
.gitignore
.travis.yml
Changes
MANIFEST
MANIFEST.SKIP
Makefile.PL
README
README.md

README.md

NAME

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

VERSION

Version 0.100

SYNOPSIS

use Dancer2::Plugin::DataTransposeValidator;

post '/' => sub {
    my $params = params;
    my $data = validator($params, 'rules-file');
    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 hash reference with the following keys is returned:

  • 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".

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.