[Validator] Completed GroupSequence implementation

webmozart · webmozart · commit 8318286650b6 · 2014-03-30T18:28:54.000+02:00
diff --git a/src/Symfony/Component/Validator/Constraints/GroupSequence.php b/src/Symfony/Component/Validator/Constraints/GroupSequence.php
@@ -11,10 +11,44 @@
 
 namespace Symfony\Component\Validator\Constraints;
 
+use Symfony\Component\Validator\Exception\OutOfBoundsException;
 use Traversable;
 
 /**
- * Annotation for group sequences
+ * A sequence of validation groups.
+ *
+ * When validating a group sequence, each group will only be validated if all
+ * of the previous groups in the sequence succeeded. For example:
+ *
+ *     $validator->validateObject($address, new GroupSequence('Basic', 'Strict'));
+ *
+ * In the first step, all constraints that belong to the group "Basic" will be
+ * validated. If none of the constraints fail, the validator will then validate
+ * the constraints in group "Strict". This is useful, for example, if "Strict"
+ * contains expensive checks that require a lot of CPU or slow, external
+ * services. You usually don't want to run expensive checks if any of the cheap
+ * checks fails.
+ *
+ * When adding metadata to a class, you can override the "Default" group of
+ * that class with a group sequence:
+ *
+ *     /**
+ *      * @GroupSequence({"Address", "Strict"})
+ *      *\/
+ *     class Address
+ *     {
+ *         // ...
+ *     }
+ *
+ * Whenever you validate that object in the "Default" group, the group sequence
+ * will be validated:
+ *
+ *     $validator->validateObject($address);
+ *
+ * If you want to execute the constraints of the "Default" group for a class
+ * with an overridden default group, pass the class name as group name instead:
+ *
+ *     $validator->validateObject($address, "Address")
  *
  * @Annotation
  *
@@ -25,13 +59,14 @@
 class GroupSequence implements \ArrayAccess, \IteratorAggregate, \Countable
 {
     /**
-     * The members of the sequence
-     * @var array
+     * The groups in the sequence
+     *
+     * @var string[]|GroupSequence[]
      */
     public $groups;
 
     /**
-     * The group under which cascaded objects are validated when validating
+     * The group in which cascaded objects are validated when validating
      * this sequence.
      *
      * By default, cascaded objects are validated in each of the groups of
@@ -46,27 +81,80 @@ class GroupSequence implements \ArrayAccess, \IteratorAggregate, \Countable
      */
     public $cascadedGroup;
 
+    /**
+     * Creates a new group sequence.
+     *
+     * @param string[] $groups The groups in the sequence
+     */
     public function __construct(array $groups)
     {
         // Support for Doctrine annotations
         $this->groups = isset($groups['value']) ? $groups['value'] : $groups;
     }
 
+    /**
+     * Returns an iterator for this group.
+     *
+     * @return Traversable The iterator
+     *
+     * @see \IteratorAggregate::getIterator()
+     *
+     * @deprecated Implemented for backwards compatibility. To be removed in
+     *             Symfony 3.0.
+     */
     public function getIterator()
     {
         return new \ArrayIterator($this->groups);
     }
 
+    /**
+     * Returns whether the given offset exists in the sequence.
+     *
+     * @param integer $offset The offset
+     *
+     * @return Boolean Whether the offset exists
+     *
+     * @deprecated Implemented for backwards compatibility. To be removed in
+     *             Symfony 3.0.
+     */
     public function offsetExists($offset)
     {
         return isset($this->groups[$offset]);
     }
 
+    /**
+     * Returns the group at the given offset.
+     *
+     * @param integer $offset The offset
+     *
+     * @return string The group a the given offset
+     *
+     * @throws OutOfBoundsException If the object does not exist
+     *
+     * @deprecated Implemented for backwards compatibility. To be removed in
+     *             Symfony 3.0.
+     */
     public function offsetGet($offset)
     {
+        if (!isset($this->groups[$offset])) {
+            throw new OutOfBoundsException(sprintf(
+                'The offset "%s" does not exist.',
+                $offset
+            ));
+        }
+
         return $this->groups[$offset];
     }
 
+    /**
+     * Sets the group at the given offset.
+     *
+     * @param integer $offset The offset
+     * @param string  $value  The group name
+     *
+     * @deprecated Implemented for backwards compatibility. To be removed in
+     *             Symfony 3.0.
+     */
     public function offsetSet($offset, $value)
     {
         if (null !== $offset) {
@@ -78,11 +166,27 @@ public function offsetSet($offset, $value)
         $this->groups[] = $value;
     }
 
+    /**
+     * Removes the group at the given offset.
+     *
+     * @param integer $offset The offset
+     *
+     * @deprecated Implemented for backwards compatibility. To be removed in
+     *             Symfony 3.0.
+     */
     public function offsetUnset($offset)
     {
         unset($this->groups[$offset]);
     }
 
+    /**
+     * Returns the number of groups in the sequence.
+     *
+     * @return integer The number of groups
+     *
+     * @deprecated Implemented for backwards compatibility. To be removed in
+     *             Symfony 3.0.
+     */
     public function count()
     {
         return count($this->groups);
diff --git a/src/Symfony/Component/Validator/Exception/OutOfBoundsException.php b/src/Symfony/Component/Validator/Exception/OutOfBoundsException.php
@@ -0,0 +1,21 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Validator\Exception;
+
+/**
+ * Base OutOfBoundsException for the Validator component.
+ *
+ * @author Bernhard Schussek <bschussek@gmail.com>
+ */
+class OutOfBoundsException extends \OutOfBoundsException implements ExceptionInterface
+{
+}
diff --git a/src/Symfony/Component/Validator/Tests/Constraints/GroupSequenceTest.php b/src/Symfony/Component/Validator/Tests/Constraints/GroupSequenceTest.php
@@ -63,4 +63,22 @@ public function testArrayAccess()
         $this->assertTrue(isset($sequence[0]));
         $this->assertSame('Group 1', $sequence[0]);
     }
+
+    /**
+     * @expectedException \Symfony\Component\Validator\Exception\OutOfBoundsException
+     */
+    public function testGetExpectsExistingKey()
+    {
+        $sequence = new GroupSequence(array('Group 1', 'Group 2'));
+
+        $sequence[2];
+    }
+
+    public function testUnsetIgnoresNonExistingKeys()
+    {
+        $sequence = new GroupSequence(array('Group 1', 'Group 2'));
+
+        // should not fail
+        unset($sequence[2]);
+    }
 }
