From 58df4fab1a7efe5b537562aaf37d7675addf29cb Mon Sep 17 00:00:00 2001
From: Ben Ramsey <ben@benramsey.com>
Date: Mon, 9 Mar 2020 16:19:55 -0500
Subject: [PATCH] [ci skip] Add documentation for using custom validator

---
 docs/customize.rst            |  6 ++++++
 docs/customize/validators.rst | 39 +++++++++++++++++++++++++++++++++++
 docs/reference.rst            |  1 +
 docs/reference/validators.rst | 34 ++++++++++++++++++++++++++++++
 4 files changed, 80 insertions(+)
 create mode 100644 docs/customize/validators.rst
 create mode 100644 docs/reference/validators.rst

diff --git a/docs/customize.rst b/docs/customize.rst
index a539c35..25ddf8e 100644
--- a/docs/customize.rst
+++ b/docs/customize.rst
@@ -11,6 +11,7 @@ Customization
     customize/ordered-time-codec
     customize/timestamp-first-comb-codec
     customize/calculators
+    customize/validators
 
 ramsey/uuid offers a variety of ways to modify the standard behavior of the
 library through dependency injection. Using `FeatureSet`_, `UuidFactory`_, and
@@ -33,6 +34,11 @@ Using a Custom Calculator
     requirements require a different solution for making calculations, see
     :ref:`customize.calculators`.
 
+Using a Custom Validator
+    If your requirements require a different level of validation or a different
+    UUID format, you may replace the default validator. See
+    :ref:`customize.validators`, to learn more.
+
 
 .. _UuidFactory: https://github.com/ramsey/uuid/blob/master/src/UuidFactory.php
 .. _FeatureSet: https://github.com/ramsey/uuid/blob/master/src/FeatureSet.php
diff --git a/docs/customize/validators.rst b/docs/customize/validators.rst
new file mode 100644
index 0000000..db51e57
--- /dev/null
+++ b/docs/customize/validators.rst
@@ -0,0 +1,39 @@
+.. _customize.validators:
+
+========================
+Using a Custom Validator
+========================
+
+By default, ramsey/uuid validates UUID strings with the lenient validator
+:php:class:`Ramsey\\Uuid\\Validator\\GenericValidator`. This validator ensures
+the string is 36 characters, has the dashes in the correct places, and uses only
+hexadecimal values. It does not ensure the string is of the RFC 4122 variant or
+contains a valid version.
+
+The validator :php:class:`Ramsey\\Uuid\\Rfc4122\\Validator` validates UUID
+strings to ensure they match the RFC 4122 variant and contain a valid version.
+Since it is not enabled by default, you will need to configure ramsey/uuid to
+use it, if you want stricter validation.
+
+.. code-block:: php
+    :caption: Set an alternate validator to use for Uuid::isValid()
+    :name: customize.validators-example
+
+    use Ramsey\Uuid\Rfc4122\Validator as Rfc4122Validator;
+    use Ramsey\Uuid\Uuid;
+    use Ramsey\Uuid\UuidFactory;
+
+    $factory = new UuidFactory();
+    $factory->setValidator(new Rfc4122Validator());
+
+    Uuid::setFactory($factory);
+
+    if (!Uuid::isValid('2bfb5006-087b-9553-5082-e8f39337ad29')) {
+        echo "This UUID is not valid!\n";
+    }
+
+.. tip::
+
+    If you want to use your own validation, create a class that implements
+    :php:interface:`Ramsey\\Uuid\\Validator\\ValidatorInterface` and use the
+    same method to set your validator on the factory.
diff --git a/docs/reference.rst b/docs/reference.rst
index 4633089..00e27b6 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -28,3 +28,4 @@ Reference
     reference/helper
     reference/name-based-namespaces
     reference/calculators
+    reference/validators
diff --git a/docs/reference/validators.rst b/docs/reference/validators.rst
new file mode 100644
index 0000000..dc51adc
--- /dev/null
+++ b/docs/reference/validators.rst
@@ -0,0 +1,34 @@
+.. _reference.validators:
+
+==========
+Validators
+==========
+
+.. php:namespace:: Ramsey\Uuid\Validator
+
+.. php:interface:: ValidatorInterface
+
+    .. php:method:: getPattern()
+
+        :returns: The regular expression pattern used by this validator
+        :returntype: ``string``
+
+    .. php:method:: validate($uuid)
+
+        :param string $uuid: The string to validate as a UUID
+        :returns: True if the provided string represents a UUID, false otherwise
+        :returntype: ``bool``
+
+.. php:class:: GenericValidator
+
+    Implements :php:interface:`Ramsey\\Uuid\\Validator\\ValidatorInterface`.
+
+    GenericValidator validates strings as UUIDs of any variant.
+
+.. php:namespace:: Ramsey\Uuid\Rfc4122
+
+.. php:class:: Validator
+
+    Implements :php:interface:`Ramsey\\Uuid\\Validator\\ValidatorInterface`.
+
+    Rfc4122\Validator validates strings as UUIDs of the RFC 4122 variant.