Skip to content

Commit ff15da6

Browse files
Bernhard Schussekfabpot
Bernhard Schussek
authored and
fabpot
committed
Added Validator documentation for the PHP metadata loader
1 parent 067407f commit ff15da6

File tree

8 files changed

+234
-19
lines changed

8 files changed

+234
-19
lines changed

‎guides/validator/constraints.rst

+52-4
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ of a class ``Author`` to have at least 3 characters.
7979
</property>
8080
</class>
8181
82-
.. code-block:: php
82+
.. code-block:: php-annotations
8383
8484
// Application/HelloBundle/Author.php
8585
class Author
@@ -94,7 +94,28 @@ of a class ``Author`` to have at least 3 characters.
9494
* @validation:NotBlank()
9595
* @validation:MinLength(3)
9696
*/
97+
private $lastName;
98+
}
99+
100+
.. code-block:: php
101+
102+
// Application/HelloBundle/Author.php
103+
use Symfony\Components\Validator\Constraints\NotBlank;
104+
use Symfony\Components\Validator\Constraints\MinLength;
105+
106+
class Author
107+
{
97108
private $firstName;
109+
110+
private $lastName;
111+
112+
public static function loadMetadata(ClassMetadata $metadata)
113+
{
114+
$metadata->addPropertyConstraint('firstName', new NotBlank());
115+
$metadata->addPropertyConstraint('firstName', new MinLength(3));
116+
$metadata->addPropertyConstraint('lastName', new NotBlank());
117+
$metadata->addPropertyConstraint('lastName', new MinLength(3));
118+
}
98119
}
99120
100121
Getters
@@ -133,7 +154,7 @@ generated token is correct:
133154
</getter>
134155
</class>
135156
136-
.. code-block:: php
157+
.. code-block:: php-annotations
137158
138159
// Application/HelloBundle/Author.php
139160
class Author
@@ -147,6 +168,27 @@ generated token is correct:
147168
}
148169
}
149170
171+
.. code-block:: php
172+
173+
// Application/HelloBundle/Author.php
174+
use Symfony\Components\Validator\Constraints\AssertTrue;
175+
176+
class Author
177+
{
178+
179+
public static function loadMetadata(ClassMetadata $metadata)
180+
{
181+
$metadata->addGetterConstraint('tokenValid', new AssertTrue(array(
182+
'message' => 'The token is invalid',
183+
)));
184+
}
185+
186+
public function isTokenValid()
187+
{
188+
// return true or false
189+
}
190+
}
191+
150192
.. note::
151193

152194
The keen-eyed among you will have noticed that the prefix of the getter
@@ -161,7 +203,9 @@ You can create a custom constraint by extending the base constraint class,
161203
:class:`Symfony\\Component\\Validator\\Constraint`. Options for your
162204
constraint are represented by public properties on the constraint class. For
163205
example, the ``Url`` constraint includes ``message`` and ``protocols``
164-
properties::
206+
properties:
207+
208+
.. code-block:: php
165209
166210
namespace Symfony\Component\Validator\Constraints;
167211
@@ -174,7 +218,9 @@ properties::
174218
As you can see, a constraint class is fairly minimal. The actual validation is
175219
performed by a another "constraint validator" class. Which constraint
176220
validator is specified by the constraint's ``validatedBy()`` method, which
177-
includes some simple default logic::
221+
includes some simple default logic:
222+
223+
.. code-block:: php
178224
179225
// in the base Symfony\Component\Validator\Constraint class
180226
public function validatedBy()
@@ -217,6 +263,8 @@ tag and an ``alias`` attribute:
217263
Your constraint class may now use this alias to reference the appropriate
218264
validator::
219265

266+
.. code-block:: php
267+
220268
public function validatedBy()
221269
{
222270
return 'alias_name';

‎guides/validator/constraints/AssertTrue.rst

+23-3
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,9 @@ Then you can constrain this method with ``AssertTrue``.
5656
</getter>
5757
</class>
5858
59-
.. code-block:: php
59+
.. code-block:: php-annotations
6060
6161
// Application/HelloBundle/Author.php
62-
namespace Application\HelloBundle;
63-
6462
class Author
6563
{
6664
protected $token;
@@ -74,6 +72,28 @@ Then you can constrain this method with ``AssertTrue``.
7472
}
7573
}
7674
75+
.. code-block:: php
76+
77+
// Application/HelloBundle/Author.php
78+
use Symfony\Components\Validator\Constraints\AssertTrue;
79+
80+
class Author
81+
{
82+
protected $token;
83+
84+
public static function loadMetadata(ClassMetadata $metadata)
85+
{
86+
$metadata->addGetterConstraint('tokenValid', new AssertTrue(array(
87+
'message' => 'The token is invalid',
88+
)));
89+
}
90+
91+
public function isTokenValid()
92+
{
93+
return $this->token == $this->generateToken();
94+
}
95+
}
96+
7797
If the validation of this method fails, you will see a message similar to
7898
this:
7999

