# NAME

Validation::Class - Low-Fat Full-Flavored Data Modeling and Validation Framework

# VERSION

version 5.83

# 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
    

    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 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 simple 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](http://search.cpan.org/perldoc?Moo), [Mo](http://search.cpan.org/perldoc?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 which can make the routine
self-validating, 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->error($field, "$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.

## field

The field keyword (or fld) creates an attribute with validation rules for reuse
in code. The field keyword may also 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.

Protip: Fields are used to validate constant and array data, not hashrefs and
objects. Don't try to use fields like attributes (use 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](http://search.cpan.org/perldoc?Validation::Class) classes
as roles. The process of applying roles to the current class mainly involve
copying the role's methods and configuration.

    package MyApp;
    

    use Validation::Class;
    

    # load specific child class
    

    load {
        ...
    };
    

    1;

The `load.class` option, can be a constant or arrayref, will require other
classes specifically and add them to the relationship map 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.

    package MyApp;
    

    use Validation::Class;
    

    # load specific child class
    

    load {
        class => 'MyApp::Relative'
    };
    

    package main;
    

    my $app = MyApp->new;
    

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

    1;

The `load.classes` option, can be a constant or arrayref, uses [Module::Find](http://search.cpan.org/perldoc?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.

    package MyApp;
    

    use Validation::Class;
    

    # load specific child class
    

    load {
        classes => 1
    };
    

    package main;
    

    my $app = MyApp->new;
    

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

    my $rel = $app->class('data_source'); # MyApp::DataSource
    my $rel = $app->class('data_source-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::Cookbook](http://search.cpan.org/perldoc?Validation::Class::Cookbook).

    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.

    package MyVal::User;
    

    load {
        role => 'MyVal::Person'
    };
    

    # or
    

    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, exported into the calling namespace automatically, should NOT be
tampered with. The new method performs a series of actions (magic) required for
the class to function properly. See the build keyword for hooking into the
instantiation process.

    package MyApp;
    

    use Validation::Class;
    

    package main;
    

    my $app = MyApp->new;
    

    ...

# ATTRIBUTES, METHODS, AND MORE

This class encapsulates the functionality used to manipulate the environment of
the calling class. The engine-class is the role that provides all of the data
validation functionality, please see [Validation::Class::Engine](http://search.cpan.org/perldoc?Validation::Class::Engine) for more
information on specific methods, and attributes.

## before

    before foo => sub { ... };

See ["before method(s) => sub { ... }" in Class::Method::Modifiers](http://search.cpan.org/perldoc?Class::Method::Modifiers#before method(s) => sub { ... }) for full
documentation.

## around

    around foo => sub { ... };

See ["around method(s) => sub { ... }" in Class::Method::Modifiers](http://search.cpan.org/perldoc?Class::Method::Modifiers#around method(s) => sub { ... }) for full
documentation.

## after

    after foo => sub { ... };

See ["after method(s) => sub { ... }" in Class::Method::Modifiers](http://search.cpan.org/perldoc?Class::Method::Modifiers#after method(s) => sub { ... }) for full
documentation.

# AUTHOR

Al Newkirk <awncorp@cpan.org>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2011 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.