Validations

Version 13 (Jacques Fuentes, 2010-08-01 01:02 PM)

1 1
h2. Validations
2 1
3 2 Kien La
*(#topic-list) "Is my model valid or not?":/projects/main/wiki/Validations#is-my-model-valid-or-not
4 2 Kien La
* "Commonalities":/projects/main/wiki/Validations#commonalities
5 2 Kien La
* "Available validations":/projects/main/wiki/Validations#available-validations
6 2 Kien La
* "validates_presence_of":/projects/main/wiki/Validations#validates_presence_of
7 2 Kien La
* "validates_size_of / validates_length_of":/projects/main/wiki/Validations#validates_size_of
8 2 Kien La
* "validates_(in|ex)clusion_of":/projects/main/wiki/Validations#validates_in_ex_clusion_of
9 2 Kien La
* "validates_format_of":/projects/main/wiki/Validations#validates_format_of
10 2 Kien La
* "validates_numericality_of":/projects/main/wiki/Validations#validates_numericality_of
11 2 Kien La
* "validates_uniqueness_of":/projects/main/wiki/Validations#validates_uniqueness_of
12 13 Jacques Fuentes
* "validate *custom:/projects/main/wiki/Validations#validate
13 2 Kien La
14 9 Ennio Wolsink
Validations offer a simple and powerful pattern to ensure the integrity of your data. By declaring validations on your models, you can be certain that only valid data will be saved to your database. No longer will you need to recall where you put that function which verifies the legitimacy of an e-mail and whether or not it will stop the record fom being saved. With validations, if your data is invalid, ActiveRecord will take care of marking the record as invalid instead of writing it to the database.
15 1
16 1
Validations will run for the following methods normally:
17 1
18 1
<pre class="code"><code class="php">
19 1
$book->save();
20 1
Book::create();
21 1
$book->update_attributes(array('title' => 'new title'));
22 1
</code></pre>
23 1
 
24 1
The following will skip validations and save the record:
25 1
26 1
<pre class="code"><code class="php">
27 1
$book->update_attribute();
28 1
$book->save(false); # anytime you pass false to save it will skip validations
29 1
</code></pre>
30 1
 
31 2 Kien La
h4(#is-my-model-valid-or-not). Is my model valid or not?
32 1
33 2 Kien La
You can determine whether or not your model is valid and can be saved to the database by issuing one of these methods: "Model::is_valid":/docs/ActiveRecord/Model#methodis_valid or "Model::is_invalid":/docs/ActiveRecord/Model#methodis_invalid. Both of these methods will run the validations for your model when invoked.
34 1
35 1
<pre class="code"><code class="php">
36 1
class Book extends ActiveRecord\Model
37 1
{
38 1
  static $validates_presence_of = array(
39 1
    array('title')
40 1
  );
41 1
}
42 1
43 1
# our book won't pass validates_presence_of
44 1
$book = new Book(array('title' => ''));
45 1
echo $book->is_valid(); # false
46 1
echo $book->is_invalid(); # true
47 1
</code></pre>
48 1
 
49 2 Kien La
If validation(s) fails for your model, then you can access the error message(s) like so. Let's assume that our validation was "validates_presence_of":/projects/main/wiki/Validations#validates_presence_of.
50 1
51 1
<pre class="code"><code class="php">
52 1
class Book extends ActiveRecord\Model
53 1
{
54 1
  static $validates_presence_of = array(
55 1
    array('title')
56 1
  );
57 1
}
58 1
 
59 1
$book = new Book(array('title' => ''));
60 1
$book->save();
61 1
$book->errors->is_invalid('title'); # => true
62 1
63 1
# if the attribute fails more than 1 validation,
64 1
# you would get an array of errors below
65 1
66 1
echo $book->errors->on('title'); # => can't be blank
67 1
</code></pre>
68 1
 
69 2 Kien La
Now let's assume our model failed two validations: "validates_presence_of":/projects/main/wiki/Validations#validates_presence_of and "validates_size_of":/projects/main/wiki/Validations#validates_size_of.
70 1
71 1
<pre class="code"><code class="php">
72 1
class Book extends ActiveRecord\Model
73 1
{
74 1
  static $validates_presence_of = array(
75 1
    array('title')
76 1
  );
77 1
 
78 1
  static $validates_size_of = array(
79 1
    array('title', 'within' => array(1,20))
80 1
  );
81 1
}
82 1
 
83 1
$book = new Book(array('title' => ''));
84 1
$book->save();
85 1
$book->errors->is_invalid('title'); # true
86 1
87 1
print_r($book->errors->on('title'));
88 1
 
89 1
# which would give us:
90 1
91 1
# Array
92 1
# (
93 1
#   [0] => can't be blank
94 1
#   [1] => is too short (minimum is 1 characters)
95 1
# )
96 1
</code></pre>
97 1
98 3 Kien La
h4(#commonalities). Commonalities
99 1
100 1
Validations are defined with a common set of options and some of them have specific options. As you've seen above, creating a validation is as simple as declaring a static validation variable in your model class as a multi-dimensional array (to validate multiple attributes). Each validation will require you to put the attribute name in the 0 index of the array. You can configure the error message by creating a message key with the message string as the value. You can also add an option which will only run the validation on either creation or update. By default, your validation will run everytime Model#save() is called.
101 1
102 1
<pre class="code"><code class="php">
103 1
class Book extends ActiveRecord\Model
104 1
{
105 1
  # 0 index is title, the attribute to test against
106 1
  # message is our custom error msg
107 1
  # only run this validation on creation - not when updating
108 1
  static $validates_presence_of = array(
109 1
    array('title', 'message' => 'cannot be blank on a book!', 'on' => 'create')
110 1
  );
111 1
}
112 1
</code></pre>
113 1
114 1
In some validations you may use: in, is within. In/within designate a range whereby you use an array with the first and second elements representing the beginning and end of the range respectively. Is represents equality.
115 1
116 10 Kien La
Common options available to all validators:
117 10 Kien La
118 10 Kien La
* *on:* run the validator during "save", "update" or "delete"
119 10 Kien La
* *allow_null:* allow null to satisfy the validation
120 10 Kien La
* *allow_blank:* allow a blank string to satisfy the validation
121 10 Kien La
* *message:* specify a custom error message
122 10 Kien La
123 3 Kien La
h4(#available-validations). Available validations
124 1
125 1
There are a number of pre-defined validation routines that you can declare on your model for specific attributes.
126 1
127 3 Kien La
* "validates_presence_of":/projects/main/wiki/Validations#validates_presence_of
128 3 Kien La
* "validates_size_of":/projects/main/wiki/Validations#validates_size_of
129 6 Kien La
* "validates_length_of":/projects/main/wiki/Validations#validates_size_of
130 3 Kien La
* "validates_(in|ex)clusion_of":/projects/main/wiki/Validations#validates_in_ex_clusion_of
131 3 Kien La
* "validates_format_of":/projects/main/wiki/Validations#validates_format_of
132 3 Kien La
* "validates_numericality_of":/projects/main/wiki/Validations#validates_numericality_of
133 3 Kien La
* "validates_uniqueness_of":/projects/main/wiki/Validations#validates_uniqueness_of
134 3 Kien La
* "validates_presence_of":/projects/main/wiki/Validations#validates_presence_of
135 12 Jacques Fuentes
* "validate *custom":/projects/main/wiki/Validations#validate
136 1
137 5 Kien La
h4(#validates_presence_of). validates_presence_of
138 4 Kien La
139 1
This is probably the simplest of all the validations. It will make sure that the value of the attribute is not null or a blank string. Available options:
140 1
141 1
* message: default: *can't be blank*
142 1
143 1
<pre class="code"><code class="php">
144 1
class Book extends ActiveRecord\Model
145 1
{
146 1
  static $validates_presence_of = array(
147 1
    array('title'),
148 1
    array('cover_blurb', 'message' => 'must be present and witty')
149 1
  );
150 1
}
151 1
 
152 1
$book = new Book(array('title' => ''));
153 1
$book->save();
154 1
 
155 1
echo $book->errors->on('cover_blurb'); # => must be present and witty
156 1
echo $book->errors->on('title'); # => can't be blank
157 1
</code></pre>
158 1
159 3 Kien La
h4(#validates_size_of). validates_size_of / validates_length_of
160 1
161 1
These two validations are one and the same. The purpose is to validate the length in characters of a given attribute. Available options:
162 1
163 3 Kien La
*is*: attribute should be *exactly* n characters long
164 8 Szymon W
*in/within*: attribute should be within an range array(n, m)
165 3 Kien La
*maximum/minimum*: attribute should not be above/below respectively
166 3 Kien La
167 1
Each of the options has a particular message and can be changed.
168 1
169 3 Kien La
* *is*: uses key 'wrong_length'
170 3 Kien La
* *in/within*: uses keys 'too_long' & 'too_short'
171 3 Kien La
* *maximum/minimum*: uses keys 'too_long' & 'too_short'
172 1
173 1
<pre class="code"><code class="php">
174 1
class Book extends ActiveRecord\Model
175 1
{
176 1
  static $validates_size_of = array(
177 1
    array('title', 'within' => array(1,5), 'too_short' => 'too short!'),
178 1
    array('cover_blurb', 'is' => 20),
179 1
    array('description', 'maximum' => 10, 'too_long' => 'should be short and sweet')
180 1
  );
181 1
}
182 1
 
183 1
$book = new Book;
184 1
$book->title = 'War and Peace';
185 1
$book->cover_blurb = 'not 20 chars';
186 1
$book->description = 'this description is longer than 10 chars';
187 1
$ret = $book->save();
188 1
 
189 1
# validations failed so we get a false return
190 1
if ($ret == false)
191 1
{
192 1
  # too short!
193 1
  echo $book->errors->on('title');
194 1
 
195 1
  # is the wrong length (should be 20 chars)
196 1
  echo $book->errors->on('cover_blurb');
197 1
 
198 1
  # should be short and sweet
199 1
  echo $book->errors->on('description');
200 1
}
201 1
</code></pre>
202 1
203 3 Kien La
h4(#validates_in_ex_clusion_of). validates_(in|ex)clusion_of
204 1
205 3 Kien La
As you can see from the names, these two are similar. In fact, this is just a white/black list approach to your validations. Inclusion is a whitelist that will require a value to be within a given set. Exclusion is the opposite: a blacklist that requires a value to *not* be within a given set. Available options:
206 1
207 3 Kien La
* *in/within*: attribute should/shouldn't be a value within an array
208 3 Kien La
* *message*: custom error message
209 1
210 1
<pre class="code"><code class="php">
211 1
class Car extends ActiveRecord\Model
212 1
{
213 1
  static $validates_inclusion_of = array(
214 7 Kien La
    array('fuel_type', 'in' => array('petroleum', 'hydrogen', 'electric')),
215 1
  );
216 1
}
217 1
 
218 1
# this will pass since it's in the above list
219 1
$car = new Car(array('fuel_type' => 'electric'));
220 1
$ret = $car->save();
221 1
echo $ret # => true
222 1
223 1
class User extends ActiveRecord\Model
224 1
{
225 1
  static $validates_exclusion_of = array(
226 1
    array('password', 'in' => array('god', 'sex', 'password', 'love', 'secret'),
227 1
      'message' => 'should not be one of the four most used passwords')
228 1
  );
229 1
}
230 1
 
231 1
$user = new User;
232 1
$user->password = 'god';
233 1
$user->save();
234 7 Kien La
235 7 Kien La
# => should not be one of the four most used passwords
236 7 Kien La
echo $user->errors->on('password');
237 1
</code></pre>
238 1
239 3 Kien La
h4(#validates_format_of). validates_format_of
240 1
241 3 Kien La
This validation uses "preg_match":http://www.php.net/preg_match to verify the format of an attribute. You can create a regular expression to test against. Available options:
242 1
243 3 Kien La
* *with*: regular expression
244 3 Kien La
* *message*: custom error message
245 1
246 1
<pre class="code"><code class="php">
247 1
class User extends ActiveRecord\Model
248 1
{
249 1
  static $validates_format_of = array(
250 1
    array('email', 'with' =>
251 1
      '/^[^0-9][A-z0-9_]+([.][A-z0-9_]+)*[@][A-z0-9_]+([.][A-z0-9_]+)*[.][A-z]{2,4}$/')
252 1
    array('password', 'with' =>
253 1
      '/^.*(?=.{8,})(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).*$/', 'message' => 'is too weak')
254 1
  );
255 1
}
256 1
 
257 1
$user = new User;
258 1
$user->email = 'not_a_real_email.com';
259 1
$user->password = 'notstrong';
260 1
$user->save();
261 1
 
262 1
echo $user->errors->on('email'); # => is invalid
263 1
echo $user->errors->on('password'); # => is too weak
264 1
</code></pre>
265 1
266 3 Kien La
h4(#validates_numericality_of). validates_numericality_of
267 1
268 1
As the name suggests, this gem tests whether or not a given attribute is a number, and whether or not it is of a certain value. Available options:
269 1
270 3 Kien La
* *only_integer*: value must be an integer (e.g. not a float), message: "is not a number"
271 3 Kien La
* *even, message*: "must be even"
272 3 Kien La
* *odd, message*: "must be odd"
273 3 Kien La
* *greater_than*: >, message: "must be greater than %d"
274 3 Kien La
* *greater_than_or_equal_to*: >=, message: "must be greater than or equal to %d"
275 3 Kien La
* *equal_to*: ==, message: "must be equal to %d"
276 3 Kien La
* *less_than*: <, message: "must be less than %d"
277 3 Kien La
* *less_than_or_equal_to*: <=, message: "must be less than or equal to %d"
278 1
279 1
<pre class="code"><code class="php">
280 1
class Order extends ActiveRecord\Model
281 1
{
282 1
  static $validates_numericality_of = array(
283 1
    array('price', 'greater_than' => 0.01),
284 1
    array('quantity', 'only_integer' => true),
285 1
    array('shipping', 'greater_than_or_equal_to' => 0),
286 1
    array('discount', 'less_than_or_equal_to' => 5, 'greater_than_or_equal_to' => 0)
287 1
  );
288 1
}
289 1
 
290 1
$order = new Order;
291 1
$order->price = 0;
292 1
$order->quantity = 1.25;
293 1
$order->shipping = 5;
294 1
$order->discount = 2;
295 1
$order->save();
296 1
 
297 1
echo $order->errors->on('price'); # => must be greater than 0.01
298 1
echo $order->errors->on('quantity'); # => is not a number
299 1
echo $order->errors->on('shipping'); # => null
300 1
echo $order->errors->on('discount'); # => null
301 1
</code></pre>
302 1
303 3 Kien La
h4(#validates_uniqueness_of). validates_uniqueness_of
304 1
305 1
Tests whether or not a given attribute already exists in the table or not.
306 1
307 3 Kien La
* *message*: custom error message
308 1
309 1
<pre class="code"><code class="php">
310 1
class User extends ActiveRecord\Model
311 1
{
312 1
  static $validates_uniqueness_of = array(
313 1
    array('name'),
314 1
    array(array('blah','bleh'), 'message' => 'blah and bleh!')
315 1
  );
316 1
}
317 1
 
318 1
User::create(array('name' => 'Tito'));
319 1
$user = User::create(array('name' => 'Tito'));
320 1
$user->is_valid(); # => false
321 11 Jacques Fuentes
</code></pre>
322 11 Jacques Fuentes
323 11 Jacques Fuentes
324 11 Jacques Fuentes
h4(#validate). validate (custom)
325 11 Jacques Fuentes
326 11 Jacques Fuentes
Generic method allows for custom business logic or advanced validation. You can add your own errors to errors object. This does not take any parameters. You place this logic in a *public* method  named *validate*.
327 11 Jacques Fuentes
328 11 Jacques Fuentes
<pre class="code"><code class="php">
329 11 Jacques Fuentes
class User extends ActiveRecord\Model
330 11 Jacques Fuentes
{
331 11 Jacques Fuentes
  public function validate() 
332 11 Jacques Fuentes
  {
333 11 Jacques Fuentes
    if ($this->first_name == $this->last_name)
334 11 Jacques Fuentes
    {
335 12 Jacques Fuentes
      $this->errors->add('first_name', "can't be the same as Last Name");
336 12 Jacques Fuentes
      $this->errors->add('last_name', "can't be the same as First Name");
337 11 Jacques Fuentes
    }
338 11 Jacques Fuentes
  }
339 11 Jacques Fuentes
}
340 11 Jacques Fuentes
 
341 11 Jacques Fuentes
$user = User::create(array('first_name' => 'Tito', 'last_name' => 'Tito'));
342 11 Jacques Fuentes
$user->is_valid(); # => false
343 11 Jacques Fuentes
echo $user->errors->on('first_name'); # => can't be the same as Last Name
344 1
</code></pre>