Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

754 lines (404 sloc) 17.189 kb

NAME

Validation::Class - Self-Validating Object System and Data Validation Framework

VERSION

version 7.10_01

SYNOPSIS

package MyVal::User;


use Validation::Class;


# rules mixin


mxn basic       => {
    required    => 1,
    max_length  => 255,
    filters     => [qw/trim strip/]
}; 


# attr(s) w/rules


fld id          => {
    mixin       => 'basic',
    max_length  => 11,
    required    => 0
};


fld name        => {
    mixin       => 'basic',
    min_length  => 2
};


fld email       => {
    mixin       => 'basic',
    min_length  => 3
};


fld login       => {
    mixin       => 'basic',
    min_length  => 5
};


fld password    => {
    mixin       => 'basic',
    min_length  => 5,
    min_symbols => 1
};


# just an attr


has attitude => 1; 


# self-validating method (even better than method signatures)


mth create  => {


    input   => [qw/name email login password/],
    output  => ['+id'],


    using   => sub {


        my ($self, @args) = @_;


        # make sure to set id for output validation


    }


}; 


package main;


my $user = MyVal::User->new(name => '...', email => '...');


unless ($user->create) {


    # did you forget your login and pass?


}


1;

Validation::Class takes a different approach towards data modeling and validation, it centralizes data validation rules to ensure consistency through DRY (dont-repeat-yourself) code.

use MyApp;


my $params = {
   'user.login' => '...',
   'user.pass' => '...'
};


my $app = MyApp->new(params => $params);


my $user = $app->class('user'); # instantiated MyApp::User object


unless ($user->validate('login', 'pass')){


    # do something with ... $input->errors;


}

DESCRIPTION

Validation::Class is much more than a robust data validation framework, in-fact it is more of a data modeling framework and can be used as an alternative to minimalistic object systems such as Moo, Mo, etc.

Validation::Class aims to provide the building blocks for easily definable self-validating data models.

When fields (attributes with validation rules) are defined, accessors are automatically generated to make getting and setting their values much easier.

Methods can be defined using the method keyword to create a self-validating method, checking the defined input requirements against existing validation rules before executing the routine, gaining consistency and security.

KEYWORDS

attribute

The attribute keyword (or has) creates a class attribute.

package MyApp::User;


use Validate::Class;


attribute 'attitude' => sub {


    return $self->bothered ? 1 : 0 


};


1;

The attribute keyword takes two arguments, the attribute name and a constant or coderef that will be used as its default value.

build

The build keyword (or bld) registers a coderef to be run at instantiation much in the same way the common BUILD routine is used in modern-day OO systems.

package MyApp::User;


use Validation::Class;


build sub {


    my $self = shift;


    # ... do something


};

The build keyword takes one argument, a coderef which is passed the instantiated class object.

directive

The directive keyword (or dir) creates custom validator directives to be used in your field definitions. It is a means of extending the pre-existing directives table before runtime and is ideal for creating custom directive extension packages to be used in all your classes.

package MyApp::Directives;


use Validation::Class;
use Data::Validate::Email;


directive 'is_email' => sub {


    my ($dir, $value, $field, $self) = @_;


    my $validator = Data::Validate::Email->new;


    unless ($validator->is_email($value)) {


        my $handle = $field->{label} || $field->{name};


        $self->errors->add_error("$handle must be a valid email address");


        return 0;


    }


    return 1;


};


package MyApp::User;


use Validate::Class;
use MyApp::Directives;


field 'email' => {
    is_email => 1,
    ...
};


1;

The directive keyword takes two arguments, the name of the directive and a coderef which will be used to validate the associated field. The coderef is passed four ordered parameters, the value of directive, the value of the field (parameter value), the field object (hashref), and the instantiated class object. The validator MUST return true or false.

Additionally, if you only desire to extend the list of acceptable directives, you can create a no-op by simply returning true, e.g.:

directive 'new_addition' => sub {1};

field

The field keyword (or fld) creates an attribute with validation rules for reuse in code. The field name should correspond with the parameter name expected to be passed to your validation class.

package MyApp::User;


use Validation::Class;


