Skip to content

Commit 6f0c697

Browse files
weaverryanweaverryan
committed
Merge pull request #2840 from lmammino/improved-image-validator
[WCM] Updated documentation for PR symfony/symfony#849...
2 parents d695cad + 1891edd commit 6f0c697

File tree

1 file changed

+175
-7
lines changed

1 file changed

+175
-7
lines changed

‎reference/constraints/Image.rst

Lines changed: 175 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ automatically setup to work for image files specifically.
88
Additionally it has options so you can validate against the width and height
99
of the image.
1010

11+
.. versionadded:: 2.4
12+
As of Symfony 2.4 you can also validate against the image aspect ratio ( defined
13+
as ``width / height``) and selectively allow square, landscape and portrait
14+
image orientations.
15+
1116
See the :doc:`File</reference/constraints/File>` constraint for the bulk of
1217
the documentation on this constraint.
1318

@@ -19,12 +24,22 @@ the documentation on this constraint.
1924
| | - `maxWidth`_ |
2025
| | - `maxHeight`_ |
2126
| | - `minHeight`_ |
27+
| | - `maxRatio`_ |
28+
| | - `minRatio`_ |
29+
| | - `allowSquare`_ |
30+
| | - `allowLandscape`_ |
31+
| | - `allowPortrait`_ |
2232
| | - `mimeTypesMessage`_ |
2333
| | - `sizeNotDetectedMessage`_ |
2434
| | - `maxWidthMessage`_ |
2535
| | - `minWidthMessage`_ |
2636
| | - `maxHeightMessage`_ |
2737
| | - `minHeightMessage`_ |
38+
| | - `maxRatioMessage`_ |
39+
| | - `minRatioMessage`_ |
40+
| | - `allowSquareMessage`_ |
41+
| | - `allowLandscapeMessage`_ |
42+
| | - `allowPortraitMessage`_ |
2843
| | - See :doc:`File</reference/constraints/File>` for inherited options |
2944
+----------------+----------------------------------------------------------------------+
3045
| Class | :class:`Symfony\\Component\\Validator\\Constraints\\File` |
@@ -82,6 +97,8 @@ it is between a certain size, add the following:
8297
.. code-block:: php-annotations
8398
8499
// src/Acme/BlogBundle/Entity/Author.php
100+
namespace Acme\BlogBundle\Entity;
101+
85102
use Symfony\Component\Validator\Constraints as Assert;
86103
87104
class Author
@@ -120,18 +137,18 @@ it is between a certain size, add the following:
120137
.. code-block:: php
121138
122139
// src/Acme/BlogBundle/Entity/Author.php
123-
// ...
140+
namespace Acme/BlogBundle/Entity
124141
125142
use Symfony\Component\Validator\Mapping\ClassMetadata;
126-
use Symfony\Component\Validator\Constraints\Image;
143+
use Symfony\Component\Validator\Constraints as Assert;
127144
128145
class Author
129146
{
130147
// ...
131148
132149
public static function loadValidatorMetadata(ClassMetadata $metadata)
133150
{
134-
$metadata->addPropertyConstraint('headshot', new Image(array(
151+
$metadata->addPropertyConstraint('headshot', new Assert\Image(array(
135152
'minWidth' => 200,
136153
'maxWidth' => 400,
137154
'minHeight' => 200,
@@ -143,6 +160,76 @@ it is between a certain size, add the following:
143160
The ``headshot`` property is validated to guarantee that it is a real image
144161
and that it is between a certain width and height.
145162

163+
You may also want to guarantee the ``headshot`` image to be square. In this
164+
case you can disable portrait and landscape orientations as shown in the
165+
following code:
166+
167+
.. configuration-block::
168+
169+
.. code-block:: yaml
170+
171+
# src/Acme/BlogBundle/Resources/config/validation.yml
172+
Acme\BlogBundle\Entity\Author
173+
properties:
174+
headshot:
175+
- Image:
176+
allowLandscape: false
177+
allowPortrait: false
178+
179+
180+
.. code-block:: php-annotations
181+
182+
// src/Acme/BlogBundle/Entity/Author.php
183+
namespace Acme\BlogBundle\Entity;
184+
185+
use Symfony\Component\Validator\Constraints as Assert;
186+
187+
class Author
188+
{
189+
/**
190+
* @Assert\Image(
191+
* allowLandscape = false
192+
* allowPortrait = false
193+
* )
194+
*/
195+
protected $headshot;
196+
}
197+
198+
.. code-block:: xml
199+
200+
<!-- src/Acme/BlogBundle/Resources/config/validation.xml -->
201+
<class name="Acme\BlogBundle\Entity\Author">
202+
<property name="headshot">
203+
<constraint name="Image">
204+
<option name="allowLandscape">false</option>
205+
<option name="allowPortrait">false</option>
206+
</constraint>
207+
</property>
208+
</class>
209+
210+
.. code-block:: php
211+
212+
// src/Acme/BlogBundle/Entity/Author.php
213+
namespace Acme\BlogBundle\Entity;
214+
215+
use Symfony\Component\Validator\Mapping\ClassMetadata;
216+
use Symfony\Component\Validator\Constraints as Assert;
217+
218+
class Author
219+
{
220+
// ...
221+
222+
public static function loadValidatorMetadata(ClassMetadata $metadata)
223+
{
224+
$metadata->addPropertyConstraint('headshot', new Assert\Image(array(
225+
'allowLandscape' => false,
226+
'allowPortrait' => false,
227+
)));
228+
}
229+
}
230+
231+
You can mix all the constraint options to create powerful validation rules.
232+
146233
Options
147234
-------
148235

@@ -194,6 +281,43 @@ maxHeight
194281
If set, the height of the image file must be less than or equal to this
195282
value in pixels.
196283

284+
maxRatio
285+
~~~~~~~~
286+
287+
**type**: ``integer``
288+
289+
If set, the aspect ratio (``width / height``) of the image file must be less than or equal to this
290+
value.
291+
292+
minRatio
293+
~~~~~~~~
294+
295+
**type**: ``integer``
296+
297+
If set, the aspect ratio (``width / height``) of the image file must be greater than or equal to this
298+
value.
299+
300+
allowSquare
301+
~~~~~~~~~~~
302+
303+
**type**: ``Boolean`` **default**: ``true``
304+
305+
If this option is false, the image must not be square.
306+
307+
allowLandscape
308+
~~~~~~~~~~~~~~
309+
310+
**type**: ``Boolean`` **default**: ``true``
311+
312+
If this option is false, the image must not be landscape oriented.
313+
314+
allowPortrait
315+
~~~~~~~~~~~~~
316+
317+
**type**: ``Boolean`` **default**: ``true``
318+
319+
If this option is false, the image must not be portrait oriented.
320+
197321
sizeNotDetectedMessage
198322
~~~~~~~~~~~~~~~~~~~~~~
199323

@@ -206,29 +330,73 @@ options has been set.
206330
maxWidthMessage
207331
~~~~~~~~~~~~~~~
208332

209-
**type**: ``string`` **default**: ``The image width is too big ({{ width }}px). Allowed maximum width is {{ max_width }}px``
333+
**type**: ``string`` **default**: ``The image width is too big ({{ width }}px).
334+
Allowed maximum width is {{ max_width }}px``
210335

211336
The error message if the width of the image exceeds `maxWidth`_.
212337

213338
minWidthMessage
214339
~~~~~~~~~~~~~~~
215340

216-
**type**: ``string`` **default**: ``The image width is too small ({{ width }}px). Minimum width expected is {{ min_width }}px``
341+
**type**: ``string`` **default**: ``The image width is too small ({{ width }}px).
342+
Minimum width expected is {{ min_width }}px``
217343

218344
The error message if the width of the image is less than `minWidth`_.
219345

220346
maxHeightMessage
221347
~~~~~~~~~~~~~~~~
222348

223-
**type**: ``string`` **default**: ``The image height is too big ({{ height }}px). Allowed maximum height is {{ max_height }}px``
349+
**type**: ``string`` **default**: ``The image height is too big ({{ height }}px).
350+
Allowed maximum height is {{ max_height }}px``
224351

225352
The error message if the height of the image exceeds `maxHeight`_.
226353

227354
minHeightMessage
228355
~~~~~~~~~~~~~~~~
229356

230-
**type**: ``string`` **default**: ``The image height is too small ({{ height }}px). Minimum height expected is {{ min_height }}px``
357+
**type**: ``string`` **default**: ``The image height is too small ({{ height }}px).
358+
Minimum height expected is {{ min_height }}px``
231359

232360
The error message if the height of the image is less than `minHeight`_.
233361

362+
maxRatioMessage
363+
~~~~~~~~~~~~~~~
364+
365+
**type**: ``string`` **default**: ``The image ratio is too big ({{ ratio }}).
366+
Allowed maximum ratio is {{ max_ratio }}``
367+
368+
The error message if the aspect ratio of the image exceeds `maxRatio`_.
369+
370+
minRatioMessage
371+
~~~~~~~~~~~~~~~
372+
373+
**type**: ``string`` **default**: ``The image ratio is too small ({{ ratio }}).
374+
Minimum ratio expected is {{ min_ratio }}``
375+
376+
The error message if the aspect ratio of the image is less than `minRatio`_.
377+
378+
allowSquareMessage
379+
~~~~~~~~~~~~~~~~~~
380+
381+
**type**: ``string`` **default**: ``The image is square ({{ width }}x{{ height }}px).
382+
Square images are not allowed``
383+
384+
The error message if the image is square and you set `allowSquare`_ to ``false``.
385+
386+
allowLandscapeMessage
387+
~~~~~~~~~~~~~~~~~~~~~
388+
389+
**type**: ``string`` **default**: ``The image is landscape oriented ({{ width }}x{{ height }}px).
390+
Landscape oriented images are not allowed``
391+
392+
The error message if the image is landscape oriented and you set `allowLandscape`_ to ``false``.
393+
394+
allowPortraitMessage
395+
~~~~~~~~~~~~~~~~~~~~
396+
397+
**type**: ``string`` **default**: ``The image is portrait oriented ({{ width }}x{{ height }}px).
398+
Portrait oriented images are not allowed``
399+
400+
The error message if the image is portrait oriented and you set `allowPoirtrait`_ to ``false``.
401+
234402
.. _`IANA website`: http://www.iana.org/assignments/media-types/image/index.html

0 commit comments

Comments
 (0)