From 29a4cc25d661904950a70da7086db0fc59de76da Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sat, 22 Mar 2014 20:53:57 +0100
Subject: [PATCH 1/4] Get started with the Validator docs

---
 components/index.rst                  |  1 +
 components/map.rst.inc                |  4 +++
 components/validator/index.rst        |  7 +++++
 components/validator/introduction.rst | 45 +++++++++++++++++++++++++++
 4 files changed, 57 insertions(+)
 create mode 100644 components/validator/index.rst
 create mode 100644 components/validator/introduction.rst

diff --git a/components/index.rst b/components/index.rst
index 739b9e84f9c..3079cc63867 100644
--- a/components/index.rst
+++ b/components/index.rst
@@ -28,6 +28,7 @@ The Components
     stopwatch
     templating/index
     translation/index
+    validator/index
     yaml/index
 
 .. include:: /components/map.rst.inc
diff --git a/components/map.rst.inc b/components/map.rst.inc
index fbc1872afb8..efc477232b6 100644
--- a/components/map.rst.inc
+++ b/components/map.rst.inc
@@ -128,6 +128,10 @@
   * :doc:`/components/translation/introduction`
   * :doc:`/components/translation/usage`
 
+* :doc:`/components/validator/index`
+
+  * :doc:`/components/validator/introduction`
+
 * :doc:`/components/yaml/index`
 
   * :doc:`/components/yaml/introduction`
diff --git a/components/validator/index.rst b/components/validator/index.rst
new file mode 100644
index 00000000000..a96a760ea9e
--- /dev/null
+++ b/components/validator/index.rst
@@ -0,0 +1,7 @@
+Validator
+=========
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction
diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst
new file mode 100644
index 00000000000..255fe136146
--- /dev/null
+++ b/components/validator/introduction.rst
@@ -0,0 +1,45 @@
+.. index::
+   single: Validator
+   single: Components; Validator
+
+The Validator Component
+=======================
+
+    The Validator component provides tools to validate values following the
+    `JSR-303 Bean Validation specification`_.
+
+Installation
+------------
+
+You can install the component in 2 different ways:
+
+* :doc:`Install it via Composer </components/using_components>` (``symfony/validator`` on `Packagist`_);
+* Use the official Git repository (https://github.com/symfony/Validator).
+
+Usage
+-----
+
+The Validator component allows you to use very advanced validation rules, but
+it is also really easy to do very minor validation. For instance, if you want
+to validate a string against a specific length, the only code you need is::
+
+    use Symfony\Component\Validator\Validation;
+    use Symfony\Component\Validator\Constraints\Length;
+
+    $validator = Validation::createValidator();
+
+    $violations = $validator->validateValue('Bernhard', new Length(array('min' => 10)));
+
+    if (0 !== count($violations)) {
+        // there are errors, let's show them
+        foreach ($violations as $violation) {
+            echo $violation->getMessage().'<br>';
+        }
+    }
+
+Sections
+--------
+
+* :doc:`/components/validator/configuration`
+
+.. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303

From 609774b1fe2d5f53a62e35bbe3a141af0a81edcc Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sun, 23 Mar 2014 14:32:50 +0100
Subject: [PATCH 2/4] Added small configuration section

---
 components/validator/introduction.rst | 33 ++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst
index 255fe136146..df510fdff2a 100644
--- a/components/validator/introduction.rst
+++ b/components/validator/introduction.rst
@@ -37,9 +37,40 @@ to validate a string against a specific length, the only code you need is::
         }
     }
 
+Retrieving a Validator Instance
+-------------------------------
+
+The :class:`Symfony\\Component\\Validator\\Validator` class is the main access
+point of the Validator component. To create a new instance of this class, it
+is recomment to use the :class:`Symfony\\Component\Validator\Validation`
+class.
+
+You can get the ``Validator`` with the default configuration by calling 
+:method:`Validation::createValidator() <Symfony\\Component\\Validator\\Validation::createValidator>`::
+
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidator();
+
+However, a lot of things can be customized. To configure the ``Validator``
+class, you can use the :class:`Symfony\\Component\\Validator\\ValidatorBuilder`.
+This class can be retrieved by using the 
+:method:`Validation::createValidatorBuilder() <Symfony\\Component\\Validator\\Validation::createValidatorBuilder>`
+method::
+
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidatorBuilder()
+        // ... build a custom instance of the Validator
+        ->getValidator();
+
+What things you can configure will be documented in the following sections.
+
 Sections
 --------
 