field 'login' => {
    required   => 1,
    min_length => 1,
    max_length => 255,
    ...
};

The field keyword takes two arguments, the field name and a hashref of key/values pairs known as directives.

The field keyword also creates accessors which provide easy access to the field's corresponding parameter value(s). Accessors will be created using the field's name as a label having any special characters replaced with an underscore.

field 'login' => {
    required   => 1,
    min_length => 1,
    max_length => 255,
    ...
};


field 'preference.send_reminders' => {
    required   => 1,
    max_length => 1,
    ...
};


field 'preference.send_reminders.text:0' => {
    ...
};


my $value = $self->login;


$self->login($new_value); # arrayrefs and hashrefs will be flattened


$self->preference_send_reminders;


$self->preference_send_reminders_text_0;

Protip: Field directives are used to validate scalar and array data. Don't use fields to store and validate blessed objects. Please see the has keyword instead.

filter

The filter keyword (or flt) creates custom filters to be used in your field definitions. It is a means of extending the pre-existing filters table before runtime and is ideal for creating custom directive extension packages to be used in all your classes.

package MyApp::Directives;


use Validation::Class;


filter 'flatten' => sub {


    $_[0] =~ s/[\t\r\n]+/ /g;
    $_[0] # return


};


package MyApp::User;


use Validate::Class;
use MyApp::Directives;


field 'description' => {
    filters => ['trim', 'flatten'],
    ...
};


1;

The filter keyword takes two arguments, the name of the filter and a coderef which will be used to filter the value the associated field. The coderef is passed the value of the field and that value MUST be operated on directly. The coderef should also return the transformed value.

load

The load keyword (or set), which can also be used as a method, provides options for extending the current class by attaching other Validation::Class classes as relatives, roles, plugins, etc. The process of applying roles to the current class mainly involve copying the role's methods and configuration.

package MyApp;


use Validation::Class;


# load stuff (extend MyApp)


load {
    ...
};


1;

The load.classes option, can be a constant or arrayref and uses Module::Find to load all child classes (in-all-subdirectories) for convenient access through the class() method. Existing parameters and configuration options are passed to the child class' constructor. All attributes can be easily overwritten using the attribute's accessors on the child class. These child classes are often referred to as relatives. This option accepts a constant or an arrayref of constants.

package MyApp;


use Validation::Class;


# load all child classes


load {
    classes => [
        __PACKAGE__
    ]
};


package main;


my $app = MyApp->new;


my $rel = $app->class('relative'); # new MyApp::Relative object


my $rel = $app->class('data_source'); # MyApp::DataSource
my $rel = $app->class('datasource-first'); # MyApp::Datasource::First


1;

The load.plugins option is used to load plugins that support Validation::Class. A Validation::Class plugin is little more than a class that implements a "new" method that extends the associated validation class object. As usual, an official Validation::Class plugin can be referred to using shorthand while custom plugins are called by prefixing a plus symbol to the fully-qualified plugin name. Learn more about plugins at Validation::Class::Intro. This option accepts a constant or an arrayref of constants.

package MyVal;


load {
    plugins => [
        'CPANPlugin', # Validation::Class::Plugin::CPANPlugin
        '+MyVal::Plugin'
    ]
};


1;

The load.roles option is used to load and inherit functionality from child classes, these classes should be used and thought-of as roles. Any validation class can be used as a role with this option. This option accepts a constant or an arrayref of constants.

package MyVal::User;


load {
    roles => [
        'MyVal::Person'
    ]
};


1;

method

The method keyword (or mth) is used to create an auto-validating method. Similar to method signatures, an auto-validating method can leverage pre-existing validation rules and profiles to ensure a method has the required data necessary to proceed.

package MyApp::User;


use Validation::Class;


method 'register' => {


    input  => ['name', '+email', 'login', '+password'],
    output => ['+id'], # optional output validation, dies on failure
    using  => sub {


        my ($self, @args) = @_;


        # .... do something registrationy


        $self->id(...); # set the ID field for output validation


        return $self;


    }


};


package main;


my $user = MyApp::User->new(params => $params);


if ($user->register) {
    ...
}


