Skip to content

Commit e4a1f42

Browse files
Bernhard Schussekfabpot
Bernhard Schussek
authored and
fabpot
committed
Added a dedicated page for each constraint. Started to split the validation documentation into chapters
1 parent ceb95cd commit e4a1f42

23 files changed

+765
-117
lines changed

‎guides/en/Validator/Constraints.markdown

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Constraints
2+
===========
3+
4+
The Validator is designed to validate objects against different *constraints*.
5+
In real life, a constraint would be: "The cake must not be burned". In
6+
Symfony2, constraints are very similar: They are assertions that a specific
7+
condition is true.
8+
9+
Constraints can be put on properties of a class, on public getters and on the
10+
class itself. Property and getter constraints obviously can only be used to
11+
validate a single value. Class constraints, on the other hand, can validate
12+
the whole state of an object at once, with all its properties and methods.
13+
14+
>**NOTE**
15+
>As "getter" the validator accepts any method with the prefix "get" or "is."
16+
17+
Supported Constraints
18+
---------------------
19+
20+
The following constraints are natively available in Symfony2:
21+
22+
* [AssertFalse](Constraints/AssertFalse)
23+
* [AssertTrue](Constraints/AssertTrue)
24+
* [AssertType](Constraints/AssertType)
25+
* [Choice](Constraints/Choice)
26+
* [Collection](Constraints/Collection)
27+
* [Date](Constraints/Date)
28+
* [DateTime](Constraints/DateTime)
29+
* [Email](Constraints/Email)
30+
* [File](Constraints/File)
31+
* [Max](Constraints/Max)
32+
* [MaxLength](Constraints/MaxLength)
33+
* [Min](Constraints/Min)
34+
* [MinLength](Constraints/MinLength)
35+
* [NotBlank](Constraints/NotBlank)
36+
* [NotNull](Constraints/NotNull)
37+
* [Regex](Constraints/Regex)
38+
* [Time](Constraints/Time)
39+
* [Url](Constraints/Url)
40+
* [Valid](Constraints/Valid)
41+
42+
Constraint Options
43+
------------------
44+
45+
TODO
46+
47+
48+
49+
50+
51+

‎guides/en/Validator/Constraints/AssertFalse.markdown

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
AssertTrue
2+
==========
3+
4+
Validates that a value is `false`.
5+
6+
[yml]
7+
properties:
8+
deleted:
9+
- AssertFalse: ~
10+
11+
Options
12+
-------
13+
14+
* `message`: The error message if validation fails
15+
16+
17+
See [AssertFalse](AssertFalse).

‎guides/en/Validator/Constraints/AssertTrue.markdown

-2
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,6 @@ put the logic in a method which returns either `true` or `false`.
2424