-* :doc:`/components/validator/configuration`
+* :doc:`/components/validator/loading_resources`
+* :doc:`/components/validator/defining_metadata`
+* :doc:`/components/validator/validating_values`
 
 .. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303

From 8f9851246f7fb137321c8f7c507440fddf369501 Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Sun, 23 Mar 2014 15:38:15 +0100
Subject: [PATCH 3/4] Added article about loaders

---
 components/map.rst.inc                |   1 +
 components/validator/index.rst        |   1 +
 components/validator/introduction.rst |   4 +-
 components/validator/resources.rst    | 180 ++++++++++++++++++++++++++
 4 files changed, 184 insertions(+), 2 deletions(-)
 create mode 100644 components/validator/resources.rst

diff --git a/components/map.rst.inc b/components/map.rst.inc
index efc477232b6..6dbaef3a02c 100644
--- a/components/map.rst.inc
+++ b/components/map.rst.inc
@@ -131,6 +131,7 @@
 * :doc:`/components/validator/index`
 
   * :doc:`/components/validator/introduction`
+  * :doc:`/components/validator/resources`
 
 * :doc:`/components/yaml/index`
 
diff --git a/components/validator/index.rst b/components/validator/index.rst
index a96a760ea9e..c653e23078a 100644
--- a/components/validator/index.rst
+++ b/components/validator/index.rst
@@ -5,3 +5,4 @@ Validator
     :maxdepth: 2
 
     introduction
+    resources
diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst
index df510fdff2a..984a8097d65 100644
--- a/components/validator/introduction.rst
+++ b/components/validator/introduction.rst
@@ -69,8 +69,8 @@ What things you can configure will be documented in the following sections.
 Sections
 --------
 
-* :doc:`/components/validator/loading_resources`
-* :doc:`/components/validator/defining_metadata`
+* :doc:`/components/validator/resources`
+* :doc:`/components/validator/metadata`
 * :doc:`/components/validator/validating_values`
 
 .. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303
