From f4afaab4abf5f191e9d2fdd415eccf7c9be75bb8 Mon Sep 17 00:00:00 2001 From: Colin O'Dell Date: Fri, 28 Feb 2014 15:21:23 -0500 Subject: [PATCH 1/3] Documentation for the new Uuid constraint --- reference/constraints/Uuid.rst | 126 +++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 reference/constraints/Uuid.rst diff --git a/reference/constraints/Uuid.rst b/reference/constraints/Uuid.rst new file mode 100644 index 00000000000..1d315bdd2a8 --- /dev/null +++ b/reference/constraints/Uuid.rst @@ -0,0 +1,126 @@ +Uuid +== + +.. versionadded:: 2.5 + The Uuid constraint was added in Symfony 2.5. + +Validates that a value is a valid `Universally unique identifier (UUID)`_ per `RFC 4122`_. +By default, this will validate the format according to the RFC's guidelines, but this can +be relaxed to accept non-standard UUIDs that other systems (like PostgreSQL) accept. +UUID versions can also be restricted using a whitelist. + ++----------------+---------------------------------------------------------------------+ +| Applies to | :ref:`property or method ` | ++----------------+---------------------------------------------------------------------+ +| Options | - `message`_ | +| | - `strict`_ | +| | - `versions`_ | ++----------------+---------------------------------------------------------------------+ +| Class | :class:`Symfony\\Component\\Validator\\Constraints\\Uuid` | ++----------------+---------------------------------------------------------------------+ +| Validator | :class:`Symfony\\Component\\Validator\\Constraints\\UuidValidator` | ++----------------+---------------------------------------------------------------------+ + +Basic Usage +----------- + +.. configuration-block:: + + .. code-block:: yaml + + # src/UploadsBundle/Resources/config/validation.yml + Acme\UploadsBundle\Entity\File: + properties: + identifier: + - Uuid: ~ + + .. code-block:: php-annotations + + // src/Acme/UploadsBundle/Entity/File.php + namespace Acme\UploadsBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class File + { + /** + * @Assert\Uuid + */ + protected $identifier; + } + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Acme/UploadsBundle/Entity/File.php + namespace Acme\UploadsBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class File + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('identifier', new Assert\Uuid()); + } + } + + +Options +------- + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This is not a valid UUID.`` + +This message is shown if the string is not a valid UUID. + +strict +~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +If this option is set to ``true`` the constraint will check if the UUID is formatted per the +RFC's input format rules: ``216fff40-98d9-11e3-a5e2-0800200c9a66``. Setting this to ``false`` +will allow alternate input formats like:: + + 216f-ff40-98d9-11e3-a5e2-0800-200c-9a66 + {216fff40-98d9-11e3-a5e2-0800200c9a66} + 216fff4098d911e3a5e20800200c9a66 + +versions +~~~~~~~~ + +**type**: ``int[]`` **default**: ``[1,2,3,4,5]`` + +This option can be used to only allow specific `UUID versions`_. Valid versions are 1 - 5. +The following PHP constants can also be used: + +* ``Uuid::V1_MAC`` +* ``Uuid::V2_DCE`` +* ``Uuid::V3_MD5`` +* ``Uuid::V4_RANDOM`` +* ``Uuid::V5_SHA1`` + +All five versions are allowed by default. + +.. _`Universally unique identifier (UUID)`: http://en.wikipedia.org/wiki/Universally_unique_identifier +.. _`RFC 4122`: http://tools.ietf.org/html/rfc4122 +.. _`UUID versions`: http://en.wikipedia.org/wiki/Universally_unique_identifier#Variants_and_versions + From 3ea91372096bd7486fa04e85ad706e6302f0a506 Mon Sep 17 00:00:00 2001 From: Colin O'Dell Date: Fri, 28 Feb 2014 15:22:50 -0500 Subject: [PATCH 2/3] List the UUID constraint in the reference section --- reference/constraints.rst | 1 + reference/constraints/map.rst.inc | 1 + 2 files changed, 2 insertions(+) diff --git a/reference/constraints.rst b/reference/constraints.rst index 0b209bbf012..ac8ef5ae33c 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -18,6 +18,7 @@ Validation Constraints Reference constraints/Url constraints/Regex constraints/Ip + constraints/Uuid constraints/Range diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 237329866d4..686ad22bca5 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -20,6 +20,7 @@ String Constraints * :doc:`Url ` * :doc:`Regex ` * :doc:`Ip ` +* :doc:`Uuid` Number Constraints ~~~~~~~~~~~~~~~~~~ From 6f6c03fe6c28994909f7eafebbaaa46f1de07fa2 Mon Sep 17 00:00:00 2001 From: Colin O'Dell Date: Fri, 28 Feb 2014 15:43:14 -0500 Subject: [PATCH 3/3] Fix formatting issues --- reference/constraints/Uuid.rst | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/reference/constraints/Uuid.rst b/reference/constraints/Uuid.rst index 1d315bdd2a8..4db4fc8ceab 100644 --- a/reference/constraints/Uuid.rst +++ b/reference/constraints/Uuid.rst @@ -1,8 +1,8 @@ Uuid -== +==== .. versionadded:: 2.5 - The Uuid constraint was added in Symfony 2.5. + The Uuid constraint was introduced in Symfony 2.5. Validates that a value is a valid `Universally unique identifier (UUID)`_ per `RFC 4122`_. By default, this will validate the format according to the RFC's guidelines, but this can @@ -97,12 +97,12 @@ strict **type**: ``boolean`` **default**: ``true`` If this option is set to ``true`` the constraint will check if the UUID is formatted per the -RFC's input format rules: ``216fff40-98d9-11e3-a5e2-0800200c9a66``. Setting this to ``false`` -will allow alternate input formats like:: +RFC's input format rules: ``216fff40-98d9-11e3-a5e2-0800200c9a66``. Setting this to ``false`` +will allow alternate input formats like: - 216f-ff40-98d9-11e3-a5e2-0800-200c-9a66 - {216fff40-98d9-11e3-a5e2-0800200c9a66} - 216fff4098d911e3a5e20800200c9a66 +* ``216f-ff40-98d9-11e3-a5e2-0800-200c-9a66`` +* ``{216fff40-98d9-11e3-a5e2-0800200c9a66}`` +* ``216fff4098d911e3a5e20800200c9a66`` versions ~~~~~~~~ @@ -123,4 +123,3 @@ All five versions are allowed by default. .. _`Universally unique identifier (UUID)`: http://en.wikipedia.org/wiki/Universally_unique_identifier .. _`RFC 4122`: http://tools.ietf.org/html/rfc4122 .. _`UUID versions`: http://en.wikipedia.org/wiki/Universally_unique_identifier#Variants_and_versions -