‎guides/validator/constraints/Choice.rst

+18-3
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ constraint definition as array.
5151
</property>
5252
</class>
5353
54-
.. code-block:: php
54+
.. code-block:: php-annotations
5555
5656
// Application/HelloBundle/Author.php
5757
class Author
@@ -62,6 +62,21 @@ constraint definition as array.
6262
protected $gender;
6363
}
6464
65+
.. code-block:: php
66+
67+
// Application/HelloBundle/Author.php
68+
use Symfony\Components\Validator\Constraints\Choice;
69+
70+
class Author
71+
{
72+
protected $gender;
73+
74+
public static function loadMetadata(ClassMetadata $metadata)
75+
{
76+
$metadata->addPropertyConstraint('gender', new Choice(array('male', 'female')));
77+
}
78+
}
79+
6580
Example 2: Choices from a callback
6681
----------------------------------
6782

@@ -104,7 +119,7 @@ constraint.
104119
</property>
105120
</class>
106121
107-
.. code-block:: php
122+
.. code-block:: php-annotations
108123
109124
// Application/HelloBundle/Author.php
110125
class Author
@@ -142,7 +157,7 @@ you can pass the class name and the method as array.
142157
</property>
143158
</class>
144159
145-
.. code-block:: php
160+
.. code-block:: php-annotations
146161
147162
// Application/HelloBundle/Author.php
148163
class Author

‎guides/validator/constraints/Collection.rst

+27-3
Original file line numberDiff line numberDiff line change
@@ -71,23 +71,47 @@ may not exist in the array.
7171
</property>
7272
</class>
7373
74-
.. code-block:: php
74+
.. code-block:: php-annotations
7575
7676
// Application/HelloBundle/Author.php
7777
class Author
7878
{
7979
/**
8080
* @validation:Collection(
8181
* fields = {
82-
* "firstName" = @validation:NotNull,
83-
* "lastName" = { @validation:NotBlank, @validation:MinLength(4) }
82+
* "firstName" = @validation:NotNull(),
83+
* "lastName" = { @validation:NotBlank(), @validation:MinLength(4) }
8484
* },
8585
* allowMissingFields = true
8686
* )
8787
*/
8888
private $options = array();
8989
}
9090
91+
.. code-block:: php
92+
93+
// Application/HelloBundle/Author.php
94+
use Symfony\Components\Validator\Constraints\Collection;
95+
use Symfony\Components\Validator\Constraints\NotNull;
96+
use Symfony\Components\Validator\Constraints\NotBlank;
97+
use Symfony\Components\Validator\Constraints\MinLength;
98+
99+
class Author
100+
{
101+
private $options = array();
102+
103+
public static function loadMetadata(ClassMetadata $metadata)
104+
{
105+
$metadata->addPropertyConstraint('options', new Collection(array(
106+
'fields' => array(
107+
'firstName' => new NotNull(),
108+
'lastName' => array(new NotBlank(), new MinLength(4)),
109+
),
110+
'allowMissingFields' => true,
111+
)));
112+
}
113+
}
114+
91115
The following object would fail the validation.
92116

93117
.. code-block:: php

‎guides/validator/constraints/File.rst

+22-1
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ not exceed a maximum size of 128 kilobytes and is a PDF document.
4949
</property>
5050
</class>
5151
52-
.. code-block:: php
52+
.. code-block:: php-annotations
5353
5454
// Application/HelloBundle/Author.php
5555
class Author
@@ -63,6 +63,27 @@ not exceed a maximum size of 128 kilobytes and is a PDF document.
6363
private $filename;
6464
}
6565
66+
.. code-block:: php
67+
68+
// Application/HelloBundle/Author.php
69+
use Symfony\Components\Validator\Constraints\File;
70+
71+
class Author
72+
{
73+
private $filename;
74+
75+
public static function loadMetadata(ClassMetadata $metadata)
76+
{
77+
$metadata->addPropertyConstraint('filename', new File(array(
78+
'maxSize' => '128k',
79+
'mimeTypes' => array(
80+
'application/pdf',
81+
'application/x-pdf',
82+
),
83+
)));
84+
}
85+
}
86+
6687
When you validate the object with a file that doesn't satisfy one of these
6788
constraints, a proper error message is returned by the validator:
6889

