Symfony
a SensioLabs product
DOWNLOAD NOW

Table of Contents

Creative Commons License
This work is licensed under a
Creative Commons
Attribution-Share Alike 3.0
Unported License.

Master Symfony2 fundamentals

Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).
trainings.sensiolabs.com

Symfony hosting done right

ServerGrove, outstanding support at the right price for your Symfony hosting needs.
servergrove.com

Discover the SensioLabs Support

Access to the SensioLabs Competency Center for an exclusive and tailor-made support on Symfony
sensiolabs.com
Home » Documentation » Reference Documents » Validation Constraints Reference » Collection
2.3 version

Collection

Collection

This constraint is used when the underlying data is a collection (i.e. an array or an object that implements Traversable and ArrayAccess), but you'd like to validate different keys of that collection in different ways. For example, you might validate the email key using the Email constraint and the inventory key of the collection with the Range constraint.

This constraint can also make sure that certain collection keys are present and that extra keys are not present.

Applies to property or method
Options
Class Collection
Validator CollectionValidator

Basic Usage

The Collection constraint allows you to validate the different keys of a collection individually. Take the following example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// src/Acme/BlogBundle/Entity/Author.php
namespace Acme\BlogBundle\Entity;

class Author
{
    protected $profileData = array(
        'personal_email',
        'short_bio',
    );

    public function setProfileData($key, $value)
    {
        $this->profileData[$key] = $value;
    }
}

To validate that the personal_email element of the profileData array property is a valid email address and that the short_bio element is not blank but is no longer than 100 characters in length, you would do the following:

  • YAML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    # src/Acme/BlogBundle/Resources/config/validation.yml
Acme\BlogBundle\Entity\Author:
    properties:
        profileData:
            - Collection:
                fields:
                    personal_email: Email
                    short_bio:
                        - NotBlank
                        - Length:
                            max:   100
                            maxMessage: Your short bio is too long!
                allowMissingFields: true
  • Annotations
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
    // src/Acme/BlogBundle/Entity/Author.php
namespace Acme\BlogBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    /**
     * @Assert\Collection(
     *     fields = {
     *         "personal_email" = @Assert\Email,
     *         "short_bio" = {
     *             @Assert\NotBlank(),
     *             @Assert\Length(
     *                 max = 100,
     *                 maxMessage = "Your bio is too long!"
     *             )
     *         }
     *     },
     *     allowMissingFields = true
     * )
     */
     protected $profileData = array(
         'personal_email',
         'short_bio',
     );
}
  • XML
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
    <!-- src/Acme/BlogBundle/Resources/config/validation.xml -->
<class name="Acme\BlogBundle\Entity\Author">
    <property name="profileData">
        <constraint name="Collection">
            <option name="fields">
                <value key="personal_email">
                    <constraint name="Email" />
                </value>
                <value key="short_bio">
                    <constraint name="NotBlank" />
                    <constraint name="Length">
                        <option name="max">100</option>
                        <option name="maxMessage">Your bio is too long!</option>
                    </constraint>
                </value>
            </option>
            <option name="allowMissingFields">true</option>
        </constraint>
    </property>
</class>
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    // src/Acme/BlogBundle/Entity/Author.php
namespace Acme\BlogBundle\Entity;

use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    private $options = array();

    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('profileData', new Assert\Collection(array(
            'fields' => array(
                'personal_email' => new Assert\Email(),
                'lastName' => array(
                    new Assert\NotBlank(),
                    new Assert\Length(array("max" => 100)),
                ),
            ),
            'allowMissingFields' => true,
        )));
    }
}

Presence and Absence of Fields

By default, this constraint validates more than simply whether or not the individual fields in the collection pass their assigned constraints. In fact, if any keys of a collection are missing or if there are any unrecognized keys in the collection, validation errors will be thrown.

If you would like to allow for keys to be absent from the collection or if you would like "extra" keys to be allowed in the collection, you can modify the allowMissingFields and allowExtraFields options respectively. In the above example, the allowMissingFields option was set to true, meaning that if either of the personal_email or short_bio elements were missing from the $personalData property, no validation error would occur.

New in version 2.1: The Required and Optional constraints are new to Symfony 2.1.

Required and Optional Field Constraints

Constraints for fields within a collection can be wrapped in the Required or Optional constraint to control whether they should always be applied (Required) or only applied when the field is present (Optional).

For instance, if you want to require that the personal_email field of the profileData array is not blank and is a valid email but the alternate_email field is optional but must be a valid email if supplied, you can do the following:

  • Annotations
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
    // src/Acme/BlogBundle/Entity/Author.php
namespace Acme\BlogBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    /**
     * @Assert\Collection(
     *     fields={
     *         "personal_email"  = @Assert\Collection\Required({@Assert\NotBlank, @Assert\Email}),
     *         "alternate_email" = @Assert\Collection\Optional({@Assert\Email}),
     *     }
     * )
     */
     protected $profileData = array(
         'personal_email',
     );
}
  • PHP
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
    // src/Acme/BlogBundle/Entity/Author.php
namespace Acme\BlogBundle\Entity;

use Symfony\Component\Validator\Mapping\ClassMetadata;
use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    protected $profileData = array('personal_email');

    public static function loadValidatorMetadata(ClassMetadata $metadata)
    {
        $metadata->addPropertyConstraint('profileData', new Assert\Collection(array(
            'fields' => array(
                'personal_email'  => new Assert\Collection\Required(array(new Assert\NotBlank(), new Assert\Email())),
                'alternate_email' => new Assert\Collection\Optional(array(new Assert\Email())),
            ),
        )));
    }
}

Even without allowMissingFields set to true, you can now omit the alternate_email property completely from the profileData array, since it is Optional. However, if the the personal_email field does not exist in the array, the NotBlank constraint will still be applied (since it is wrapped in Required) and you will receive a constraint violation.

Options

fields

type: array [default option]

This option is required, and is an associative array defining all of the keys in the collection and, for each key, exactly which validator(s) should be executed against that element of the collection.

allowExtraFields

type: Boolean default: false

If this option is set to false and the underlying collection contains one or more elements that are not included in the fields option, a validation error will be returned. If set to true, extra fields are ok.

extraFieldsMessage

type: Boolean default: The fields {{ fields }} were not expected

The message shown if allowExtraFields is false and an extra field is detected.

allowMissingFields

type: Boolean default: false

If this option is set to false and one or more fields from the fields option are not present in the underlying collection, a validation error will be returned. If set to true, it's ok if some fields in the fields_ option are not present in the underlying collection.

missingFieldsMessage

type: Boolean default: The fields {{ fields }} are missing

The message shown if allowMissingFields is false and one or more fields are missing from the underlying collection.

« Choice | Count »

NEWS FROM THE BLOG

Visit Symfony's blog

IN THE NEWS

Announcing the next Symfony Live Conference 2013 in Portland

UPCOMING TRAINING SESSIONS

View all sessions

sf - Symfony is a trademark of Fabien Potencier. All rights reserved.

What is Symfony?

Get Started

Learn Symfony

Marketplace

Community

Services

Blog

About