diff --git a/components/validator/resources.rst b/components/validator/resources.rst
new file mode 100644
index 00000000000..fc9b2acf21f
--- /dev/null
+++ b/components/validator/resources.rst
@@ -0,0 +1,180 @@
+.. index::
+    single: Validator; Loading Resources
+
+Loading Resources
+=================
+
+The Validator uses metadata to validate a value. This metadata defines how a
+class, array or any other value should be validated. When validating a class,
+each class contains its own specific metadata. When validating another value,
+the metadata to passed to the validate methods.
+
+Class metadata should be defined somewhere in a configuration file, or in the
+class itself. The ``Validator`` needs to be able to retrieve this metadata
+from the file or class. To do that, it uses a set of loaders.
+
+.. seealso::
+
+    You'll learn how to define the metadata in :doc:`metadata`.
+
+The StaticMethodLoader
+----------------------
+
+The easiest loader is the
+:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\StaticMethodLoader`.
+This loader will call a static method of the class in order to get the
+metadata for that class. The name of the method is configured using the
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::addMethodMapping`
+method of the Validator builder::
+
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidatorBuilder()
+        ->addMethodMapping('loadValidatorMetadata')
+        ->getValidator();
+
+Now, the retrieved ``Validator`` tries to find the ``loadValidatorMetadata()``
+method of the validated class to load its metadata.
+
+.. tip::
+
+    You can call this method multiple times to add multiple supported method
+    names. You can also use
+    :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addMethodMappings`
+    to set an array of supported method names.
+
+The FileLoaders
+---------------
+
+The component also provides 2 file loaders, one to load Yaml files and one to
+load XML files. Use 
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::addYamlMapping` or
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::addXmlMapping` to
+configure the locations of these files::
+
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidatorBuilder()
+        ->addYamlMapping('config/validation.yml')
+        ->getValidator();
+
+.. tip::
+
+    Just like with the method mappings, you can also use 
+    :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addYamlMappings` and
+    :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addXmlMappings`
+    to configure an array of file paths.
+
+The AnnotationLoader
+--------------------
+
+At last, the component provides an
+:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader`.
+This loader will parse the annotations of a class. Annotations are placed in
+PHPdoc comments (`/** ... */`) and start with an ``@``. For instance::
+
+    // ...
+
+    /**
+     * @Assert\NotBlank()
+     */
+    protected $name;
+
+To enable the annotation loader, call the 
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::enableAnnotationMapping`
+method. It takes an optional annotation reader instance, which defaults to
+``Doctrine\Common\Annotations\AnnotationReader``::
+
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidatorBuilder()
+        ->enableAnnotationMapping()
+        ->getValidator();
+
+To disable the annotation loader after it was enabled, call
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::disableAnnotationMapping`.
+
+.. note::
+
+    In order to use the annotation loader, you should have installed the
+    ``doctrine/annotations`` and ``doctrine/cache`` packages of Packagist.
+
+Using Multiple Loaders
+----------------------
+
+The component provides a 
+:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\LoaderChain` class to
+chain multiple loaders. This means you can configure as many loaders as you
+want at the same time.
+
+The ``ValidatorBuilder`` will already take care of this when you configure
+multiple mappings::
+
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidatorBuilder()
+        ->enableAnnotationMapping()
+        ->addMethodMapping('loadValidatorMetadata')
+        ->addXmlMapping('config/validation.xml')
+        ->getValidator();
+
+Caching
+-------
+
+Using many loaders to load metadata from different places is very easy for the
+developer, but it can easily slow down your application since each file needs
+to be parsed, validated and converted to a
+:class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` instance. To
+solve this problems, you can configure a cacher which will be used to cache
+the ``ClassMetadata`` after it was loaded.
+
+The Validator component comes with a
+:class:`Symfony\\Component\\Validator\\Mapping\\Cache\\ApcCache`
+implementation. You can easily create other cachers by creating a class which
+implements :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface`.
+
+.. note::
+
+    The loader already use a singleton load mechanism. That means that they
+    will only load and parse a file once and put that in a property, which
+    will be used on the next time. However, the Validator still needs to
+    merge all metadata of one class from every loader when it is requested.
+
+To set a cacher, call the
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMetadataCache` of
+the Validator builder::
+
+    use Symfony\Component\Validator\Validation;
+    use Symfony\Component\Validator\Mapping\Cache\ApcCache;
+
+    $validator = Validation::createValidatorBuilder()
+        // ... add loaders
+        ->setMetadataCache(new ApcCache('some_apc_prefix'));
+        ->getValidator();
+
+Using a Custom MetadataFactory
+------------------------------
+
+All loaders and the cacher are passed to an instance of
+:class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadataFactory`. This
+class is responsible for creating a ``ClassMetadata`` instance from all the
+configured resources.
+
+You can also use a custom metadata factory implementation by creating a class
+which implements
+:class:`Symfony\\Component\\Validator\\MetadataFactoryInterface`. You can set
+this custom implementation using 
+:method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMetadataFactory`::
+
+    use Acme\Validation\CustomMetadataFactory;
+    use Symfony\Component\Validator\Validation;
+
+    $validator = Validation::createValidatorBuilder()
+        ->setMetadataFactory(new CustomMetadataFactory(...));
+        ->getValidator();
+
+.. caution::
+
+    Since you are using a custom metadata factory, you can't configure loaders
+    and cachers using the helper methods anymore. You now have to inject them
+    into your custom metadata factory yourself.

From 0bd220dae72fc465efd7857432ee81fe367679a8 Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Mon, 24 Mar 2014 20:06:40 +0100
Subject: [PATCH 4/4] Applied comments by @cordoval

---
 components/validator/introduction.rst | 17 +++++++-------
 components/validator/resources.rst    | 32 ++++++++++++++-------------
 2 files changed, 26 insertions(+), 23 deletions(-)

diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst
index 984a8097d65..d1cfffaf3eb 100644
--- a/components/validator/introduction.rst
+++ b/components/validator/introduction.rst
@@ -20,8 +20,8 @@ Usage
 -----
 
 The Validator component allows you to use very advanced validation rules, but
-it is also really easy to do very minor validation. For instance, if you want
-to validate a string against a specific length, the only code you need is::
+it is also really easy to do easy validation tasks. For instance, if you want
+to validate a string is at least 10 character long, the only code you need is::
 
     use Symfony\Component\Validator\Validation;
     use Symfony\Component\Validator\Constraints\Length;
