Small doc typo fix in ResultSet.
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Validation.pm
1 package DBIx::Class::Validation;
2
3 use strict;
4 use warnings;
5
6 use base qw( DBIx::Class );
7 use English qw( -no_match_vars );
8
9 #local $^W = 0; # Silence C:D:I redefined sub errors.
10 # Switched to C::D::Accessor which doesn't do this. Hate hate hate hate.
11
12 our $VERSION = '0.01';
13
14 __PACKAGE__->mk_classdata( 'validation_module' => 'FormValidator::Simple' );
15 __PACKAGE__->mk_classdata( 'validation_profile'  );
16 __PACKAGE__->mk_classdata( 'validation_auto' => 1 );
17
18 sub validation_module {
19     my $class = shift;
20     my $module = shift;
21     
22     eval("use $module");
23     $class->throw_exception("Unable to load the validation module '$module' because $EVAL_ERROR") if ($EVAL_ERROR);
24     $class->throw_exception("The '$module' module does not support the check method") if (!$module->can('check'));
25     
26     $class->_validation_module_accessor( $module );
27 }
28
29 sub validation {
30     my $class = shift;
31     my %args = @_;
32     
33     $class->validation_module( $args{module} ) if (exists $args{module});
34     $class->validation_profile( $args{profile} ) if (exists $args{profile});
35     $class->validation_auto( $args{auto} ) if (exists $args{auto});
36 }
37
38 sub validate {
39     my $self = shift;
40     my %data = $self->get_columns();
41     my $module = $self->validation_module();
42     my $profile = $self->validation_profile();
43     my $result = $module->check( \%data => $profile );
44     return $result if ($result->success());
45     $self->throw_exception( $result );
46 }
47
48 sub insert {
49     my $self = shift;
50     $self->validate if ($self->validation_auto());
51     $self->next::method(@_);
52 }
53
54 sub update {
55     my $self = shift;
56     $self->validate if ($self->validation_auto());
57     $self->next::method(@_);
58 }
59
60 1;
61 __END__
62
63 =head1 NAME
64
65 DBIx::Class::Validation - Validate all data before submitting to your database.
66
67 =head1 SYNOPSIS
68
69 In your base DBIC package:
70
71   __PACKAGE__->load_components(qw/... Validation/);
72
73 And in your subclasses:
74
75   __PACKAGE__->validation(
76     module => 'FormValidator::Simple',
77     profile => { ... },
78     auto => 1,
79   );
80
81 And then somewhere else:
82
83   eval{ $obj->validate() };
84   if( my $results = $EVAL_ERROR ){
85     ...
86   }
87
88 =head1 METHODS
89
90 =head2 validation
91
92   __PACKAGE__->validation(
93     module => 'FormValidator::Simple',
94     profile => { ... },
95     auto => 1,
96   );
97
98 Calls validation_module(), validation_profile(), and validation_auto() if the corresponding 
99 argument is defined.
100
101 =head2 validation_module
102
103   __PACKAGE__->validation_module('Data::FormValidator');
104
105 Sets the validation module to use.  Any module that supports a check() method just like 
106 Data::FormValidator's can be used here, such as FormValidator::Simple.
107
108 Defaults to FormValidator::Simple.
109
110 =head2 validation_profile
111
112   __PACKAGE__->validation_profile(
113     { ... }
114   );
115
116 Sets the profile that will be passed to the validation module.
117
118 =head2 validation_auto
119
120   __PACKAGE__->validation_auto( 1 );
121
122 This flag, when enabled, causes any updates or inserts of the class 
123 to call validate() before actually executing.
124
125 =head2 validate
126
127   $obj->validate();
128
129 Validates all the data in the object against the pre-defined validation 
130 module and profile.  If there is a problem then a hard error will be 
131 thrown.  If you put the validation in an eval you can capture whatever 
132 the module's check() method returned.
133
134 =head2 auto_validate
135
136   __PACKAGE__->auto_validate( 0 );
137
138 Turns on and off auto-validation.  This feature makes all UPDATEs and 
139 INSERTs call the validate() method before doing anything.  The default 
140 is for auto-validation to be on.
141
142 Defaults to on.
143
144 =head1 AUTHOR
145
146 Aran C. Deltac <bluefeet@cpan.org>
147
148 =head1 LICENSE
149
150 You may distribute this code under the same terms as Perl itself.
151