1Validation::Class::ProtUosteyrpeC(o3n)tributed Perl DocuVmaelnitdaattiioonn::Class::Prototype(3)
2
6 Validation::Class::Prototype - Data Validation Engine for
7 Validation::Class Classes
8
10 version 7.900057
11
13 Validation::Class::Prototype is the validation engine used by proxy via
14 Validation::Class whose methods are aliases to the methods defined
15 here. Please see Validation::Class::Simple for a quick introduction on
16 how to get started.
17
19 attributes
20 The attributes attribute provides access to simple attributes
21 registered on the the calling class. This attribute is a
22 Validation::Class::Mapping object containing hashref objects and CANNOT
23 be overridden.
24 builders
26 The builders attribute provides access to coderefs registered to hook
27 into the instantiation process of the calling class. This attribute is
28 a Validation::Class::Listing object containing coderef objects and
29 CANNOT be overridden.
30 configuration
32 The configuration attribute provides the default configuration profile.
33 This attribute is a Validation::Class::Configuration object and CANNOT
34 be overridden.
35 directives
37 The directives attribute provides access to defined directive objects.
38 This attribute is a Validation::Class::Mapping object containing
39 hashrefs and CANNOT be overridden.
40 documents
42 The documents attribute provides access to defined document models.
43 This attribute is a Validation::Class::Mapping object and CANNOT be
44 overridden.
45 errors
47 The errors attribute provides access to class-level error messages.
48 This attribute is a Validation::Class::Errors object, may contain error
49 messages and CANNOT be overridden.
50 events
52 The events attribute provides access to validation events and the
53 directives that subscribe to them. This attribute is a
54 Validation::Class::Mapping object and CANNOT be overridden.
55 fields
57 The fields attribute provides access to defined fields objects. This
58 attribute is a Validation::Class::Fields object containing
59 Validation::Class::Field objects and CANNOT be overridden.
60 filtering
62 The filtering attribute (by default set to 'pre') controls when
63 incoming data is filtered. Setting this attribute to 'post' will defer
64 filtering until after validation occurs which allows any errors
65 messages to report errors based on the unaltered data. Alternatively,
66 setting the filtering attribute to 'off' will bypass all filtering
67 unless explicitly defined at the field-level.
68 filters
70 The filters attribute provides access to defined filters objects. This
71 attribute is a Validation::Class::Mapping object containing code
72 references and CANNOT be overridden.
73 ignore_failure
75 The ignore_failure boolean determines whether your application will
76 live or die upon failing to validate a self-validating method defined
77 using the method keyword. This is on (1) by default, method validation
78 failures will set errors and can be determined by checking the error
79 stack using one of the error message methods. If turned off, the
80 application will die and confess on failure.
81 ignore_intervention
83 The ignore_intervention boolean determines whether validation will
84 short-circuit if required fields are not present. This is off (0) by
85 default; The logic behind this decision is that, for example, in the
86 case of a required field, if the field was not submitted but was
87 required, there is no need to perform additional validation. This is a
88 type-of short-circuiting which reduces validation overhead. If you
89 would like to emit all applicable validation errors you can enable this
90 option.
91 ignore_unknown
93 The ignore_unknown boolean determines whether your application will
94 live or die upon encountering unregistered field directives during
95 validation. This is off (0) by default, attempts to validate unknown
96 fields WILL cause the program to die.
97 messages
99 The messages attribute provides access to class-level error message
100 overrides. This attribute is a Validation::Class::Mapping object
101 containing scalar values.
102 methods
104 The methods attribute provides access to self-validating code
105 references. This attribute is a Validation::Class::Mapping object
106 containing code references.
107 mixins
109 The mixins attribute provides access to field templates. This attribute
110 is a Validation::Class::Mapping object and CANNOT be overridden.
111 The package attribute contains the namespace of the instance object
113 currently using this module.
114 params
116 The params attribute provides access to input parameters. This
117 attribute is a Validation::Class::Mapping object and CANNOT be
118 overridden.
119 profiles
121 The profiles attribute provides access to validation profile. This
122 attribute is a Validation::Class::Mapping object containing hash
123 references and CANNOT be overridden.
124 queued
126 The queued attribute returns an arrayref of field names for validation
127 and CANNOT be overridden. It represents a list of field names stored to
128 be used in validation later. If the queued attribute contains a list,
129 you can omit arguments to the validate method.
130 report_failure
132 The report_failure boolean determines whether your application will
133 report self-validating method failures as class-level errors. This is
134 off (0) by default, if turned on, an error messages will be generated
135 and set at the class-level specifying the method which failed in
136 addition to the existing messages.
137 report_unknown
139 The report_unknown boolean determines whether your application will
140 report unregistered fields as class-level errors upon encountering
141 unregistered field directives during validation. This is off (0) by
142 default, attempts to validate unknown fields will NOT be registered as
143 class-level variables.
144 settings
146 The settings attribute provides access to settings specific to the
147 associated class, not to be confused with settings which exist in the
148 prototype's configuration. This attribute is a
149 Validation::Class::Mapping object and CANNOT be overridden.
150 validated
152 The validated attribute simply denotes whether the validation routine
153 has been executed since the last normalization process (which occurs at
154 instantiation and before validation). It's values will either be 0 (not
155 validated), 1 (validated with errors), or 2 (validated without errors).
156 You can simply check this attribute for truth when you need to know if
157 validation has occurred.
158
160 apply_filters
161 The apply_filters method can be used to run the currently defined
162 parameters through the filters defined in their matching fields.
163 $self = $self->apply_filters;
165 # apply filters to fields where filtering is set to 'post' filtering
167 $self = $self->apply_filters('post');
168 class
170 This method instantiated and returns the validation class specified ,
171 existing parameters and configuration options are passed to the
172 constructor of the validation class (including the stash object). You
173 can prevent/override arguments from being copied to the new class
174 object by supplying the them as arguments to this method.
175 The class method is also quite handy in that it will detect parameters
177 that are prefixed with the name of the class being fetched, and
178 automatically create aliases on the matching rules (if any) to allow
179 validation to occur seamlessly.
180 package Class;
182 use Validation::Class;
184 load classes => 1; # load child classes e.g. Class::*
186 package main;
188 my $input = Class->new(params => $params);
190 my $child1 = $input->class('Child'); # loads Class::Child;
192 my $child2 = $input->class('StepChild'); # loads Class::StepChild;
193 my $child3 = $input->class('child'); # loads Class::Child;
195 my $child4 = $input->class('step_child'); # loads Class::StepChild;
196 # intelligently detecting and mapping parameters to child class
198 my $params = {
200 'my.name' => 'Guy Friday',
202 'child.name' => 'Guy Friday Jr.'
203 };
205 $input->class('child'); # child field *name* mapped to param *child.name*
207 # without copying params from class
209 my $child = $input->class('child', params => {});
211 1;
213 clear_queue
215 The clear_queue method resets the queue container, see the queue method
216 for more information on queuing fields to be validated. The clear_queue
217 method has yet another useful behavior in that it can assign the values
218 of the queued parameters to the list it is passed, where the values are
219 assigned in the same order queued.
220 my $self = Class->new(params => $params);
222 $self->queue(qw(name +email));
224 # ... additional logic
226 $self->queue(qw(+login +password));
228 if ($self->validate) {
230 $self->clear_queue(my($name, $email));
232 print "Name is $name and email is $email";
234 }
236 clone_field
238 The clone_field method is used to create new fields (rules) from
239 existing fields on-the-fly. This is useful when you have a variable
240 number of parameters being validated that can share existing validation
241 rules. Please note that cloning a field does not include copying and/or
242 processing of any mixins on the original field to the cloned field, if
243 desired, this must be done manually.
244 package Class;
246 use Validation::Class;
248 field 'phone' => {
250 label => 'Your Phone',
251 required => 1
252 };
253 package main;
255 my $self = Class->new(params => $params);
257 # clone phone rule at run-time to validate dynamically created parameters
259 $self->clone_field('phone', 'phone2', { label => 'Phone A', required => 0 });
260 $self->clone_field('phone', 'phone3', { label => 'Phone B', required => 0 });
261 $self->clone_field('phone', 'phone4', { label => 'Phone C', required => 0 });
262 $self->validate(qw/phone phone2 phone3 phone4/);
264 1;
266 does
268 The does method is used to determine whether the current prototype is
269 composed using the role specified. Return true if so, false if not.
270 package Class;
272 use Validation::Class;
274 set role => 'Class::Root';
276 package main;
278 my $self = Class->new(params => $params);
280 return 1 if $self->proto->does('Class::Root');
282 error_count
284 The error_count method returns the total number of errors set at both
285 the class and field level.
286 my $count = $self->error_count;
288 error_fields
290 The error_fields method returns a hashref containing the names of
291 fields which failed validation and an arrayref of error messages.
292 unless ($self->validate) {
294 my $failed = $self->error_fields;
296 }
298 my $suspects = $self->error_fields('field2', 'field3');
300 errors_to_string
302 The errors_to_string method stringifies the all error objects on both
303 the class and fields using the specified delimiter (defaulting to
304 comma-space (", ")).
305 return $self->errors_to_string("\n");
307 return $self->errors_to_string(undef, sub{ ucfirst lc shift });
308 unless ($self->validate) {
310 return $self->errors_to_string;
312 }
314 get_errors
316 The get_errors method returns a list of combined class-and-field-level
317 errors.
318 # returns all errors
320 my @errors = $self->get_errors;
321 # filter errors by fields whose name starts with critical
323 my @critical = $self->get_errors(qr/^critical/i);
324 # return errors for field_a and field_b specifically
326 my @specific_field_errors = $self->get_errors('field_a', 'field_b');
327 get_fields
329 The get_fields method returns the list of Validation::Class::Field
330 objects for specific fields and returns an empty list if no arguments
331 are passed. If a field does not match the name specified it will return
332 undefined.
333 my ($a, $b) = $self->get_fields('field_a', 'field_b');
335 get_hash
337 The get_hash method returns a hashref consisting of all fields with
338 their absolute values (i.e. default value or matching parameter value).
339 If a field does not have an absolute value its value will be undefined.
340 my $hash = $self->get_hash;
342 get_params
344 The get_params method returns the values of the parameters specified
345 (as a list, in the order specified). This method will return a list of
346 key/value pairs if no parameter names are passed.
347 if ($self->validate) {
349 my ($name) = $self->get_params('name');
351 my ($name, $email, $login, $password) =
353 $self->get_params(qw/name email login password/);
354 # you should note that if the params don't exist they will return
356 # undef meaning you should check that it is defined before doing any
357 # comparison checking as doing so would generate an error, e.g.
358 if (defined $name) {
360 if ($name eq '') {
362 print 'name parameter was passed but was empty';
363 }
364 }
366 else {
368 print 'name parameter was never submitted';
369 }
370 }
372 # alternatively ...
374 my $params = $self->get_params; # return hashref of parameters
376 print $params->{name};
378 get_values
380 The get_values method returns the absolute value for a given field.
381 This method executes specific logic which returns the value a field has
382 based on a set of internal conditions. This method always returns a
383 list, field names that do not exist are returned as undefined.
384 my ($value) = $self->get_values('field_name');
386 # equivalent to
388 my $param = $self->params->get('field_name');
390 my $field = $self->fields->get('field_name');
391 my $value;
392 if ($field->{readonly}) {
394 $value = $field->{default} || undef;
395 }
396 else {
397 $value = $field->{value} || $param;
398 }
399 is_valid
401 The is_valid method returns a boolean value which is true if the last
402 validation attempt was successful, and false if it was not (which is
403 determined by looking for errors at the class and field levels).
404 return "OK" if $self->is_valid;
406 normalize
408 The normalize method executes a set of routines that conditions the
409 environment filtering any parameters present whose matching field has
410 its filtering directive set to 'pre'. This method is executed
411 automatically at instantiation and again just before each validation
412 event.
413 $self->normalize;
415 param
417 The param method gets/sets a single parameter by name. This method
418 returns the value assigned or undefined if the parameter does not
419 exist.
420 my $value = $self->param('name');
422 $self->param($name => $value);
424 plugin
426 The plugin method returns an instantiated plugin object which is passed
427 the current prototype object. Note: This functionality is somewhat
428 experimental.
429 package Class;
431 use Validation::Class;
433 package main;
435 my $input = Class->new(params => $params);
437 my $formatter = $input->plugin('telephone_format');
439 # ... returns a Validation::Class::Plugin::TelephoneFormat object
440 queue
442 The queue method is a convenience method used specifically to append
443 the queued attribute allowing you to *queue* fields to be validated.
444 This method also allows you to set fields that must always be
445 validated.
446 $self->queue(qw/name login/);
448 $self->queue(qw/email email2/) if $input->param('change_email');
449 $self->queue(qw/login login2/) if $input->param('change_login');
450 reset
452 The reset method clears all errors, fields and queued field names, both
453 at the class and individual field levels.
454 $self->reset();
456 reset_errors
458 The reset_errors method clears all errors, both at the class and
459 individual field levels. This method is called automatically every time
460 the validate() method is triggered.
461 $self->reset_errors();
463 reset_fields
465 The reset_fields method set special default directives and clears all
466 errors and field values, both at the class and individual field levels.
467 This method is executed automatically at instantiation.
468 $self->reset_fields();
470 reset_params
472 The reset_params method is responsible for completely removing any
473 existing parameters and adding those specified. This method returns the
474 class object. This method takes a list of key/value pairs or a single
475 hashref.
476 $self->reset_params($new_params);
478 set_errors
480 The set_errors method pushes its arguments (error messages) onto the
481 class-level error stack and returns a count of class-level errors.
482 my $count = $self->set_errors('...', '...');
484 set_fields
486 The set_fields method is responsible setting/overriding registered
487 fields. This method returns the class object. This method takes a list
488 of key/value pairs or a single hashref whose key should be a valid
489 field name and whose value should be a hashref that is a valid field
490 configuration object.
491 $self->set_fields($name => $config); # accepts hashref also
493 set_params
495 The set_params method is responsible for setting/replacing parameters.
496 This method returns the class object. This method takes a list of
497 key/value pairs or a single hashref whose keys should match field names
498 and whose value should be a scalar or arrayref of scalars.
499 $self->set_params($name => $value); # accepts a hashref also
501 set_value
503 The set_value method assigns a value to the specified field's parameter
504 unless the field is readonly. This method returns the class object.
505 $self->set_values($name => $value);
507 stash
509 The stash method provides a container for context/instance specific
510 information. The stash is particularly useful when custom validation
511 routines require insight into context/instance specific operations.
512 package MyApp::Person;
514 use Validation::Class;
516 field 'email' => {
518 validation => sub {
520 my ($self) = @_;
522 my $db = $self->stash('database');
524 return 0 unless $db;
526 return $db->find(...) ? 0 : 1 ; # email exists
527 }
529 };
531 package main;
533 # store the database object for use in email validation
535 $self->stash(database => $database_object);
536 validate
538 The validate method (or has_valid, or validates) returns true/false
539 depending on whether all specified fields passed validation checks.
540 Please consider, if this method is called without any parameters, the
541 list of fields to be validated will be assumed/deduced, making the
542 execution strategy conditional, which may not be what you want.
543 use MyApp::Person;
545 my $input = MyApp::Person->new(params => $params);
547 # validate specific fields
549 unless ($input->validate('login','password')){
550 return $input->errors_to_string;
551 }
552 # validate fields based on a regex pattern
554 unless ($input->validate(qr/^setting(\d+)?/)){
555 return $input->errors_to_string;
556 }
557 # validate existing parameters
559 # however, if no parameters exist, ...
560 # validate all fields, which will return true unless a field exists
561 # with a required directive
562 unless ($input->validate){
563 return $input->errors_to_string;
564 }
565 # validate all fields period, obviously
567 unless ($input->validate($input->fields->keys)){
568 return $input->errors_to_string;
569 }
570 # implicitly validate parameters which don't explicitly match a field
572 my $parameter_map = {
573 user => 'login',
574 pass => 'password'
575 };
576 unless ($input->validate($parameter_map)){
577 return $input->errors_to_string;
578 }
579 Another cool trick the validate() method can perform is the ability to
581 temporarily alter whether a field is required or not during validation.
582 This functionality is often referred to as the *toggle* function.
583 This method is important when you define a field as required or non and
585 want to change that per validation. This is done by calling the
586 validate() method with a list of fields to be validated and prefixing
587 the target fields with a plus or minus respectively as follows:
588 use MyApp::Person;
590 my $input = MyApp::Person->new(params => $params);
592 # validate specific fields, force name, email and phone to be required
594 # regardless of the field directives ... and force the age, sex
595 # and birthday to be optional
596 my @spec = qw(+name +email +phone -age -sex -birthday);
598 unless ($input->validate(@spec)){
600 return $input->errors_to_string;
601 }
602 validate_document
604 The validate_document method (or document_validates) is used to
605 validate the specified hierarchical data against the specified document
606 declaration. This is extremely valuable for validating serialized
607 messages passed between machines. This method requires two arguments,
608 the name of the document declaration to be used, and the data to be
609 validated which should be submitted in the form of a hashref. The
610 following is an example of this technique:
611 my $boolean = $self->validate_document(foobar => $data);
613 Additionally, you may submit options in the form of a hashref to
615 further control the validation process. The following is an example of
616 this technique:
617 # the prune option removes non-matching parameters (nodes)
619 my $boolean = $self->validate_document(foobar => $data, { prune => 1 });
620 Additionally, to support the validation of ad-hoc specifications, you
622 may pass this method two hashrefs, the first being the document
623 notation schema, and the second being the hierarchical data you wish to
624 validate.
625 validate_method
627 The validate_method method (or method_validates) is used to determine
628 whether a self-validating method will be successful. It does so by
629 validating the methods input specification. This is useful in
630 circumstances where it is advantageous to know in-advance whether a
631 self-validating method will pass or fail. It effectively allows you to
632 use the methods input specification as a validation profile.
633 if ($self->validate_method('password_change')) {
635 # password_change will pass validation
637 if ($self->password_change) {
639 # password_change executed
640 }
641 }
643 validate_profile
645 The validate_profile method (or profile_validates) executes a stored
646 validation profile, it requires a profile name and can be passed
647 additional parameters which get forwarded into the profile routine in
648 the order received.
649 unless ($self->validate_profile('password_change')) {
651 print $self->errors_to_string;
653 }
655 unless ($self->validate_profile('email_change', $dbi_handle)) {
657 print $self->errors_to_string;
659 }
661
663 Al Newkirk <anewkirk@ana.io>
664
666 This software is copyright (c) 2011 by Al Newkirk.
667 This is free software; you can redistribute it and/or modify it under
669 the same terms as the Perl 5 programming language system itself.
670perl v5.34.0 2022-01-21 Validation::Class::Prototype(3)