‎guides/validator/constraints/Valid.rst

+73-3
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ their properties. Furthermore, ``Author`` stores an ``Address`` instance in the
8686
</property>
8787
</class>
8888
89-
.. code-block:: php
89+
.. code-block:: php-annotations
9090
9191
// Application/HelloBundle/Address.php
9292
class Author
@@ -118,6 +118,44 @@ their properties. Furthermore, ``Author`` stores an ``Address`` instance in the
118118
protected $lastName;
119119
}
120120
121+
.. code-block:: php
122+
123+
// Application/HelloBundle/Address.php
124+
use Symfony\Components\Validator\Constraints\NotBlank;
125+
use Symfony\Components\Validator\Constraints\MaxLength;
126+
127+
class Author
128+
{
129+
protected $street;
130+
131+
protected $zipCode;
132+
133+
public static function loadMetadata(ClassMetadata $metadata)
134+
{
135+
$metadata->addPropertyConstraint('street', new NotBlank());
136+
$metadata->addPropertyConstraint('zipCode', new NotBlank());
137+
$metadata->addPropertyConstraint('zipCode', new MaxLength(5));
138+
}
139+
}
140+
141+
// Application/HelloBundle/Author.php
142+
use Symfony\Components\Validator\Constraints\NotBlank;
143+
use Symfony\Components\Validator\Constraints\MinLength;
144+
145+
class Author
146+
{
147+
protected $firstName;
148+
149+
protected $lastName;
150+
151+
public static function loadMetadata(ClassMetadata $metadata)
152+
{
153+
$metadata->addPropertyConstraint('firstName', new NotBlank());
154+
$metadata->addPropertyConstraint('firstName', new MinLength(4));
155+
$metadata->addPropertyConstraint('lastName', new NotBlank());
156+
}
157+
}
158+
121159
With this mapping it is possible to successfully validate an author with an
122160
invalid address. To prevent that, we add the ``Valid`` constraint to the
123161
``$address`` property.
@@ -141,7 +179,7 @@ invalid address. To prevent that, we add the ``Valid`` constraint to the
141179
</property>
142180
</class>
143181
144-
.. code-block:: php
182+
.. code-block:: php-annotations
145183
146184
// Application/HelloBundle/Author.php
147185
class Author
@@ -152,6 +190,21 @@ invalid address. To prevent that, we add the ``Valid`` constraint to the
152190
protected $address;
153191
}
154192
193+
.. code-block:: php
194+
195+
// Application/HelloBundle/Author.php
196+
use Symfony\Components\Validator\Constraints\Valid;
197+
198+
class Author
199+
{
200+
protected $address;
201+
202+
public static function loadMetadata(ClassMetadata $metadata)
203+
{
204+
$metadata->addPropertyConstraint('address', new Valid());
205+
}
206+
}
207+
155208
We can even go one step further and validate the class of the related object
156209
to be ``Address`` or one of its subclasses.
157210

@@ -174,7 +227,7 @@ to be ``Address`` or one of its subclasses.
174227
</property>
175228
</class>
176229
177-
.. code-block:: php
230+
.. code-block:: php-annotations
178231
179232
// Application/HelloBundle/Author.php
180233
class Author
@@ -184,3 +237,20 @@ to be ``Address`` or one of its subclasses.
184237
*/
185238
protected $address;
186239
}
240+
241+
.. code-block:: php
242+
243+
// Application/HelloBundle/Author.php
244+
use Symfony\Components\Validator\Constraints\Valid;
245+
246+
class Author
247+
{
248+
protected $address;
249+
250+
public static function loadMetadata(ClassMetadata $metadata)
251+
{
252+
$metadata->addPropertyConstraint('address', new Valid(array(
253+
'class' => 'Application\HelloBundle\Address',
254+
)));
255+
}
256+
}

0 commit comments

Comments
 (0)