1;

The method keyword takes two arguments, the name of the method to be created and a hashref of required key/value pairs. The hashref must have an "input" variable whose value is either an arrayref of fields to be validated, or a constant value which matches a validation profile name. The hashref must also have a "using" variable whose value is a coderef which will be executed upon successfully validating the input. Whether and what the method returns is yours to decide.

Optionally the required hashref can have an "output" variable whose value is either an arrayref of fields to be validated, or a constant value which matches a validation profile name which will be used to perform data validation after the coderef has been executed. Please note that output validation failure will cause the program to die, the premise behind this decision is based on the assumption that given successfully validated input a routine's output should be predictable and if an error occurs it is most-likely a program error as opposed to a user error.

See the ignore_failure and report_failure switch to control how method input validation failures are handled.

mixin

The mixin keyword (or mxn) creates a validation rules template that can be applied to any field using the mixin directive. Mixin directives are processed first so existing field directives will override the mixed-in directives.

package MyApp::User;


use Validation::Class;


mixin 'constrain' => {
    required   => 1,
    min_length => 1,
    max_length => 255,
    ...
};


# e.g.
field 'login' => {
    mixin => 'constrain',
    ...
};

The mixin keyword takes two arguments, the mixin name and a hashref of key/values pairs known as directives.

profile

The profile keyword (or pro) stores a validation profile (coderef) which as in the traditional use of the term is a sequence of validation routines that validate data relevant to a specific action.

package MyApp::User;


use Validation::Class;


profile 'signup' => sub {


    my ($self, @args) = @_;


    return $self->validate(qw(
        +name
        +email
        +email_confirmation
        -login
        +password
        +password_confirmation
    ));


};


package main;


my $user = MyApp::User->new(params => $params);


unless ($user->validate_profile('signup')) {


    die $user->errors_to_string;


}

The profile keyword takes two arguments, a profile name and coderef which will be used to execute a sequence of actions for validation purposes.

METHODS

new

The new method instantiates a new class object, it performs a series of actions (magic) required for the class function properly, and for that reason, this method should never be overridden. Use the build keyword to hooking into the instantiation process.

package MyApp;


use Validation::Class;


# optionally


build sub {


    my ($self) = @_; # is instantiated


};


package main;


my $app = MyApp->new;


...

prototype

The prototype method (or proto) returns an instance of the associated class prototype. The class prototype is responsible for manipulating and validating the data model (current class). It is not likely that you'll need to access this method directly.

package MyApp;


use Validation::Class;


package main;


my $app = MyApp->new;


my $prototype = $app->prototype;


...

THE PROTOTYPE CLASS

This module provides mechanisms (sugar functions to model your data) which allow you to define self-validating classes. Each class your create is associated with a prototype class which provides data validation functionality and keeps your class' namespace free from pollution, please see Validation::Class::Prototype for more information on specific methods, and attributes.

All derived classes will have a prototype-class attached to it which does all the heavy lifting (regarding validation and error handling). The prototype injects a few proxy methods into your class which are basically aliases to your prototype class, however it is possible to access the prototype directly using the proto/prototype methods.

package MyApp::User;


use Validation::Class;


package main;


my $user  = MyApp::User->new;
my $proto = $user->prototype;


$proto->error_count # same as calling $self->error_count

THE OBJECT SYSTEM

All derived classes will benefit from the light-weight, straight-forward and simple object system Validation::Class provides. The standard new method should be used to instantiate a new object and the bld/build keywords can be used to hook into the instantiation process. Validation::Class does NOT provide method modifiers but can be extended with Class::Method::Modifiers.

before

before foo => sub { ... };

See "before method(s) => sub { ... }" in Class::Method::Modifiers for full documentation.

around

around foo => sub { ... };

See "around method(s) => sub { ... }" in Class::Method::Modifiers for full documentation.

after

after foo => sub { ... };

See "after method(s) => sub { ... }" in Class::Method::Modifiers for full documentation.

AUTHOR

Al Newkirk anewkirk@ana.io

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Al Newkirk.

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

Jump to Line
Something went wrong with that request. Please try again.