Answer¶

This is a great question because it touches on a few interesting and related concepts: custom validation, assigning errors, and the best practices around all of this.

Let’s follow along with your example. Suppose we have an Event entity that looks like this (with some extras, like getter and setter methods):

// src/KnpU/QADayBundle/Entity/Event.php
namespace KnpU\QADayBundle\Entity;

use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity(repositoryClass="KnpU\QADayBundle\Entity\EventRepository")
 */
class Event
{
    /**
     * @ORM\Column(name="id", type="integer")
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    private $id;

    /** @ORM\Column(name="name", type="string", length=255) */
    private $name;

    /** @ORM\Column(name="startDate", type="datetime") */
    private $startDate;

    /** @ORM\Column(name="endDate", type="datetime") */
    private $endDate;

    // ...
}

I also have a really basic route, controller and form setup which allows the user to create a new Event (check out the code download to see this). Ok, let’s get to work!

// src/KnpU/QADayBundle/Entity/Event.php
// ...
use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\ExecutionContextInterface;

/**
 * @Assert\Callback(methods={"checkCustomValidation"})
 */
class Event
{
    // ...

    public function checkCustomValidation(ExecutionContextInterface $context)
    {
        $context->addViolationAt('name', 'Pick a cooler name!');
    }
}

// src/KnpU/QADayBundle/Controller/EventController.php

use Symfony\Component\Validator\Constraints as Assert;
use Symfony\Component\Validator\ExecutionContextInterface;
use KnpU\QADayBundle\Entity\Event;
// ...

public function newAction(Request $request)
{
    $form = $this->createFormBuilder(null, array(
        'data_class' => 'KnpU\QADayBundle\Entity\Event',
        'constraints' => array(
            new Assert\Callback(array($this, 'validateEventDates'))
        )
    ))
        ->add('name', 'text')
        ->add('startDate', 'datetime')
        ->add('endDate', 'datetime')
        ->getForm()
    ;

    // ...
}

// src/KnpU/QADayBundle/Entity/EventController.php
public function validateEventDates(Event $event, ExecutionContextInterface $context)
{
    $context->addViolationAt('startDate', 'There is already an event during this time!');
}

// src/KnpU/QADayBundle/Entity/EventRepository.php
namespace KnpU\QADayBundle\Entity;

use Doctrine\ORM\EntityRepository;

class EventRepository extends EntityRepository
{
    public function findOverlappingWithRange(\DateTime $startDate, \DateTime $endDate)
    {
        $qb = $this->createQueryBuilder('e');

        return $qb->andWhere('e.startDate < :endDate AND e.endDate > :startDate')
            ->setParameter('startDate', $startDate)
            ->setParameter('endDate', $endDate)
            ->getQuery()
            ->execute()
        ;
    }
}

// src/KnpU/QADayBundle/Controller/EventController.php
public function validateEventDates(Event $event, ExecutionContextInterface $context)
{
    $conflicts = $this->getDoctrine()
        ->getRepository('QADayBundle:Event')
        ->findOverlappingWithRange($event->getStartDate(), $event->getEndDate())
    ;

    if (count($conflicts) > 0) {
        $context->addViolationAt(
            'startDate',
            'There is already an event during this time!'
        );
    }
}

$form = $this->createForm(new EventType, null, array(
    'em' => $this->getDoctrine()->getManager()
))

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $em = $options['em'];
}

Creating a Proper Custom Validation Constraint¶

There’s nothing wrong with what we have so far, but for the sake of reusability, clean code and unit testing, it can be much better.

The ultimate solution to custom validation is to create your own constraint. Fortunately, we’ve already done most of the work. Start by creating a new UniqueEventDate class:

// src/KnpU/QADayBundle/Validator/UniqueEventDate.php
namespace KnpU\QADayBundle\Validator;

use Symfony\Component\Validator\Constraint;

/** @Annotation */
class UniqueEventDate extends Constraint
{
    public function validatedBy()
    {
        return 'unique_event_date';
    }

    public function getTargets()
    {
        return self::CLASS_CONSTRAINT;
    }
}

