From 6155df4da30ec3be693b49588f8523d3393d55ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Sch=C3=A4dlich?= Date: Sun, 31 Mar 2019 19:21:24 +0200 Subject: [PATCH 1/3] [Validator] Add docs for number constraints * Positive constraint * PositiveOrZero constraint * Negative constraint * NegativeOrZero constraint --- reference/constraints/Negative.rst | 82 +++++++++++++++++++++++ reference/constraints/NegativeOrZero.rst | 83 ++++++++++++++++++++++++ reference/constraints/Positive.rst | 82 +++++++++++++++++++++++ reference/constraints/PositiveOrZero.rst | 83 ++++++++++++++++++++++++ reference/constraints/map.rst.inc | 7 ++ 5 files changed, 337 insertions(+) create mode 100644 reference/constraints/Negative.rst create mode 100644 reference/constraints/NegativeOrZero.rst create mode 100644 reference/constraints/Positive.rst create mode 100644 reference/constraints/PositiveOrZero.rst diff --git a/reference/constraints/Negative.rst b/reference/constraints/Negative.rst new file mode 100644 index 00000000000..59642de781e --- /dev/null +++ b/reference/constraints/Negative.rst @@ -0,0 +1,82 @@ +Negative +======== + +.. versionadded:: 4.3 + + The ``Negative`` constraint was introduced in Symfony 4.3. + +Validates that a value is a negative number. To force that a value is a negative +number or equal to zero, see :doc:`/reference/constraints/NegativeOrZero`. +To force a value is positive, see :doc:`/reference/constraints/Positive`. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\Negative` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\LesserThanValidator` +========== =================================================================== + +Basic Usage +----------- + +The following constraint ensure that: + +* the ``withdraw`` of a bankaccount ``TransferItem`` is a negative number (lesser than zero) + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/TransferItem.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class TransferItem + { + /** + * @Assert\Negative + */ + protected $withdraw; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\TransferItem: + properties: + withdraw: + - Negative + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/TransferItem.php + namespace App\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class TransferItem + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('withdraw', new Assert\Negative(); + } + } diff --git a/reference/constraints/NegativeOrZero.rst b/reference/constraints/NegativeOrZero.rst new file mode 100644 index 00000000000..c703c30cbaf --- /dev/null +++ b/reference/constraints/NegativeOrZero.rst @@ -0,0 +1,83 @@ +NegativeOrZero +============== + +.. versionadded:: 4.3 + + The ``NegativeOrZero`` constraint was introduced in Symfony 4.3. + +Validates that a value is a negative number or equal to zero. To force that a value +is only a negative number, see :doc:`/reference/constraints/Negative`. +To force a value is positive or equal to zero, +see :doc:`/reference/constraints/PositiveOrZero`. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\NegativeOrZero` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\LesserThanOrEqualValidator` +========== =================================================================== + +Basic Usage +----------- + +The following constraint ensure that: + +* the ``withdraw`` of a bankaccount ``TransferItem`` is a negative number or equal to zero + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/TransferItem.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class TransferItem + { + /** + * @Assert\NegativeOrZero + */ + protected $withdraw; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\TransferItem: + properties: + withdraw: + - NegativeOrZero + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/TransferItem.php + namespace App\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class TransferItem + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('withdraw', new Assert\NegativeOrZero(); + } + } diff --git a/reference/constraints/Positive.rst b/reference/constraints/Positive.rst new file mode 100644 index 00000000000..695cba80637 --- /dev/null +++ b/reference/constraints/Positive.rst @@ -0,0 +1,82 @@ +Positive +======== + +.. versionadded:: 4.3 + + The ``Positive`` constraint was introduced in Symfony 4.3. + +Validates that a value is a positive number. To force that a value is positive +number or equal to zero, see :doc:`/reference/constraints/PositiveOrZero`. +To force a value is negative, see :doc:`/reference/constraints/Negative`. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\Positive` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanValidator` +========== =================================================================== + +Basic Usage +----------- + +The following constraint ensure that: + +* the ``income`` of an ``Employee`` is a positive number (greater than zero) + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/Employee.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Employee + { + /** + * @Assert\Positive + */ + protected $income; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Employee: + properties: + income: + - Positive + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Employee.php + namespace App\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Employee + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('income', new Assert\Positive(); + } + } diff --git a/reference/constraints/PositiveOrZero.rst b/reference/constraints/PositiveOrZero.rst new file mode 100644 index 00000000000..dce02944566 --- /dev/null +++ b/reference/constraints/PositiveOrZero.rst @@ -0,0 +1,83 @@ +PositiveOrZero +============== + +.. versionadded:: 4.3 + + The ``PositiveOrZero`` constraint was introduced in Symfony 4.3. + +Validates that a value is a positive number or equal to zero. To force that +a value is only a positiven umber, see :doc:`/reference/constraints/Positive`. +To force a value is negative or equal to zero, +see :doc:`/reference/constraints/NegativeOrZero`. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\PositiveOrZero` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqualValidator` +========== =================================================================== + +Basic Usage +----------- + +The following constraint ensure that: + +* the number of ``siblings`` of a ``Person`` is positive or zero + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/Person.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + /** + * @Assert\PositiveOrZero + */ + protected $siblings; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Person: + properties: + siblings: + - PositiveOrZero + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Person.php + namespace App\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('siblings', new Assert\PositiveOrZero(); + } + } diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 4f95a168242..e94bfec7a78 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -38,6 +38,13 @@ Comparison Constraints * :doc:`Range ` * :doc:`DivisibleBy ` +Number Constraints +~~~~~~~~~~~~~~~~~~ +* :doc:`Date ` +* :doc:`Date ` +* :doc:`Date ` +* :doc:`Date ` + Date Constraints ~~~~~~~~~~~~~~~~ From 61878ee5eea9cd775f739759cb2e29ae638fce14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Sch=C3=A4dlich?= Date: Mon, 1 Apr 2019 09:27:57 +0200 Subject: [PATCH 2/3] [Validator] Changes after code review --- reference/constraints.rst | 5 +++++ reference/constraints/Negative.rst | 26 +++++++++++++++++++++++- reference/constraints/NegativeOrZero.rst | 26 +++++++++++++++++++++++- reference/constraints/Positive.rst | 26 +++++++++++++++++++++++- reference/constraints/PositiveOrZero.rst | 26 +++++++++++++++++++++++- reference/constraints/map.rst.inc | 8 ++++---- 6 files changed, 109 insertions(+), 8 deletions(-) diff --git a/reference/constraints.rst b/reference/constraints.rst index d81a4eefd37..2e30e3ee19f 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -32,6 +32,11 @@ Validation Constraints Reference constraints/Range constraints/DivisibleBy + constraints/Positive + constraints/PositiveOrZero + constraints/Negative + constraints/NegativeOrZero + constraints/Date constraints/DateTime constraints/Time diff --git a/reference/constraints/Negative.rst b/reference/constraints/Negative.rst index 59642de781e..0a3e91c4fce 100644 --- a/reference/constraints/Negative.rst +++ b/reference/constraints/Negative.rst @@ -77,6 +77,30 @@ The following constraint ensure that: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('withdraw', new Assert\Negative(); + $metadata->addPropertyConstraint('withdraw', new Assert\Negative()); } } + +Available Options +----------------- + +.. include:: /reference/constraints/_groups-option.rst.inc + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be negative.`` + +The default message supplied when the value is not less than zero. + +You can use the following parameters in this message: + +============================= ================================================ +Parameter Description +============================= ================================================ +``{{ compared_value }}`` Always zero +``{{ compared_value_type }}`` The expected value type +``{{ value }}`` The current (invalid) value +============================= ================================================ + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/NegativeOrZero.rst b/reference/constraints/NegativeOrZero.rst index c703c30cbaf..86e9b85d78a 100644 --- a/reference/constraints/NegativeOrZero.rst +++ b/reference/constraints/NegativeOrZero.rst @@ -78,6 +78,30 @@ The following constraint ensure that: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('withdraw', new Assert\NegativeOrZero(); + $metadata->addPropertyConstraint('withdraw', new Assert\NegativeOrZero()); } } + +Available Options +----------------- + +.. include:: /reference/constraints/_groups-option.rst.inc + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be either negative or zero.`` + +The default message supplied when the value is not less than or equal to zero. + +You can use the following parameters in this message: + +============================= ================================================ +Parameter Description +============================= ================================================ +``{{ compared_value }}`` Always zero +``{{ compared_value_type }}`` The expected value type +``{{ value }}`` The current (invalid) value +============================= ================================================ + +.. include:: /reference/constraints/_payload-option.rst.inc \ No newline at end of file diff --git a/reference/constraints/Positive.rst b/reference/constraints/Positive.rst index 695cba80637..1897758c3bf 100644 --- a/reference/constraints/Positive.rst +++ b/reference/constraints/Positive.rst @@ -77,6 +77,30 @@ The following constraint ensure that: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('income', new Assert\Positive(); + $metadata->addPropertyConstraint('income', new Assert\Positive()); } } + +Available Options +----------------- + +.. include:: /reference/constraints/_groups-option.rst.inc + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be positive.`` + +The default message supplied when the value is not greater than zero. + +You can use the following parameters in this message: + +============================= ================================================ +Parameter Description +============================= ================================================ +``{{ compared_value }}`` Always zero +``{{ compared_value_type }}`` The expected value type +``{{ value }}`` The current (invalid) value +============================= ================================================ + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/PositiveOrZero.rst b/reference/constraints/PositiveOrZero.rst index dce02944566..44e736ee044 100644 --- a/reference/constraints/PositiveOrZero.rst +++ b/reference/constraints/PositiveOrZero.rst @@ -78,6 +78,30 @@ The following constraint ensure that: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('siblings', new Assert\PositiveOrZero(); + $metadata->addPropertyConstraint('siblings', new Assert\PositiveOrZero()); } } + +Available Options +----------------- + +.. include:: /reference/constraints/_groups-option.rst.inc + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should be either positive or zero.`` + +The default message supplied when the value is not greater than or equal to zero. + +You can use the following parameters in this message: + +============================= ================================================ +Parameter Description +============================= ================================================ +``{{ compared_value }}`` Always zero +``{{ compared_value_type }}`` The expected value type +``{{ value }}`` The current (invalid) value +============================= ================================================ + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index e94bfec7a78..5402a2fd0d2 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -40,10 +40,10 @@ Comparison Constraints Number Constraints ~~~~~~~~~~~~~~~~~~ -* :doc:`Date ` -* :doc:`Date ` -* :doc:`Date ` -* :doc:`Date ` +* :doc:`Positive ` +* :doc:`PositiveOrZero ` +* :doc:`Negative ` +* :doc:`NegativeOrZero ` Date Constraints ~~~~~~~~~~~~~~~~ From 0f70621827d4b7a450e3a6b8a4f29422a725dbd3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Sch=C3=A4dlich?= Date: Mon, 1 Apr 2019 09:39:31 +0200 Subject: [PATCH 3/3] [Validator] Add better example for NegativeOrZero constraint --- reference/constraints/NegativeOrZero.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/reference/constraints/NegativeOrZero.rst b/reference/constraints/NegativeOrZero.rst index 86e9b85d78a..7d0dc452a5f 100644 --- a/reference/constraints/NegativeOrZero.rst +++ b/reference/constraints/NegativeOrZero.rst @@ -24,7 +24,7 @@ Basic Usage The following constraint ensure that: -* the ``withdraw`` of a bankaccount ``TransferItem`` is a negative number or equal to zero +* the ``level`` of a ``UnderGroundGarage`` is a negative number or equal to zero .. configuration-block:: @@ -35,20 +35,20 @@ The following constraint ensure that: use Symfony\Component\Validator\Constraints as Assert; - class TransferItem + class UnderGroundGarage { /** * @Assert\NegativeOrZero */ - protected $withdraw; + protected $level; } .. code-block:: yaml # config/validator/validation.yaml - App\Entity\TransferItem: + App\Entity\UnderGroundGarage: properties: - withdraw: + level: - NegativeOrZero .. code-block:: xml @@ -59,8 +59,8 @@ The following constraint ensure that: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - - + + @@ -68,17 +68,17 @@ The following constraint ensure that: .. code-block:: php - // src/Entity/TransferItem.php + // src/Entity/UnderGroundGarage.php namespace App\Entity; use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; - class TransferItem + class UnderGroundGarage { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('withdraw', new Assert\NegativeOrZero()); + $metadata->addPropertyConstraint('level', new Assert\NegativeOrZero()); } }