@@ -31,7 +31,7 @@ to validate a string against a specific length, the only code you need is::
     $violations = $validator->validateValue('Bernhard', new Length(array('min' => 10)));
 
     if (0 !== count($violations)) {
-        // there are errors, let's show them
+        // there are errors, now you can show them
         foreach ($violations as $violation) {
             echo $violation->getMessage().'<br>';
         }
@@ -42,19 +42,20 @@ Retrieving a Validator Instance
 
 The :class:`Symfony\\Component\\Validator\\Validator` class is the main access
 point of the Validator component. To create a new instance of this class, it
-is recomment to use the :class:`Symfony\\Component\Validator\Validation`
+is recommend to use the :class:`Symfony\\Component\Validator\Validation`
 class.
 
-You can get the ``Validator`` with the default configuration by calling 
+You can get a very basic ``Validator`` by calling 
 :method:`Validation::createValidator() <Symfony\\Component\\Validator\\Validation::createValidator>`::
 
     use Symfony\Component\Validator\Validation;
 
     $validator = Validation::createValidator();
 
-However, a lot of things can be customized. To configure the ``Validator``
-class, you can use the :class:`Symfony\\Component\\Validator\\ValidatorBuilder`.
-This class can be retrieved by using the 
+The created validator can be used to validate strings, array, numbers, but it
+can't validate classes. To be able to do that, you have to configure the ``Validator``
+class. To do that, you can use the :class:`Symfony\\Component\\Validator\\ValidatorBuilder`.
+This class can be retrieved by using the
 :method:`Validation::createValidatorBuilder() <Symfony\\Component\\Validator\\Validation::createValidatorBuilder>`
 method::
 
diff --git a/components/validator/resources.rst b/components/validator/resources.rst
index fc9b2acf21f..c2975d14e55 100644
--- a/components/validator/resources.rst
+++ b/components/validator/resources.rst
@@ -7,7 +7,7 @@ Loading Resources
 The Validator uses metadata to validate a value. This metadata defines how a
 class, array or any other value should be validated. When validating a class,
 each class contains its own specific metadata. When validating another value,
-the metadata to passed to the validate methods.
+the metadata must be passed to the validate methods.
 
 Class metadata should be defined somewhere in a configuration file, or in the
 class itself. The ``Validator`` needs to be able to retrieve this metadata
@@ -20,7 +20,7 @@ from the file or class. To do that, it uses a set of loaders.
 The StaticMethodLoader
 ----------------------
 
-The easiest loader is the
+The most basic loader is the
 :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\StaticMethodLoader`.
 This loader will call a static method of the class in order to get the
 metadata for that class. The name of the method is configured using the
@@ -34,7 +34,7 @@ method of the Validator builder::
         ->getValidator();
 
 Now, the retrieved ``Validator`` tries to find the ``loadValidatorMetadata()``
-method of the validated class to load its metadata.
+method of the class to validate to load its metadata.
 
 .. tip::
 
@@ -70,8 +70,9 @@ The AnnotationLoader
 
 At last, the component provides an
 :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader`.
-This loader will parse the annotations of a class. Annotations are placed in
-PHPdoc comments (`/** ... */`) and start with an ``@``. For instance::
+This loader uses an annotation reader to parse the annotations of a class.
+Annotations are placed in doc block comments (`/** ... */`) and start with an
+``@``. For instance::
 
     // ...
 
@@ -97,7 +98,7 @@ To disable the annotation loader after it was enabled, call
 .. note::
 
     In order to use the annotation loader, you should have installed the
-    ``doctrine/annotations`` and ``doctrine/cache`` packages of Packagist.
+    ``doctrine/annotations`` and ``doctrine/cache`` packages from Packagist.
 
 Using Multiple Loaders
 ----------------------
@@ -121,9 +122,9 @@ multiple mappings::
 Caching
 -------
 
-Using many loaders to load metadata from different places is very easy for the
-developer, but it can easily slow down your application since each file needs
-to be parsed, validated and converted to a
+Using many loaders to load metadata from different places is very easy when
+creating the metadata, but it can easily slow down your application since each
+file needs to be parsed, validated and converted to a
 :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` instance. To
 solve this problems, you can configure a cacher which will be used to cache
 the ``ClassMetadata`` after it was loaded.
@@ -135,10 +136,11 @@ implements :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface
 
 .. note::
 
-    The loader already use a singleton load mechanism. That means that they
-    will only load and parse a file once and put that in a property, which
-    will be used on the next time. However, the Validator still needs to
-    merge all metadata of one class from every loader when it is requested.
+    The loaders already use a singleton load mechanism. That means that the
+    loaders will only load and parse a file once and put that in a property,
+    which will then be used the next time it is asked for metadata. However,
+    the Validator still needs to merge all metadata of one class from every
+    loader when it is requested.
 
 To set a cacher, call the
 :method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMetadataCache` of
@@ -176,5 +178,5 @@ this custom implementation using
 .. caution::
 
     Since you are using a custom metadata factory, you can't configure loaders
-    and cachers using the helper methods anymore. You now have to inject them
-    into your custom metadata factory yourself.
+    and cachers using the ``add*Mapping()`` methods anymore. You now have to
+    inject them into your custom metadata factory yourself.

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/3710.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/3710.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/3710.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/symfony/symfony-docs/pull/3710.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>