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.