README.md
1[![Actions Status](https://github.com/tokuhirom/FormValidator-Lite/workflows/CI/badge.svg)](https://github.com/tokuhirom/FormValidator-Lite/actions)
2# NAME
3
4FormValidator::Lite - lightweight form validation library
5
6# SYNOPSIS
7
8 use FormValidator::Lite;
9
10 FormValidator::Lite->load_constraints(qw/Japanese/);
11
12 my $q = CGI->new();
13 my $validator = FormValidator::Lite->new($q);
14 $validator->load_function_message('en');
15 my $res = $validator->check(
16 name => [qw/NOT_NULL/],
17 name_kana => [qw/NOT_NULL KATAKANA/],
18 {mails => [qw/mail1 mail2/]} => ['DUPLICATION'],
19 );
20 if ( ..... return_true_if_error() ..... ) {
21 $validator->set_error('login_id' => 'DUPLICATION');
22 }
23 if ($validator->has_error) {
24 ...
25 }
26
27 # in your template
28 <ul>
29 ? for my $msg ($validator->get_error_messages) {
30 <li><?= $msg ?></li>
31 ? }
32 </ul>
33
34# DESCRIPTION
35
36FormValidator::Lite is a simple, fast implementation for form validation.
37
38IT'S IN BETA QUALITY. API MAY CHANGE IN THE FUTURE.
39
40# HOW TO WRITE YOUR OWN CONSTRAINTS
41
42Create your own constraint package as such :
43
44 package MyApp::Validator::Constraint;
45 use strict;
46 use warnings;
47 use FormValidator::Lite::Constraint;
48
49 rule 'IS_EVEN' => sub {
50 return $_ % 2 ? 0 : 1;
51 };
52
53 rule 'IS_GREATER_THAN' => sub {
54 my ($min) = @_;
55 return $_ >= $min;
56 }
57 alias 'IS_GREATER_THAN' => 'IS_BIGGER_THAN';
58
59 1;
60
61And in your controller :
62
63 use FormValidator::Lite qw("+MyApp::Validator::Constraint");
64
65 my $validator = FormValidator::Lite->new(...);
66 $validator->set_message_data(...);
67 $validator->check(
68 some_param => [ 'UINT', 'IS_EVEN', ['IS_GREATER_THAN' => 42] ],
69 );
70
71When defining a rule keep in mind that the value for the parameter comes from
72`$_` and the additional arguments defined in your validation
73specifications come from `@_`.
74
75# METHODS
76
77- my $validator = FormValidator::Lite->new($q);
78
79 Create a new instance.
80
81 The constructor takes a mandatory argument `$q` that is a query-like
82 object such as Apache::Request, CGI.pm, Plack::Request. The object MUST have
83 a `$q->param` method.
84
85 **EXPERIMENTAL: ** You can pass the hash value for `$q`.
86
87- $validator->query()
88- $validator->query($query)
89
90 Getter/Setter for the query attribute.
91
92- $validator->check(@specs\_array)
93
94 Validate the query against a set of specifications defined in the
95 `@specs_array` argument. In the most common case, the array is a sequence
96 of pairs : the first item is the parameter name and the second item is an
97 array reference with a list of constraint rules to apply on the query's value
98 for the parameter.
99
100 my $res = $validator->check(
101 name => [qw/NOT_NULL/],
102 name_kana => [qw/NOT_NULL KATAKANA/],
103 {mails => [qw/mail1 mail2/]} => ['DUPLICATION'],
104 );
105
106 In the above example _name_ is a parameter. _NOT\_NULL_, _KATAKANA_ and
107 _DUPLICATION_ are the names of the constraints.
108
109- $validator->is\_error($key)
110
111 Return true value if there is an error for the `$key` parameter.
112
113- $validator->is\_valid()
114
115 Return true value if `$validator` didn't detect any error.
116
117 This is the same as `!$validator->has_error()`.
118
119- $validator->has\_error()
120
121 Return true value if `$validator` detects error.
122
123 This is the same as `!$validator->is_valid()`.
124
125- $validator->set\_error($param, $rule\_name)
126
127 Manually set a new error for the parameter named `$param`. The rule's name
128 is `$rule_name`.
129
130- $validator->errors()
131
132 Return all the errors as a hash reference where the keys are the parameters
133 and the values are a hash reference with the failing constraints.
134
135 {
136 'foo' => { 'NOT_NULL' => 1, 'INT' => 1 },
137 'bar' => { 'EMAIL' => 1, },
138 }
139
140- $validator->load\_constraints($name)
141
142 $validator->load_constraints("DATE", "Email");
143
144 # or load your own constraints
145 $validator->load_constraints("+MyApp::FormValidator::Lite::Constraint");
146
147 You can also load the constraints during import :
148
149 use FormValidator::Lite qw/Date Email/;
150
151 Load constraint components named `"FormValidator::Lite::Constraint::${name}"`.
152
153 By default, You can use only constraints defined by [FormValidator::Lite::Constraint::Default](https://metacpan.org/pod/FormValidator%3A%3ALite%3A%3AConstraint%3A%3ADefault).
154
155- $validator->load\_function\_message($lang)
156
157 $validator->load_function_message('ja');
158
159 Load function message file.
160
161 Currently, [FormValidator::Lite::Messages::ja](https://metacpan.org/pod/FormValidator%3A%3ALite%3A%3AMessages%3A%3Aja) and
162 [FormValidator::Lite::Messages::en](https://metacpan.org/pod/FormValidator%3A%3ALite%3A%3AMessages%3A%3Aen) are available.
163
164- $validator->set\_param\_message($param => $message, ...)
165
166 $validator->set_param_message(
167 name => 'Your Name',
168 );
169
170 Add a message-friendly description for the parameter.
171
172- $validator->set\_message("$param.$func" => $message)
173
174 $v->set_message('zip.jzip' => 'Please input correct zip number.');
175
176 Set an error message for a given $param and $func pair.
177
178- $validator->set\_message\_data({ message => $msg, param => $param, function => $function })
179
180 $v->set_message_data(YAML::Load(<<'...'));
181 ---
182 message:
183 zip.jzip: Please input correct zip number.
184 param:
185 name: Your Name
186 function:
187 not_null: "[_1] is empty"
188 hiragana: "[_1] is not Hiragana"
189 ...
190
191 Set the error message map. In the 'function' and 'message' sections,
192 `[_1]` will be replaced by `build_message` with the description of
193 the failing parameter provided in the 'param' section.
194
195- `$validator->build_message($tmpl, @args)`
196
197 replace \[\_1\] in `$tmpl` by `@args`.
198
199 Setup error message map.
200
201- `$validator->set_message("$param.$func" => $message)`
202
203 $v->set_message('zip.jzip' => 'Please input correct zip number.');
204
205 Note that it will void any previous calls to `load_function_message`,
206 `set_message` or `set_param_message`.
207
208- my @errors = $validator->get\_error\_messages()
209- my $errors = $validator->get\_error\_messages()
210
211 Get all the error messages for the query. This method returns an array in list
212 context and an array reference otherwise.
213
214- my $msg = $validator->get\_error\_message($param => $func)
215
216 Generate the error message for parameter `$param` and function
217 `$func`.
218
219- my @msgs = $validator->get\_error\_messages\_from\_param($param)
220
221 Get all the error messages for the parameter `$param`.
222
223# WHY NOT FormValidator::Simple?
224
225Yes, I know. This module is very similar with FV::S.
226
227But, FormValidator::Simple is too heavy for me.
228FormValidator::Lite is fast!
229
230 Perl: 5.010000
231 FVS: 0.23
232 FVL: 0.02
233 Rate FormValidator::Simple FormValidator::Lite
234 FormValidator::Simple 353/s -- -75%
235 FormValidator::Lite 1429/s 304% --
236
237# AUTHOR
238
239Tokuhiro Matsuno <tokuhirom AAJKLFJEF@ gmail.com>
240
241# THANKS TO
242
243craftworks
244
245nekokak
246
247tomi-ru
248
249# SEE ALSO
250
251[FormValidator::Simple](https://metacpan.org/pod/FormValidator%3A%3ASimple), [Data::FormValidator](https://metacpan.org/pod/Data%3A%3AFormValidator), [HTML::FormFu](https://metacpan.org/pod/HTML%3A%3AFormFu)
252
253# LICENSE
254
255This library is free software; you can redistribute it and/or modify
256it under the same terms as Perl itself.
257