[ci skip] Add documentation for using custom validator

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

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.

docs/reference.rst

@@ -28,3 +28,4 @@ Reference
     reference/helper
     reference/name-based-namespaces
     reference/calculators
+    reference/validators

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.