diff --git a/book/validation.rst b/book/validation.rst index f454b78e525..35c29958a4c 100644 --- a/book/validation.rst +++ b/book/validation.rst @@ -630,7 +630,7 @@ this method must return ``true``: class Author { /** - * @Assert\True(message = "The password cannot match your first name") + * @Assert\IsTrue(message = "The password cannot match your first name") */ public function isPasswordLegal() { @@ -675,7 +675,7 @@ this method must return ``true``: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addGetterConstraint('passwordLegal', new Assert\True(array( + $metadata->addGetterConstraint('passwordLegal', new Assert\IsTrue(array( 'message' => 'The password cannot match your first name', ))); } @@ -937,7 +937,7 @@ username and the password are different only if all other validation passes private $password; /** - * @Assert\True(message="The password cannot match your username", groups={"Strict"}) + * @Assert\IsTrue(message="The password cannot match your username", groups={"Strict"}) */ public function isPasswordLegal() { @@ -1011,7 +1011,7 @@ username and the password are different only if all other validation passes $metadata->addPropertyConstraint('username', new Assert\NotBlank()); $metadata->addPropertyConstraint('password', new Assert\NotBlank()); - $metadata->addGetterConstraint('passwordLegal', new Assert\True(array( + $metadata->addGetterConstraint('passwordLegal', new Assert\IsTrue(array( 'message' => 'The password cannot match your first name', 'groups' => array('Strict'), ))); diff --git a/reference/constraints.rst b/reference/constraints.rst index 94077dd3052..491aa8e626c 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -8,9 +8,9 @@ Validation Constraints Reference constraints/NotBlank constraints/Blank constraints/NotNull - constraints/Null - constraints/True - constraints/False + constraints/IsNull + constraints/IsTrue + constraints/IsFalse constraints/Type constraints/Email diff --git a/reference/constraints/Blank.rst b/reference/constraints/Blank.rst index 4ce7426116c..ffbf196f435 100644 --- a/reference/constraints/Blank.rst +++ b/reference/constraints/Blank.rst @@ -3,7 +3,7 @@ Blank Validates that a value is blank, defined as equal to a blank string or equal to ``null``. To force that a value strictly be equal to ``null``, see the -:doc:`/reference/constraints/Null` constraint. To force that a value is +:doc:`/reference/constraints/IsNull` constraint. To force that a value is *not* blank, see :doc:`/reference/constraints/NotBlank`. +----------------+---------------------------------------------------------------------+ diff --git a/reference/constraints/False.rst b/reference/constraints/False.rst index 9e1cdc7a45f..41bee6ee926 100644 --- a/reference/constraints/False.rst +++ b/reference/constraints/False.rst @@ -1,120 +1,9 @@ False ===== -Validates that a value is ``false``. Specifically, this checks to see if -the value is exactly ``false``, exactly the integer ``0``, or exactly the -string "``0``". - -Also see :doc:`True `. - -+----------------+---------------------------------------------------------------------+ -| Applies to | :ref:`property or method ` | -+----------------+---------------------------------------------------------------------+ -| Options | - `message`_ | -| | - `payload`_ | -+----------------+---------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Validator\\Constraints\\False` | -+----------------+---------------------------------------------------------------------+ -| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\FalseValidator` | -+----------------+---------------------------------------------------------------------+ - -Basic Usage ------------ - -The ``False`` constraint can be applied to a property or a "getter" method, -but is most commonly useful in the latter case. For example, suppose that -you want to guarantee that some ``state`` property is *not* in a dynamic -``invalidStates`` array. First, you'd create a "getter" method:: - - protected $state; - - protected $invalidStates = array(); - - public function isStateInvalid() - { - return in_array($this->state, $this->invalidStates); - } - -In this case, the underlying object is only valid if the ``isStateInvalid`` -method returns **false**: - -.. configuration-block:: - - .. code-block:: php-annotations - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - use Symfony\Component\Validator\Constraints as Assert; - - class Author - { - /** - * @Assert\False( - * message = "You've entered an invalid state." - * ) - */ - public function isStateInvalid() - { - // ... - } - } - - .. code-block:: yaml - - # src/AppBundle/Resources/config/validation.yml - AppBundle\Entity\Author - getters: - stateInvalid: - - 'False': - message: You've entered an invalid state. - - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - use Symfony\Component\Validator\Mapping\ClassMetadata; - use Symfony\Component\Validator\Constraints as Assert; - - class Author - { - public static function loadValidatorMetadata(ClassMetadata $metadata) - { - $metadata->addGetterConstraint('stateInvalid', new Assert\False()); - } - } - .. caution:: - When using YAML, be sure to surround ``False`` with quotes (``'False'``) - or else YAML will convert this into a ``false`` boolean value. - -Options -------- - -message -~~~~~~~ - -**type**: ``string`` **default**: ``This value should be false.`` - -This message is shown if the underlying data is not false. + The ``False`` constraint is deprecated since Symfony 2.7 + and will be removed in Symfony 3.0. Use the ``IsFalse`` constraint instead. -.. include:: /reference/constraints/_payload-option.rst.inc +.. include:: /reference/constraints/IsFalse.rst diff --git a/reference/constraints/IsFalse.rst b/reference/constraints/IsFalse.rst new file mode 100644 index 00000000000..a4171bcf598 --- /dev/null +++ b/reference/constraints/IsFalse.rst @@ -0,0 +1,115 @@ +IsFalse +======= + +Validates that a value is ``false``. Specifically, this checks to see if +the value is exactly ``false``, exactly the integer ``0``, or exactly the +string "``0``". + +Also see :doc:`IsTrue `. + ++----------------+-----------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+-----------------------------------------------------------------------+ +| Options | - `message`_ | +| | - `payload`_ | ++----------------+-----------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\IsFalse` | ++----------------+-----------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\IsFalseValidator` | ++----------------+-----------------------------------------------------------------------+ + +Basic Usage +----------- + +The ``IsFalse`` constraint can be applied to a property or a "getter" method, +but is most commonly useful in the latter case. For example, suppose that +you want to guarantee that some ``state`` property is *not* in a dynamic +``invalidStates`` array. First, you'd create a "getter" method:: + + protected $state; + + protected $invalidStates = array(); + + public function isStateInvalid() + { + return in_array($this->state, $this->invalidStates); + } + +In this case, the underlying object is only valid if the ``isStateInvalid`` +method returns **false**: + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + /** + * @Assert\IsFalse( + * message = "You've entered an invalid state." + * ) + */ + public function isStateInvalid() + { + // ... + } + } + + .. code-block:: yaml + + # src/AppBundle/Resources/config/validation.yml + AppBundle\Entity\Author + getters: + stateInvalid: + - 'IsFalse': + message: You've entered an invalid state. + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addGetterConstraint('stateInvalid', new Assert\IsFalse()); + } + } + +Options +------- + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be false.`` + +This message is shown if the underlying data is not false. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/IsNull.rst b/reference/constraints/IsNull.rst new file mode 100644 index 00000000000..7c281fd1592 --- /dev/null +++ b/reference/constraints/IsNull.rst @@ -0,0 +1,93 @@ +IsNull +====== + +Validates that a value is exactly equal to ``null``. To force that a property +is simply blank (blank string or ``null``), see the :doc:`/reference/constraints/Blank` +constraint. To ensure that a property is not null, see :doc:`/reference/constraints/NotNull`. + +Also see :doc:`NotNull `. + ++----------------+-----------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+-----------------------------------------------------------------------+ +| Options | - `message`_ | +| | - `payload`_ | ++----------------+-----------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\IsNull` | ++----------------+-----------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\IsNullValidator` | ++----------------+-----------------------------------------------------------------------+ + +Basic Usage +----------- + +If, for some reason, you wanted to ensure that the ``firstName`` property +of an ``Author`` class exactly equal to ``null``, you could do the following: + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + /** + * @Assert\IsNull() + */ + protected $firstName; + } + + .. code-block:: yaml + + # src/AppBundle/Resources/config/validation.yml + AppBundle\Entity\Author: + properties: + firstName: + - 'IsNull': ~ + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('firstName', Assert\IsNull()); + } + } + +Options +------- + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be null.`` + +This is the message that will be shown if the value is not ``null``. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/IsTrue.rst b/reference/constraints/IsTrue.rst new file mode 100644 index 00000000000..4d971a419ae --- /dev/null +++ b/reference/constraints/IsTrue.rst @@ -0,0 +1,129 @@ +IsTrue +====== + +Validates that a value is ``true``. Specifically, this checks to see if +the value is exactly ``true``, exactly the integer ``1``, or exactly the +string "``1``". + +Also see :doc:`IsFalse `. + ++----------------+-----------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+-----------------------------------------------------------------------+ +| Options | - `message`_ | +| | - `payload`_ | ++----------------+-----------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\IsTrue` | ++----------------+-----------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\IsTrueValidator` | ++----------------+-----------------------------------------------------------------------+ + +Basic Usage +----------- + +This constraint can be applied to properties (e.g. a ``termsAccepted`` property +on a registration model) or to a "getter" method. It's most powerful in +the latter case, where you can assert that a method returns a true value. +For example, suppose you have the following method:: + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + class Author + { + protected $token; + + public function isTokenValid() + { + return $this->token == $this->generateToken(); + } + } + +Then you can constrain this method with ``IsTrue``. + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + protected $token; + + /** + * @Assert\IsTrue(message = "The token is invalid") + */ + public function isTokenValid() + { + return $this->token == $this->generateToken(); + } + } + + .. code-block:: yaml + + # src/AppBundle/Resources/config/validation.yml + AppBundle\Entity\Author: + getters: + tokenValid: + - 'IsTrue': + message: The token is invalid. + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/AppBundle/Entity/Author.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints\IsTrue; + + class Author + { + protected $token; + + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addGetterConstraint('tokenValid', new IsTrue(array( + 'message' => 'The token is invalid.', + ))); + } + + public function isTokenValid() + { + return $this->token == $this->generateToken(); + } + } + +If the ``isTokenValid()`` returns false, the validation will fail. + +Options +------- + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be true.`` + +This message is shown if the underlying data is not true. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Null.rst b/reference/constraints/Null.rst index 81691ca79a9..f6328fb14dd 100644 --- a/reference/constraints/Null.rst +++ b/reference/constraints/Null.rst @@ -1,96 +1,9 @@ Null ==== -Validates that a value is exactly equal to ``null``. To force that a property -is simply blank (blank string or ``null``), see the :doc:`/reference/constraints/Blank` -constraint. To ensure that a property is not null, see :doc:`/reference/constraints/NotNull`. - -+----------------+-----------------------------------------------------------------------+ -| Applies to | :ref:`property or method ` | -+----------------+-----------------------------------------------------------------------+ -| Options | - `message`_ | -| | - `payload`_ | -+----------------+-----------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Validator\\Constraints\\Null` | -+----------------+-----------------------------------------------------------------------+ -| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\NullValidator` | -+----------------+-----------------------------------------------------------------------+ - -Basic Usage ------------ - -If, for some reason, you wanted to ensure that the ``firstName`` property -of an ``Author`` class exactly equal to ``null``, you could do the following: - -.. configuration-block:: - - .. code-block:: php-annotations - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - use Symfony\Component\Validator\Constraints as Assert; - - class Author - { - /** - * @Assert\Null() - */ - protected $firstName; - } - - .. code-block:: yaml - - # src/AppBundle/Resources/config/validation.yml - AppBundle\Entity\Author: - properties: - firstName: - - 'Null': ~ - - .. code-block:: xml - - - - - - - - - - - - - .. code-block:: php - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - use Symfony\Component\Validator\Mapping\ClassMetadata; - use Symfony\Component\Validator\Constraints as Assert; - - class Author - { - public static function loadValidatorMetadata(ClassMetadata $metadata) - { - $metadata->addPropertyConstraint('firstName', Assert\Null()); - } - } - .. caution:: - When using YAML, be sure to surround ``Null`` with quotes (``'Null'``) - or else YAML will convert this into a ``null`` value. - -Options -------- - -message -~~~~~~~ - -**type**: ``string`` **default**: ``This value should be null.`` - -This is the message that will be shown if the value is not ``null``. + The ``Null`` constraint is deprecated since Symfony 2.7 + and will be removed in Symfony 3.0. Use the ``IsNull`` constraint instead. -.. include:: /reference/constraints/_payload-option.rst.inc +.. include:: /reference/constraints/IsNull.rst diff --git a/reference/constraints/True.rst b/reference/constraints/True.rst index 18dea513a45..285cd68bf15 100644 --- a/reference/constraints/True.rst +++ b/reference/constraints/True.rst @@ -1,134 +1,9 @@ True ==== -Validates that a value is ``true``. Specifically, this checks to see if -the value is exactly ``true``, exactly the integer ``1``, or exactly the -string "``1``". - -Also see :doc:`False `. - -+----------------+---------------------------------------------------------------------+ -| Applies to | :ref:`property or method ` | -+----------------+---------------------------------------------------------------------+ -| Options | - `message`_ | -| | - `payload`_ | -+----------------+---------------------------------------------------------------------+ -| Class | :class:`Symfony\\Component\\Validator\\Constraints\\True` | -+----------------+---------------------------------------------------------------------+ -| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\TrueValidator` | -+----------------+---------------------------------------------------------------------+ - -Basic Usage ------------ - -This constraint can be applied to properties (e.g. a ``termsAccepted`` property -on a registration model) or to a "getter" method. It's most powerful in -the latter case, where you can assert that a method returns a true value. -For example, suppose you have the following method:: - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - class Author - { - protected $token; - - public function isTokenValid() - { - return $this->token == $this->generateToken(); - } - } - -Then you can constrain this method with ``True``. - -.. configuration-block:: - - .. code-block:: php-annotations - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - use Symfony\Component\Validator\Constraints as Assert; - - class Author - { - protected $token; - - /** - * @Assert\True(message = "The token is invalid") - */ - public function isTokenValid() - { - return $this->token == $this->generateToken(); - } - } - - .. code-block:: yaml - - # src/AppBundle/Resources/config/validation.yml - AppBundle\Entity\Author: - getters: - tokenValid: - - 'True': - message: The token is invalid. - - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php - - // src/AppBundle/Entity/Author.php - namespace AppBundle\Entity; - - use Symfony\Component\Validator\Mapping\ClassMetadata; - use Symfony\Component\Validator\Constraints\True; - - class Author - { - protected $token; - - public static function loadValidatorMetadata(ClassMetadata $metadata) - { - $metadata->addGetterConstraint('tokenValid', new True(array( - 'message' => 'The token is invalid.', - ))); - } - - public function isTokenValid() - { - return $this->token == $this->generateToken(); - } - } - -If the ``isTokenValid()`` returns false, the validation will fail. - .. caution:: - When using YAML, be sure to surround ``True`` with quotes (``'True'``) - or else YAML will convert this into a ``true`` boolean value. - -Options -------- - -message -~~~~~~~ - -**type**: ``string`` **default**: ``This value should be true.`` - -This message is shown if the underlying data is not true. + The ``True`` constraint is deprecated since Symfony 2.7 + and will be removed in Symfony 3.0. Use the ``IsTrue`` constraint instead. -.. include:: /reference/constraints/_payload-option.rst.inc +.. include:: /reference/constraints/IsTrue.rst