NAME
Validation::Class - Low-Fat Full-Flavored Data Modeling and Validation
Framework
VERSION
version 5.95
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, 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.
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 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 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 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.
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 for more information on specific methods, and
attributes.
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 <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.