1Validation::Class::ProtUosteyrpeC(o3n)tributed Perl DocuVmaelnitdaattiioonn::Class::Prototype(3)
2
3
4

NAME

6       Validation::Class::Prototype - Data Validation Engine for
7       Validation::Class Classes
8

VERSION

10       version 7.900057
11

DESCRIPTION

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

ATTRIBUTES

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
25   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
31   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
36   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
41   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
46   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
51   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
56   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
61   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
69   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
74   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
82   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
92   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
98   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
103   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
108   mixins
109       The mixins attribute provides access to field templates. This attribute
110       is a Validation::Class::Mapping object and CANNOT be overridden.
111
112       The package attribute contains the namespace of the instance object
113       currently using this module.
114
115   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
120   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
125   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
131   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
138   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
145   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
151   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

METHODS

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
164           $self = $self->apply_filters;
165
166           # apply filters to fields where filtering is set to 'post' filtering
167           $self = $self->apply_filters('post');
168
169   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
176       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
181           package Class;
182
183           use Validation::Class;
184
185           load classes => 1; # load child classes e.g. Class::*
186
187           package main;
188
189           my $input = Class->new(params => $params);
190
191           my $child1  = $input->class('Child');      # loads Class::Child;
192           my $child2  = $input->class('StepChild');  # loads Class::StepChild;
193
194           my $child3  = $input->class('child');      # loads Class::Child;
195           my $child4  = $input->class('step_child'); # loads Class::StepChild;
196
197           # intelligently detecting and mapping parameters to child class
198
199           my $params = {
200
201               'my.name'    => 'Guy Friday',
202               'child.name' => 'Guy Friday Jr.'
203
204           };
205
206           $input->class('child'); # child field *name* mapped to param *child.name*
207
208           # without copying params from class
209
210           my $child = $input->class('child', params => {});
211
212           1;
213
214   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
221           my $self = Class->new(params => $params);
222
223           $self->queue(qw(name +email));
224
225           # ... additional logic
226
227           $self->queue(qw(+login +password));
228
229           if ($self->validate) {
230
231               $self->clear_queue(my($name, $email));
232
233               print "Name is $name and email is $email";
234
235           }
236
237   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
245           package Class;
246
247           use Validation::Class;
248
249           field 'phone' => {
250               label => 'Your Phone',
251               required => 1
252           };
253
254           package main;
255
256           my $self = Class->new(params => $params);
257
258           # 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
263           $self->validate(qw/phone phone2 phone3 phone4/);
264
265           1;
266
267   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
271           package Class;
272
273           use Validation::Class;
274
275           set role => 'Class::Root';
276
277           package main;
278
279           my $self = Class->new(params => $params);
280
281           return 1 if $self->proto->does('Class::Root');
282
283   error_count
284       The error_count method returns the total number of errors set at both
285       the class and field level.
286
287           my $count = $self->error_count;
288
289   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
293           unless ($self->validate) {
294
295               my $failed = $self->error_fields;
296
297           }
298
299           my $suspects = $self->error_fields('field2', 'field3');
300
301   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
306           return $self->errors_to_string("\n");
307           return $self->errors_to_string(undef, sub{ ucfirst lc shift });
308
309           unless ($self->validate) {
310
311               return $self->errors_to_string;
312
313           }
314
315   get_errors
316       The get_errors method returns a list of combined class-and-field-level
317       errors.
318
319           # returns all errors
320           my @errors = $self->get_errors;
321
322           # filter errors by fields whose name starts with critical
323           my @critical = $self->get_errors(qr/^critical/i);
324
325           # return errors for field_a and field_b specifically
326           my @specific_field_errors = $self->get_errors('field_a', 'field_b');
327
328   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
334           my ($a, $b) = $self->get_fields('field_a', 'field_b');
335
336   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
341           my $hash = $self->get_hash;
342
343   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
348           if ($self->validate) {
349
350               my ($name) = $self->get_params('name');
351
352               my ($name, $email, $login, $password) =
353                   $self->get_params(qw/name email login password/);
354
355               # 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
359               if (defined $name) {
360
361                   if ($name eq '') {
362                       print 'name parameter was passed but was empty';
363                   }
364
365               }
366
367               else {
368                   print 'name parameter was never submitted';
369               }
370
371           }
372
373           # alternatively ...
374
375           my $params = $self->get_params; # return hashref of parameters
376
377           print $params->{name};
378
379   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
385           my ($value) = $self->get_values('field_name');
386
387           # equivalent to
388
389           my $param = $self->params->get('field_name');
390           my $field = $self->fields->get('field_name');
391           my $value;
392
393           if ($field->{readonly}) {
394               $value = $field->{default} || undef;
395           }
396           else {
397               $value = $field->{value} || $param;
398           }
399
400   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
405           return "OK" if $self->is_valid;
406
407   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
414           $self->normalize;
415
416   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
421           my $value = $self->param('name');
422
423           $self->param($name => $value);
424
425   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
430           package Class;
431
432           use Validation::Class;
433
434           package main;
435
436           my $input = Class->new(params => $params);
437
438           my $formatter = $input->plugin('telephone_format');
439           # ... returns a Validation::Class::Plugin::TelephoneFormat object
440
441   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
447           $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
451   reset
452       The reset method clears all errors, fields and queued field names, both
453       at the class and individual field levels.
454
455           $self->reset();
456
457   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
462           $self->reset_errors();
463
464   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
469           $self->reset_fields();
470
471   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
477           $self->reset_params($new_params);
478
479   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
483           my $count = $self->set_errors('...', '...');
484
485   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
492           $self->set_fields($name => $config); # accepts hashref also
493
494   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
500           $self->set_params($name => $value); # accepts a hashref also
501
502   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
506           $self->set_values($name => $value);
507
508   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
513           package MyApp::Person;
514
515           use Validation::Class;
516
517           field 'email' => {
518
519               validation => sub {
520
521                   my ($self) = @_;
522
523                   my $db = $self->stash('database');
524
525                   return 0 unless $db;
526                   return $db->find(...) ? 0 : 1 ; # email exists
527
528               }
529
530           };
531
532           package main;
533
534           #  store the database object for use in email validation
535           $self->stash(database => $database_object);
536
537   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
544           use MyApp::Person;
545
546           my $input = MyApp::Person->new(params => $params);
547
548           # validate specific fields
549           unless ($input->validate('login','password')){
550               return $input->errors_to_string;
551           }
552
553           # validate fields based on a regex pattern
554           unless ($input->validate(qr/^setting(\d+)?/)){
555               return $input->errors_to_string;
556           }
557
558           # 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
566           # validate all fields period, obviously
567           unless ($input->validate($input->fields->keys)){
568               return $input->errors_to_string;
569           }
570
571           # 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
580       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
584       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
589           use MyApp::Person;
590
591           my $input = MyApp::Person->new(params => $params);
592
593           # 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
597           my @spec = qw(+name +email +phone -age -sex -birthday);
598
599           unless ($input->validate(@spec)){
600               return $input->errors_to_string;
601           }
602
603   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
612           my $boolean = $self->validate_document(foobar => $data);
613
614       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
618           # the prune option removes non-matching parameters (nodes)
619           my $boolean = $self->validate_document(foobar => $data, { prune => 1 });
620
621       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
626   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
634           if ($self->validate_method('password_change')) {
635
636               # password_change will pass validation
637
638               if ($self->password_change) {
639                   # password_change executed
640               }
641
642           }
643
644   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
650           unless ($self->validate_profile('password_change')) {
651
652               print $self->errors_to_string;
653
654           }
655
656           unless ($self->validate_profile('email_change', $dbi_handle)) {
657
658               print $self->errors_to_string;
659
660           }
661

AUTHOR

663       Al Newkirk <anewkirk@ana.io>
664
666       This software is copyright (c) 2011 by Al Newkirk.
667
668       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.
670
671
672
673perl v5.32.1                      2021-01-27   Validation::Class::Prototype(3)
Impressum