2525
[php]
2626
// Application/HelloBundle/Author.php
27-
namespace Application\HelloBundle;
28-
2927
class Author
3028
{
3129
protected $token;

‎guides/en/Validator/Constraints/AssertType.markdown

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
AssertType
2+
==========
3+
4+
Validates that a value has a specific data type
5+
6+
[yml]
7+
properties:
8+
age:
9+
- AssertType: integer
10+
11+
Options
12+
-------
13+
14+
* `type` (**default**, required): A fully qualified class name or one of the
15+
PHP datatypes as determined by PHP's `is_` functions.
16+
17+
* [`array`](http://php.net/is_array)
18+
* [`bool`](http://php.net/is_bool)
19+
* [`callable`](http://php.net/is_callable)
20+
* [`float`](http://php.net/is_float)
21+
* [`double`](http://php.net/is_double)
22+
* [`int`](http://php.net/is_int)
23+
* [`integer`](http://php.net/is_integer)
24+
* [`long`](http://php.net/is_long)
25+
* [`null`](http://php.net/is_null)
26+
* [`numeric`](http://php.net/is_numeric)
27+
* [`object`](http://php.net/is_object)
28+
* [`real`](http://php.net/is_real)
29+
* [`resource`](http://php.net/is_resource)
30+
* [`scalar`](http://php.net/is_scalar)
31+
* [`string`](http://php.net/is_string)
32+
33+
* `message`: The error message in case the validation fails

‎guides/en/Validator/Constraints/Choice.markdown

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
Choice
2+
======
3+
4+
Validates that a value is one or more of a list of choices.
5+
6+
[yml]
7+
properties:
8+
gender:
9+
- Choice: [male, female]
10+
11+
Options
12+
-------
13+
14+
* `choices` (**default**, required): The available choices
15+
* `callback`: Can be used instead of `choices`. A static callback method
16+
returning the choices. If you pass a string, it is expected to be
17+
the name of a static method in the validated class.
18+
* `multiple`: Whether multiple choices are allowed. Default: `false`
19+
* `min`: The minimum amount of selected choices
20+
* `max`: The maximum amount of selected choices
21+
* `message`: The error message if validation fails
22+
* `minMessage`: The error message if `min` validation fails
23+
* `maxMessage`: The error message if `max` validation fails
24+
25+
Example 1: Choices as array (YAML)
26+
----------------------------------
27+
28+
If the choices are few and easy to determine, they can be passed to the
29+
constraint definition as array.
30+
31+
**Listing 1**
32+
33+
[yml]
34+
# Application/HelloBundle/Resources/config/validation.yml
35+
Application\HelloBundle\Author:
36+
properties:
37+
gender:
38+
- Choice: [male, female]
39+
40+
Example 2: Choices as array (XML)
41+
---------------------------------
42+
43+
The following snippet shows the mapping of Example 1 using XML.
44+
45+
**Listing 2**
46+
47+
[xml]
48+
<!-- Application/HelloBundle/Resources/config/validation.xml -->
49+
<class name="Application\HelloBundle\Author">
50+
<property name="gender">
51+
<constraint name="Choice">
52+
<value>male</value>
53+
<value>female</value>
54+
</constraint>
55+
</property>
56+
</class>
57+
58+
Example 3: Choices as array (Docblock Annotations)
59+
--------------------------------------------------
60+
61+
Of course, Example 1 can also be solved with annotations.
62+
63+
**Listing 3**
64+
65+
[php]
66+
// Application/HelloBundle/Author.php
67+
class Author
68+
{
69+
/**
70+
* @Validation({ @Choice({"male", "female"}) })
71+
*/
72+
protected $gender;
73+
}
74+
75+
Example 4: Choices from a callback (YAML)
76+
-----------------------------------------
77+
78+
When you also need the choices in other contexts (such as a drop-down box in
79+
a form), it is more flexible to bind them to your domain model using a static
80+
callback method.
81+
82+
**Listing 4**
83+
84+
[php]
85+
// Application/HelloBundle/Author.php
86+
class Author
87+
{
88+
public static function getGenders()
89+
{
90+
return array('male', 'female');
91+
}
92+
}
93+
94+
You can pass the name of this method to the `callback` option of the `Choice`
95+
constraint.
96+
97+
**Listing 5**
98+
99+
[yml]
100+
# Application/HelloBundle/Resources/config/validation.yml
101+
Application\HelloBundle\Author:
102+
properties:
103+
gender:
104+
- Choice: { callback: getGenders }
105+
106+
If the static callback is stored in a different class, for example `Util`,
107+
you can pass the class name and the method as array.
108+
109+
**Listing 6**
110+
111+
[yml]
112+
# Application/HelloBundle/Resources/config/validation.yml
113+
Application\HelloBundle\Author:
114+
properties:
115+
gender:
116+
- Choice: { callback: [Util, getGenders] }
117+
118+
Example 5: Choices from a callback (XML)
119+
----------------------------------------
120+
121+
The following listing shows how Listing 6 is written with XML.
122+
123+
**Listing 7**
124+
125+
[xml]
126+
<!-- Application/HelloBundle/Resources/config/validation.xml -->
127+
<class name="Application\HelloBundle\Author">
128+
<property name="gender">
129+
<constraint name="Choice">
130+
<option name="callback">
131+
<value>Util</value>
132+
<value>getGenders</value>
133+
</option>
134+
</constraint>
135+
</property>
136+
</class>
137+
138+
Example 6: Choices from a callback (Docblock Annotations)
139+
---------------------------------------------------------
140+
141+
Here you see how the mapping of Listing 6 is written with annotations.
142+
143+
**Listing 8**
144+
145+
[php]
146+
// Application/HelloBundle/Author.php
147+
class Author
148+
{
149+
/**
150+
* @Validation({ @Choice(callback = {"Util", "getGenders"}) })
151+
*/
152+
protected $gender;
153+
}

‎guides/en/Validator/Constraints/Collection.markdown

+7-4
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,11 @@ Options
2828
Example 1 (YAML):
2929
-----------------
3030

31+
Let's validate an array with two indexes `firstName` and `lastName`. The value
32+
of `firstName` must not be blank, while the value of `lastName` must not be
33+
blank with a minimum length of four characters. Furthermore, both keys
34+
may not exist in the array.
35+
3136
**Listing 1**
3237

3338
[yml]
@@ -38,9 +43,9 @@ Example 1 (YAML):
3843
- Collection:
3944
fields:
4045
firstName:
41-
- NotNull: ~
46+
- NotBlank: ~
4247
lastName:
43-
- NotNull: ~
48+
- NotBlank: ~
4449
- MinLength: 4
4550
allowMissingFields: true
4651
@@ -97,8 +102,6 @@ This example shows the mapping from Example 1 with Docblock Annotations.
97102

98103
[php]
99104
// Application/HelloBundle/Author.php
100-
namespace Application\HelloBundle;
101-
102105
class Author
103106
{
104107
/**

‎guides/en/Validator/Constraints/Date.markdown

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
Date
2+
====
3+
4+
Validates that a value is a valid date string with format "YYYY-MM-DD".
5+
6+
[yml]
7+
properties:
8+
birthday:
9+
- Date: ~
10+
11+
Options
12+
-------
13+
14+
* `message`: The error message if the validation fails

‎guides/en/Validator/Constraints/DateTime.markdown

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
DateTime
2+
========
3+
4+
Validates that a value is a valid datetime string with format "YYYY-MM-DD HH:MM:SS".
5+
6+
[yml]
7+
properties:
8+
createdAt:
9+
- DateTime: ~
10+
11+
Options
12+
-------
13+
14+
* `message`: The error message if the validation fails

‎guides/en/Validator/Constraints/Email.markdown

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Email
2+
=====
3+
4+
Validates that a value is a valid email address.
5+
6+
[yml]
7+
properties:
8+
email:
9+
- Email: ~
10+
11+
Options
12+
-------
13+
14+
* `checkMX`: Whether MX records should be checked for the domain. Default: `false`
15+
* `message`: The error message if the validation fails

0 commit comments

Comments
 (0)