Yep, this class is so simple it’s silly. Each custom validation constraint is actually two classes: one “Constraint” (seen here) that holds some options and another “Constraint Validator” (shown next) which does all the work. In fact, you can find these for the built-in constraints, for example NotBlank and NotBlankValidator.

There are 3 interesting parts to this class:

1) The @Annotation will eventually allow us to reference this constraints in the Event class via, well, annotations.

2) The validatedBy tells Symfony about the “Constraint Validator” that will actually do the heavy lifting. The unique_event_date string shouldn’t make sense yet - but it’ll be more obvious in a minute.

3) The getTargets method defines whether this constraint can be applied to an entire class, a property, or both. Again, since we need multiple values on Event in order to make our validation decision, we will apply the constraint to the entire class.

Next, create the “Constraint Validator” class:

// src/KnpU/QADayBundle/Validator/UniqueEventDateValidator.php
namespace KnpU\QADayBundle\Validator;

use Symfony\Component\Validator\ConstraintValidator;
use Doctrine\ORM\EntityManager;
use Symfony\Component\Validator\Constraint;

class UniqueEventDateValidator extends ConstraintValidator
{
    private $em;

    public function __construct(EntityManager $em)
    {
        $this->em = $em;
    }

    public function validate($object, Constraint $constraint)
    {
        die('hold on, we\'ll fill finish this in a second...');
    }
}

In a second, we’ll fill this class in and have it do all the validation work. But first, register it as a service and tag it with a special validator.constraint_validator tag:

# src/KnpU/QADayBundle/Resources/config/services.yml
services:
    unique_event_date_validator:
        class: KnpU\QADayBundle\Validator\UniqueEventDateValidator
        arguments:
            - "@doctrine.orm.entity_manager"
        tags:
            -
                name: validator.constraint_validator
                alias: unique_event_date

Notice that the alias we use with the tag corresponds with the value that the Constraint class returns in validateBy. This is how Symfony knows that the UniqueEventDateValidator is the real muscle behind the UniqueEventDate constraint.

Ok! Before we fill in the logic in the validate method, let’s try this out! The new constraint isn’t magically activated - we activate it like any other constraint, with annotations (or YAML, if you prefer):

// src/KnpU/QADayBundle/Entity/Event.php
// ...

use KnpU\QADayBundle\Validator\UniqueEventDate;

/**
 * @ORM\Entity(repositoryClass="KnpU\QADayBundle\Entity\EventRepository")
 * @UniqueEventDate()
 */
class Event
{
    // ...
}

When you submit the form, the UniqueEventDate constraint is triggered, and ultimately the UniqueEventDateValidator::validate method is called. In other words, you’ll see our die statement print.

Ok, let’s finish this! Copy the logic from the controller validateEventDates method and remove it and the constraints option while you’re there. Paste it into UniqueEventDateValidator::validate and adjust it accordingly:

// src/KnpU/QADayBundle/Validator/UniqueEventDateValidator.php
public function validate($object, Constraint $constraint)
{
    $conflicts = $this->em
        ->getRepository('QADayBundle:Event')
        ->findOverlappingWithRange($object->getStartDate(), $object->getEndDate())
    ;

    if (count($conflicts) > 0) {
        $this->context->addViolationAt('startDate', 'There is already an event during this time!');
    }
}

Let’s walk through the differences:

1) Since we’ve injected Doctrine’s Entity Manager, we can access it and get the EventRepository through $this->em.

2) Since we applied the UniqueEventDate constraint to the Event class, the entire Event object is passed as the first argument to this method (i.e. $object).

3) The ExecutionContext is stored automatically on the $this->context property.

That’s it! When you re-submit the form, the UniqueEventDate constraint on Event activates this method, which does all the work.

Through all of this, one nice thing is that we were always in complete control of which field our error was attached to. I chose to attach the error to the startDate field, but you can use whatever makes sense to you. If you use the addViolation method instead, the error will be attached to the whole form and displayed at the top:

$this->context->addViolation('There is already an event during this time!');

Ok, start validating!