VERSION
version 7.70OVERVIEW
This documentation will serves as a brief overview of the rationale and various usage scenarios for Validation::Class.INTRODUCTION
package MyApp::User;
use Validation::Class;
# package commands
set ...;
# a mixin template
mxn 'basic' => {
required => 1
};
# a validation rule
fld 'login' => {
label => 'User Login',
error => 'Login invalid.',
mixin => 'basic',
validation => sub {
my ($self, $field, $params) = @_;
return $field->{value} eq 'admin' ? 1 : 0;
}
};
# a validation rule
fld 'password' => {
label => 'User Password',
error => 'Password invalid.',
mixin => 'basic',
validation => sub {
my ($self, $field, $params) = @_;
return $field->{value} eq 'pass' ? 1 : 0;
}
};
# a validation profile
pro 'registration' => sub {
my ($self, @args) = @_;
return $self->validate(qw(+name +email -login +password))
};
# an auto-validating method
mth 'register' => {
input => 'registration',
using => sub {
my ($self, @args) = shift;
# ... do something
}
};
1;
SCREENCAST
The following screencast <http://youtu.be/YCPViiB5jv0> explains what Validation::Class is, why it was created, and what it has to offer.Data Modeling Fun
Validation::Class is designed to provide you with a self-validating data model. The DRY approach the library enforces ensures data integrity through consistency.This enables you to check incoming data once and ensure it meets a specific criteria then move on throughout various layers in the application stack with a level-of-certainty that the input is as it should be, ... sort've a set-it-and-forget-it approach.
Prior to Validation::Class version 7, the general idea was to have developers create a validation class in addition to an existing data/object model (which is twice the work), this was the reasoning behind having the framework ship with a Moose adapter (no longer available). Although the Moose adapter is no longer supported, Validation::Class provides your classes with a simple object system providing the tools necessary to combine your validation and model layers.
The Validation::Class object system provides automatic generation of attributes and accessors based on field names, and a new method for instantiating your classes. The method keyword creates self-validating routines (like method signatures) which allow you to focus on the handling of data instead of worrying if the data is as it should be.
Simple as it may seem, these features allow developers to easily create data models and objects with verifiable attributes and methods as well as built-in validation and error handling functionality while remaining fast and extensible due to its lean dependency chain.
Die On Your Own Terms
Validation::Class won't die on instantiation (or anywhere else for that matter) unless you tell it to. The ignore_failure flag when set to false will confess to method validation failures. The ignore_unknown flag when set to false will confess to an attempt to validate a parameter with no matching field definition.Although the sentiment may not be shared by all, error handling is one of those things I'd just like to be available without worrying too much about how its setup. Validation and error handling are built-in mechanisms you are encouraged to leverage. Validation::Class is extremely extendable for those that wish to roll-their-own-solution.
A Reasonably Realistic Example
The following is a reasonably realistic albeit lame example of Validation::Class usage scenarios:... in MyApp.pm (the glue)
package MyApp;
use Validation::Class;
set classes => [__PACKAGE__]; # load all sub-classes, MyApp::*
1;
... in MyApp/Person.pm (the role/base-class)
package MyApp::Person;
use Validation::Class;
mxn 'basic' => {
require => 1,
filters => ['trim', 'strip']
};
fld 'first_name' => {
mixin => 'basic'
};
fld 'last_name' => {
mixin => 'basic'
};
... in MyApp/User.pm (an app user)
package MyApp::User;
use Validation::Class;
set base => ['MyApp::Person'];
fld 'login' => {
mixin => 'basic'
};
fld 'password' => {
mixin => 'basic'
};
mth 'register' => {
input => ['first_name', 'last_name', 'login', 'password'],
using => sub {
my ($self) = @_;
# do something registrationy
}
}
... in myapp.pl (the script)
use MyApp;
# find some parameters, e.g.
my $params = {
'user.first_name' => '...',
'user.last_name' => '...',
'user.login' => '...',
'user.password' => '...'
};
# or
my $params = {
user => {
first_name => '...',
last_name => '...',
login => '...',
password => '...'
}
};
my $app = MyApp->new(params => $params);
my $user = $app->class('user');
unless ($user->register) {
print $user->errors_to_string # more error handling via V::C::Errors
}
# or
my $user = MyApp::User->new(first_name => '...', last_name => '...');
unless ($user->register) {
# $user->error_count
}
BUILDING CLASSES
package MyApp::User;
use Validation::Class;
# a validation rule template
mixin 'basic' => {
required => 1,
min_length => 1,
max_length => 255,
filters => ['lowercase', 'alphanumeric']
};
# a validation rule
field 'login' => {
mixin => 'basic',
label => 'user login',
error => 'login invalid',
validation => sub {
my ($self, $field, $params) = @_;
return $field->value eq 'admin' ? 1 : 0;
}
};
# a validation rule
field 'password' => {
mixin => 'basic',
label => 'user login',
error => 'login invalid',
validation => sub {
my ($self, $field, $params) = @_;
return $field->value eq 'pass' ? 1 : 0;
}
};
1;
Your validation class can be thought of as your data-model/input-firewall. The benefits this approach provides might require you to change your perspective on parameter handling and workflow. Typically when designing an application we tend to name parameters arbitrarily and validate the same data at various stages during a program's execution in various places in the application stack. This approach is inefficient and prone to bugs and security problems.
To get the most out of Validation::Class you should consider each parameter hitting your application (individually) as a transmission fitting a very specific criteria, yes, like a field in a data model.
Your validation rules will act as filters which will reject or accept and format the transmission for use within your application, yes, almost exactly like a firewall.
A validation class is defined as follows:
package MyApp::User;
use Validation::Class;
# a mixin template
mxn 'basic' => {
required => 1
};
# a validation rule
fld 'login' => {
label => 'User Login',
error => 'Login invalid.',
mixin => 'basic',
validation => sub {
my ($self, $field, $params) = @_;
return $field->value eq 'admin' ? 1 : 0;
}
};
# a validation rule
fld 'password' => {
label => 'User Password',
error => 'Password invalid.',
mixin => 'basic',
validation => sub {
my ($self, $field, $params) = @_;
return $field->value eq 'pass' ? 1 : 0;
}
};
# a validation profile
pro 'registration' => sub {
my ($self, @args) = @_;
return $self->validate(qw(+name +email -login +password))
};
# an auto-validating method
mth 'register' => {
input => [qw/+login +password/],
using => sub {
my ($self, @args) = shift;
# ... do something
}
};
1;
The fields defined will be used to validate the specified input parameters. You specify the input parameters at/after instantiation, parameters should take the form of a hashref of key/value pairs passed to the params attribute, or attribute/value pairs. Multi-level (nested) hashrefs are allowed and are inflated/deflated in accordance with the rules of Hash::Flatten. The following is an example on using your validate class to validate input in various scenarios:
# web app
package MyApp;
use MyApp::User;
use Misc::WebAppFramework;
get '/auth' => sub {
# get user input parameters
my $params = shift;
# initialize validation class and set input parameters
my $user = MyApp::User->new(params => $params);
unless ($user->validate('login', 'password')) {
# print errors to browser unless validation is successful
return $user->errors_to_string;
}
return 'you have authenticated';
};
Lazy validation? Have your validation class automatically find the appropriate fields to validate against (params must match field names). This is possible but not necessarily recommended as the execution and validation is dictated by the parameters submitted (which you may or may not have control over).
use MyApp::User;
my $user = MyApp::User->new(params => $params);
unless ($user->validate) {
return $input->errors_to_string;
}
You can define an alias to automatically map a parameter to a validation field whereby a field definition will have an alias attribute containing an arrayref of alternate names that can be matched against passed-in parameter names.
package MyApp::User;
field 'fu' => {
...,
alias => [
'foo',
'bar',
'baz',
'bax'
]
};
package main;
use MyApp::User;
my $user = MyApp::User->new(params => { foo => 1 });
unless ($user->validate('fu'){
return $user->errors_to_string;
}
# OK because foo is an alias on the fu field
Filtering Incoming Data
Validation::Class supports pre/post filtering but is configured to pre-filter incoming data. This means that based upon the filtering options supplied within the individual fields, filtering will happen before validation (technically at instantiation and again just before validation). As expected, this is configurable via the filtering attribute.A WORD OF CAUTION: Validation::Class is configured to pre-filter incoming data which boosts application security and is best used with passive filtering (e.g. converting character case - filtering which only alters the input in predictable ways), versus aggressive filtering (e.g. formatting a telephone number) which completely and permanently changes the incoming data ... so much so that if the validation still fails ... errors that are reported may not match the data that was submitted.
If you're sure you'd rather employ aggressive filtering, I suggest setting the filtering attribute to 'post' for post-filtering or setting it to null and applying the filters manually by calling the apply_filters() method.
Auto Serialization/Deserialization
Validation::Class supports automatic serialization and deserialization of parameters with complex data structures which means that you can set a parameter as an arrayref or hashref of nested data structures and validate against them, likewise you can set a parameters using parameter names which are serialized string representations of the keys within the complex structure you wish to set and validate against. The serialization rules are as documented in Hash::Flatten.The following is an example of that:
my $params = {
user => {
login => 'admin',
password => 'pass'
}
};
my $input = MyApp->new(params => $params);
# or
my $params = {
'user.login' => 'admin',
'user.password' => 'pass'
};
my $input = MyApp->new(params => $params);
# field definition using field('user.login', ...)
# and field('user.password', ...) will match against the parameters above
# after filtering, validation, etc ... return your params as a hashref if
# needed
my $params = $input->get_params_hash;
Separation of Concerns
For larger applications where a single validation class might become cluttered and inefficient, Validation::Class comes equipped to help you separate your validation rules into separate classes.The idea is that you'll end up with a main validation class (most likely empty) that will simply serve as your point of entry into your relative (child) classes. The following is an example of this:
package MyVal::User;
use Validation::Class;
field name => { ... };
field email => { ... };
field login => { ... };
field password => { ... };
package MyVal::Profile;
use Validation::Class;
field age => { ... };
field sex => { ... };
field birthday => { ... };
package MyVal;
use Validation::Class;
set classes => [__PACKAGE__];
package main;
my $input = MyVal->new(params => $params);
my $user = $input->class('user');
my $profile = $input->class('profile');
...
1;
BUILDING OBJECTS
package MyApp::Database;
use DBI;
use Validation::Class;
fld name => {
required => 1,
};
fld host => {
required => 1,
};
fld port => {
required => 1,
};
fld user => {
required => 1,
};
fld pass => {
# ...
};
obj _build_dbh => {
type => 'DBI',
init => 'connect', # defaults to new
args => sub {
my ($self) = @_;
my @conn_str_parts =
('dbi', 'mysql', $self->name, $self->host, $self->port);
return (
join(':', @conn_str_parts),
$self->user,
$self->pass
)
}
};
has dbh => sub { shift->_build_dbh }; # cache the _build_dbh object
sub connect {
my ($self) = @_;
my @parameters = ('name', 'host', 'port', 'user');
if ($self->validate(@parameters)) {
if ($self->dbh) {
my $db = $self->dbh;
# ... do something else with DBI
return 1;
}
$self->set_errors($DBI::errstr);
}
return 0;
}
package main;
my $database = MyApp::Database->new(
name => 'test',
host => 'localhost',
port => '3306',
user => 'root'
);
if ($database->connect) {
# ...
}
More documentation to come ...
BUILDING PLUGINS
When creating official Validation::Class plugins you should use the namespace Validation::Class::Plugin::YourPluginName. This will allow users of your plugin to simply pass YourPluginName to the "plugins" option of the load() method. Otherwise you will need to pass the fully-qualified plugin package name prefixed with a ``+'' symbol. The following is an example of including a plugin.
package MyApp::User;
use Validation::Class;
load plugins => [
'PluginName', # Validation::Class::Plugin::PluginName
'+MyApp::User::YourPluginName'
];
# a validation rule
field 'login' => {
label => 'User Login',
error => 'Login invalid.',
required => 1,
validation => sub {
my ($self, $field, $params) = @_;
return $field->{value} eq 'admin' ? 1 : 0;
}
};
# a validation rule
field 'password' => {
label => 'User Password',
error => 'Password invalid.',
required => 1,
validation => sub {
my ($self, $field, $params) = @_;
return $field->{value} eq 'pass' ? 1 : 0;
}
};
1;
Your plugin is loaded at runtime and can manipulate the calling class by declaring a new method. The following is an example of a fictitious plugin for formatting telephone numbers:
package Validation::Class::Plugin::USTelephone;
# hook into the instantiation process of the calling class at runtime
sub new {
my ($plugin, $caller) = @_;
# US Telephones
$caller->filters->{telephone_usa} = sub {
my $phone = shift;
$phone =~ s/\D//g;
my ($area, $prefix, $xchng) = $phone =~ m/1?(\d{3})(\d{3})(\d{4});
return "+1 ($area) $prefix-$xchng";
};
return bless {}, $plugin;
}
Once we create, test and deploy our plugin, we can use it in our code as follows:
package MyApp::User;
use Validation::Class;
load plugins => ['USTelephone'];
# a validation rule
field 'phone' => {
label => 'Telephone Number',
error => 'Phone number invalid.',
required => 1,
filters => ['telephone_usa'],
filtering => 'post', # phone is only formatted if validation passes
};
package main ;
# the phone param will become +1 (215) 555-1212
my $input = MyApp::User->new(phone => '2155551212');
# get direct access to the instantiated plugin
my $plugin = $input->plugin('us_telephone');
INTROSPECT AND EXTEND
Most users will never venture beyond the public API, but powerful abilities await the more adventureous developer and this section was written specifically for you. To assist you on along your journey, let me explain exactly what happens when you define and instantiate a validation class.Classes are defined using keywords (field, mixin, filter, etc) which register rule definitions on a cached class profile (of-sorts) associated with the class which is being constructed. On instantiation, the cached class profile is cloned then merged with any arguments provided to the constructor, this means that even in a persistent environment the original class profile is never altered.
To begin introspection, simply look into the attributes attached to the class prototype, e.g. fields, mixins, filters, etc., the following examples will give you an idea of how to use introspection to extend your application code using Validation::Class.
Please keep in mind that Validation::Class is likely to have most of the functionalty you would need to introspect your codebase. The following is an introspect design template that will work in most cases:
package MyApp::Introspect;
use Validation::Class;
set classes => ['MyApp']; # load MyApp and all MyApp::* child classes
sub per_class {
my ($self, $code) = @_;
$self->proto->relatives->each(sub {
my ($alias, $namespace) = @_;
# do something with each class
$code->($namespace);
});
}
sub per_field_per_class {
my ($self, $code) = @_;
$self->per_class(sub {
my $namespace = shift;
my $class = $namespace->new;
foreach my $field (sort $class->fields->keys) {
# do something with each field
$code->($class, $class->fields->{$field});
}
});
}
...
MISC TECHNIQUES
What follows is a miscellaneous list of tips and tricks that leverage Validation::Class to perform additional operations.Log All Validation Attempts
package MyApp::User;
use Validation::Class;
use Class::Method::Modifiers;
...
after validate => sub {
my ($self, @args) = @_;
# maybe using Log::Log4Perl to write log validation attempts
};
after validate_profile => sub {
my ($self, @args) = @_;
# maybe using Log::Log4Perl to write log validation attempts
};
More documentation to come ...
Client-Side Validation Library
In the context of a web-application, it is often best to perform the initial input validation on the client (web-browser) before submitting data to the server for further validation and processing. In the following code we will generate javascript objects that match our Validation::Class data models which we will then use with jQuery to validate form data, etc.... in bin/generate_jsapi
# usage: ./generate_jsapi > app.api.js
use MyApp::Introspect;
use JSON;
my $classes = {};
my $json = JSON->new->allow_blessed->convert_blessed->pretty([1]);
my $introspection = MyApp::Introspect->new;
$introspection->per_field_per_class(sub{
my ($class, $field) = @_;
my $namespace = ref $class;
# attributes we want in the js api
my $attributes = { map { $_ => $field->{$_} } qw(
name label error filters required length min_length max_length
) };
my $fieldspace = $classes->{$namespace}->{$field->{name}} = $attributes;
});
# generate the JS API
print "\n";
print "var MyApp = MyApp || {};\n\n";
while (my($namespace, $fields) = each(%{$classes})) {
$namespace =~ s/::/./;
my $objects = $json->encode($fields);
chomp $objects;
print "$namespace = $objects;\n\n";
}
The output of the following script should generate a file which looks similar to the following:
var MyApp = MyApp || {};
MyApp.Test = {
"email" : {
"name" : "email",
"filters" : [
"strip",
"trim"
],
"min_length" : 3,
"length" : null,
"required" : 1,
"error" : null,
"label" : null,
"max_length" : 255
},
"password" : {
"name" : "password",
"filters" : [
"strip",
"trim"
],
"min_length" : 5,
"length" : null,
"required" : 1,
"error" : null,
"label" : null,
"max_length" : 255
},
"name" : {
"name" : "name",
"filters" : [
"strip",
"trim"
],
"min_length" : 5,
"length" : null,
"required" : 1,
"error" : null,
"label" : null,
"max_length" : 255
},
"id" : {
"name" : "id",
"filters" : [
"strip",
"trim"
],
"min_length" : null,
"length" : null,
"required" : 0,
"error" : null,
"label" : null,
"max_length" : 11
},
"login" : {
"name" : "login",
"filters" : [
"strip",
"trim"
],
"min_length" : 5,
"length" : null,
"required" : 1,
"error" : null,
"label" : null,
"max_length" : 255
}
};
If its not obvious yet, we can easily use this generated javascript API with jQuery to validate forms, etc. The following are a few ideas on how we might do that.
... the form
<form action="/awesomeness" class="protected">
<input id="name" name="name" value="" model="test-name" />
</form>
... the javascript
// validate any form with a 'protected' class
$('form.protected').submit(function(){
// all form fields submitted
$(':input', this).each(function(){
var model = $(this).attr('model');
if (model) {
var cf = model.split("-");
var class = cf[0];
var field = cf[1];
// uppercase first
class = class.charAt(0).toUpperCase() + class.slice(1);
// check model against element, e.g.
if (! $(this).val() && MyApp[class][field].required) {
// ERROR, DANGER, KABOOM!!!
}
}
});
});
AUTHOR
Al Newkirk <[email protected]>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.