From 7cedc2c5ed21353c697f4f97e31470cb940bbd42 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 22 Mar 2014 20:53:57 +0100 Subject: [PATCH 01/24] 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 38bf2e07748..42f19b5564e 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -135,6 +135,10 @@ * :doc:`/components/translation/usage` * :doc:`/components/translation/custom_formats` +* :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 ` (``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().'
'; + } + } + +Sections +-------- + +* :doc:`/components/validator/configuration` + +.. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303 From 677738f2177d8ab06a60d4d91f06f585602492ec Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 23 Mar 2014 14:32:50 +0100 Subject: [PATCH 02/24] 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() `:: + + 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() ` +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 7947c389211f9bfc7f3ddde4a1cff26a4f83a1a9 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sun, 23 Mar 2014 15:38:15 +0100 Subject: [PATCH 03/24] 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 42f19b5564e..2d2ba2eec9c 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -138,6 +138,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 1b5823233080625f70ed3f5f64cebcdac5ca754f Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 24 Mar 2014 20:06:40 +0100 Subject: [PATCH 04/24] 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().'
'; } @@ -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() `:: 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() ` 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. From 1ad4e12685398d549e3128b85507bc39bbbd3d06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 13:39:20 +0200 Subject: [PATCH 05/24] @ricardclau review --- components/validator/introduction.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index d1cfffaf3eb..717efce6713 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -21,7 +21,7 @@ Usage The Validator component allows you to use very advanced validation rules, but 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:: +to validate that 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; @@ -42,7 +42,7 @@ 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 recommend to use the :class:`Symfony\\Component\Validator\Validation` +is recommended to use the :class:`Symfony\\Component\Validator\Validation` class. You can get a very basic ``Validator`` by calling @@ -52,8 +52,8 @@ You can get a very basic ``Validator`` by calling $validator = Validation::createValidator(); -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`` +The created validator can be used to validate strings, arrays, numbers, but it +can't validate classes. In order to achieve 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() ` From c63acc294b4841cd6db2299a45e98f0504b80ef5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:11:23 +0200 Subject: [PATCH 06/24] fixed backslash on namespaces --- components/validator/introduction.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 717efce6713..0b45461dd25 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -6,7 +6,11 @@ The Validator Component ======================= The Validator component provides tools to validate values following the - `JSR-303 Bean Validation specification`_. + `JSR-303 Bean Validation specification`_. With the component, this is done in two parts: + * ``Contraints``: a constraint describes a rule that need to be validated + * ``Validators``: a list of classes that implement the validation logic for common usages + + Installation ------------ @@ -16,6 +20,8 @@ You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/validator`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/Validator). +Then, require the vendor/autoload.php file to enable the autoloading mechanism provided by Composer. Otherwise, your application won't be able to find the classes of this Symfony component. + Usage ----- @@ -42,7 +48,7 @@ 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 recommended to use the :class:`Symfony\\Component\Validator\Validation` +is recommended to use the :class:`Symfony\\Component\\Validator\\Validation` class. You can get a very basic ``Validator`` by calling From a5bac78d34145e3d813ce087675f3b50052f53b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:15:36 +0200 Subject: [PATCH 07/24] added Packagist link --- components/validator/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 0b45461dd25..9135a5d163f 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -77,7 +77,7 @@ Sections -------- * :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 +.. _Packagist: https://packagist.org/packages/symfony/validator \ No newline at end of file From b6a6ab9e80a9ec7f04c4f54d84f80351f72ebd16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:25:24 +0200 Subject: [PATCH 08/24] added new sections --- components/validator/builtin_validators.rst | 5 +++++ components/validator/internationalization.rst | 5 +++++ components/validator/introduction.rst | 5 ++++- components/validator/validation_groups.rst | 5 +++++ 4 files changed, 19 insertions(+), 1 deletion(-) create mode 100755 components/validator/builtin_validators.rst create mode 100755 components/validator/internationalization.rst create mode 100755 components/validator/validation_groups.rst diff --git a/components/validator/builtin_validators.rst b/components/validator/builtin_validators.rst new file mode 100755 index 00000000000..935a48022d8 --- /dev/null +++ b/components/validator/builtin_validators.rst @@ -0,0 +1,5 @@ +.. index:: + single: Validator; Built In validators + +Built In validators +=================== \ No newline at end of file diff --git a/components/validator/internationalization.rst b/components/validator/internationalization.rst new file mode 100755 index 00000000000..bda6fb51756 --- /dev/null +++ b/components/validator/internationalization.rst @@ -0,0 +1,5 @@ +.. index:: + single: Validator; Internationalization + +Internationalization +==================== \ No newline at end of file diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 9135a5d163f..ddc14d16ecd 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -77,7 +77,10 @@ Sections -------- * :doc:`/components/validator/resources` -* :doc:`/components/validator/validating_values` +* :doc:`/components/validator/builtin_validators` +* :doc:`/components/validator/validation_groups` +* :doc:`/components/validator/internationalization` +* :doc:`/components/validator/custom_validation` .. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303 .. _Packagist: https://packagist.org/packages/symfony/validator \ No newline at end of file diff --git a/components/validator/validation_groups.rst b/components/validator/validation_groups.rst new file mode 100755 index 00000000000..b993139a0be --- /dev/null +++ b/components/validator/validation_groups.rst @@ -0,0 +1,5 @@ +.. index:: + single: Validator; Validation groups + +Validation groups +================= \ No newline at end of file From a1fc7bfa8b20761589c29483fc5e7784a06d4fd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:30:15 +0200 Subject: [PATCH 09/24] built the toc tree --- components/validator/index.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/components/validator/index.rst b/components/validator/index.rst index c653e23078a..1ada67c67f2 100644 --- a/components/validator/index.rst +++ b/components/validator/index.rst @@ -6,3 +6,7 @@ Validator introduction resources + builtin_validators + validation_groups + custom_validation + internationalization From 3f0790b9b4748b3571d758eaea808904253c53b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:33:39 +0200 Subject: [PATCH 10/24] added custom validation section --- components/validator/custom_validation.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100755 components/validator/custom_validation.rst diff --git a/components/validator/custom_validation.rst b/components/validator/custom_validation.rst new file mode 100755 index 00000000000..c6d83f6d39e --- /dev/null +++ b/components/validator/custom_validation.rst @@ -0,0 +1,5 @@ +.. index:: + single: Validator; Custom validation + +Custom validation +================= \ No newline at end of file From 5e99a61b1e948e8f74344291766f92cc8a74a274 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:37:57 +0200 Subject: [PATCH 11/24] re added metadata section --- components/validator/metadata.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100755 components/validator/metadata.rst diff --git a/components/validator/metadata.rst b/components/validator/metadata.rst new file mode 100755 index 00000000000..db9fd203939 --- /dev/null +++ b/components/validator/metadata.rst @@ -0,0 +1,5 @@ +.. index:: + single: Validator; Metadata + +Metadata +======== \ No newline at end of file From 009c2bf7865758f4f78b0e4adde513666a81dffe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:42:31 +0200 Subject: [PATCH 12/24] updated toc tree --- components/validator/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/components/validator/index.rst b/components/validator/index.rst index 1ada67c67f2..a18caeaeb2b 100644 --- a/components/validator/index.rst +++ b/components/validator/index.rst @@ -6,6 +6,7 @@ Validator introduction resources + metadata builtin_validators validation_groups custom_validation From efd5b77e5531885c8b8b9d589a273097a6475708 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Sat, 29 Aug 2015 14:54:29 +0200 Subject: [PATCH 13/24] add example on how to use the static method loader --- components/validator/builtin_validators.rst | 5 ++++- components/validator/resources.rst | 20 +++++++++++++++++++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/components/validator/builtin_validators.rst b/components/validator/builtin_validators.rst index 935a48022d8..92bb0949c50 100755 --- a/components/validator/builtin_validators.rst +++ b/components/validator/builtin_validators.rst @@ -2,4 +2,7 @@ single: Validator; Built In validators Built In validators -=================== \ No newline at end of file +=================== + +For each validation rule, the component ships a Constraint class and its associated Validator class. +The Constraint object describes the rule to check and the Validator implementation runs the validation logic. \ No newline at end of file diff --git a/components/validator/resources.rst b/components/validator/resources.rst index c2975d14e55..9bf88e4ba79 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -34,7 +34,25 @@ method of the Validator builder:: ->getValidator(); Now, the retrieved ``Validator`` tries to find the ``loadValidatorMetadata()`` -method of the class to validate to load its metadata. +method of the class to validate to load its metadata:: + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints\NotBlank; + use Symfony\Component\Validator\Constraints\Length; + + class User + { + protected $name; + + public static function loadValidatorMatadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('name', new NotBlank()); + $metadata->addPropertyConstraint('name', new Length(array( + 'min' => 5, + 'max' => 20, + ))); + } + } .. tip:: From 4894b25baf5bd06135ac60e7566b07a46d98f0cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Mon, 31 Aug 2015 20:01:36 +0200 Subject: [PATCH 14/24] WouterJ comments --- components/validator/builtin_validators.rst | 6 ++-- components/validator/custom_validation.rst | 6 ++-- components/validator/introduction.rst | 10 +++--- components/validator/resources.rst | 34 ++++++++++++--------- components/validator/validation_groups.rst | 6 ++-- 5 files changed, 33 insertions(+), 29 deletions(-) diff --git a/components/validator/builtin_validators.rst b/components/validator/builtin_validators.rst index 92bb0949c50..e75bcd9b1c5 100755 --- a/components/validator/builtin_validators.rst +++ b/components/validator/builtin_validators.rst @@ -1,8 +1,8 @@ .. index:: - single: Validator; Built In validators + single: Validator; Built In Validators -Built In validators +Built In Validators =================== For each validation rule, the component ships a Constraint class and its associated Validator class. -The Constraint object describes the rule to check and the Validator implementation runs the validation logic. \ No newline at end of file +The Constraint object describes the rule to check and the Validator implementation runs the validation logic. diff --git a/components/validator/custom_validation.rst b/components/validator/custom_validation.rst index c6d83f6d39e..af561df589f 100755 --- a/components/validator/custom_validation.rst +++ b/components/validator/custom_validation.rst @@ -1,5 +1,5 @@ .. index:: - single: Validator; Custom validation + single: Validator; Custom Validation -Custom validation -================= \ No newline at end of file +Custom Validation +================= diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index ddc14d16ecd..34c064820cf 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -10,8 +10,6 @@ The Validator Component * ``Contraints``: a constraint describes a rule that need to be validated * ``Validators``: a list of classes that implement the validation logic for common usages - - Installation ------------ @@ -20,7 +18,7 @@ You can install the component in 2 different ways: * :doc:`Install it via Composer ` (``symfony/validator`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/Validator). -Then, require the vendor/autoload.php file to enable the autoloading mechanism provided by Composer. Otherwise, your application won't be able to find the classes of this Symfony component. +.. include:: /components/require_autoload.rst.inc Usage ----- @@ -51,7 +49,7 @@ point of the Validator component. To create a new instance of this class, it is recommended to use the :class:`Symfony\\Component\\Validator\\Validation` class. -You can get a very basic ``Validator`` by calling +You can get a very basic ``Validator`` by calling :method:`Validation::createValidator() `:: use Symfony\Component\Validator\Validation; @@ -71,7 +69,7 @@ method:: // ... build a custom instance of the Validator ->getValidator(); -What things you can configure will be documented in the following sections. +In the next sections, you'll learn about all things you can configure in the Validator. Sections -------- @@ -83,4 +81,4 @@ Sections * :doc:`/components/validator/custom_validation` .. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303 -.. _Packagist: https://packagist.org/packages/symfony/validator \ No newline at end of file +.. _Packagist: https://packagist.org/packages/symfony/validator diff --git a/components/validator/resources.rst b/components/validator/resources.rst index 9bf88e4ba79..a9e5db5339d 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -37,8 +37,7 @@ Now, the retrieved ``Validator`` tries to find the ``loadValidatorMetadata()`` method of the class to validate to load its metadata:: use Symfony\Component\Validator\Mapping\ClassMetadata; - use Symfony\Component\Validator\Constraints\NotBlank; - use Symfony\Component\Validator\Constraints\Length; + use Symfony\Component\Validator\Constraints as Assert; class User { @@ -46,8 +45,8 @@ method of the class to validate to load its metadata:: public static function loadValidatorMatadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('name', new NotBlank()); - $metadata->addPropertyConstraint('name', new Length(array( + $metadata->addPropertyConstraint('name', new Assert\NotBlank()); + $metadata->addPropertyConstraint('name', new Asert\Length(array( 'min' => 5, 'max' => 20, ))); @@ -65,7 +64,7 @@ The FileLoaders --------------- The component also provides 2 file loaders, one to load Yaml files and one to -load XML files. Use +load XML files. Use :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addYamlMapping` or :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addXmlMapping` to configure the locations of these files:: @@ -76,9 +75,14 @@ configure the locations of these files:: ->addYamlMapping('config/validation.yml') ->getValidator(); +.. note:: + + If you want to load YAML mapping files then you will also need to install + :doc:`the Yaml component `. + .. tip:: - Just like with the method mappings, you can also use + 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. @@ -89,9 +93,9 @@ The AnnotationLoader At last, the component provides an :class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader`. This loader uses an annotation reader to parse the annotations of a class. -Annotations are placed in doc block comments (`/** ... */`) and start with an +Annotations are placed in doc block comments (``/** ... */``) and start with an ``@``. For instance:: - + use Symfony\Component\Validator\Constraints as Assert; // ... /** @@ -99,7 +103,7 @@ Annotations are placed in doc block comments (`/** ... */`) and start with an */ protected $name; -To enable the annotation loader, call the +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``:: @@ -116,12 +120,12 @@ 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 from Packagist. + ``doctrine/annotations`` and ``doctrine/cache`` packages from _Packagist. Using Multiple Loaders ---------------------- -The component provides a +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. @@ -144,10 +148,10 @@ 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 +solve this problem, you can configure a cacher which will be used to cache the ``ClassMetadata`` after it was loaded. -The Validator component comes with a +The Validator component comes with an :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`. @@ -183,7 +187,7 @@ 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 +this custom implementation using :method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMetadataFactory`:: use Acme\Validation\CustomMetadataFactory; @@ -198,3 +202,5 @@ this custom implementation using Since you are using a custom metadata factory, you can't configure loaders and cachers using the ``add*Mapping()`` methods anymore. You now have to inject them into your custom metadata factory yourself. + +.. _Packagist: https://packagist.org diff --git a/components/validator/validation_groups.rst b/components/validator/validation_groups.rst index b993139a0be..68a6b2711f5 100755 --- a/components/validator/validation_groups.rst +++ b/components/validator/validation_groups.rst @@ -1,5 +1,5 @@ .. index:: - single: Validator; Validation groups + single: Validator; Validation Groups -Validation groups -================= \ No newline at end of file +Validation Groups +================= From 5899d236c9f20bb2468f8246fe5cd7367f97be36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Andrieu?= Date: Mon, 31 Aug 2015 20:30:25 +0200 Subject: [PATCH 15/24] started to migrate metadata part from book to component docs --- components/validator/metadata.rst | 81 +++++++++++++++++++++++++++++- components/validator/resources.rst | 1 + 2 files changed, 81 insertions(+), 1 deletion(-) diff --git a/components/validator/metadata.rst b/components/validator/metadata.rst index db9fd203939..9ef2e76e2f4 100755 --- a/components/validator/metadata.rst +++ b/components/validator/metadata.rst @@ -2,4 +2,83 @@ single: Validator; Metadata Metadata -======== \ No newline at end of file +======== + +The :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` class represents and manages all the configured constraints on a given class. + +Properties +---------- + +Validating class properties is the most basic validation technique. Validation component +allows you to validate private, protected or public properties. The next +listing shows you how to configure the ``$firstName`` property of an ``Author`` +class to have at least 3 characters:: + + // ... + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + private $firstName; + + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('firstName', new Assert\NotBlank()); + $metadata->addPropertyConstraint( + 'firstName', + new Assert\Length(array("min" => 3)) + ); + } + } + +Getters +------- + +Constraints can also be applied to the return value of a method. Symfony +allows you to add a constraint to any public method whose name starts with +"get" or "is". In this guide, both of these types of methods are referred +to as "getters". + +The benefit of this technique is that it allows you to validate your object +dynamically. For example, suppose you want to make sure that a password field +doesn't match the first name of the user (for security reasons). You can +do this by creating an ``isPasswordLegal`` method, and then asserting that +this method must return ``true``:: + + // ... + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Author + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addGetterConstraint('passwordLegal', new Assert\True(array( + 'message' => 'The password cannot match your first name', + ))); + } + } + +Now, create the ``isPasswordLegal()`` method and include the logic you need:: + + public function isPasswordLegal() + { + return $this->firstName !== $this->password; + } + +.. note:: + + The keen-eyed among you will have noticed that the prefix of the getter + ("get" or "is") is omitted in the mapping. This allows you to move the + constraint to a property with the same name later (or vice versa) without + changing your validation logic. + +Classes +------- + +Some constraints apply to the entire class being validated. For example, +the :doc:`Callback ` constraint is a generic +constraint that's applied to the class itself. When that class is validated, +methods specified by that constraint are simply executed so that each can +provide more custom validation. diff --git a/components/validator/resources.rst b/components/validator/resources.rst index a9e5db5339d..2ee1a212778 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -95,6 +95,7 @@ At last, the component provides an 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:: + use Symfony\Component\Validator\Constraints as Assert; // ... From 72f11a3276da317b8bc7c5972ba691a36c2d68ac Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 12:52:15 +0200 Subject: [PATCH 16/24] Finished the first version of the Validator documentation --- components/validator/builtin_validators.rst | 8 --- components/validator/custom_validation.rst | 5 -- components/validator/index.rst | 4 -- components/validator/internationalization.rst | 5 -- components/validator/introduction.rst | 44 ++++++-------- components/validator/metadata.rst | 51 +++++++--------- components/validator/resources.rst | 60 +++++++++---------- components/validator/validation_groups.rst | 5 -- 8 files changed, 67 insertions(+), 115 deletions(-) delete mode 100755 components/validator/builtin_validators.rst delete mode 100755 components/validator/custom_validation.rst delete mode 100755 components/validator/internationalization.rst delete mode 100755 components/validator/validation_groups.rst diff --git a/components/validator/builtin_validators.rst b/components/validator/builtin_validators.rst deleted file mode 100755 index e75bcd9b1c5..00000000000 --- a/components/validator/builtin_validators.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. index:: - single: Validator; Built In Validators - -Built In Validators -=================== - -For each validation rule, the component ships a Constraint class and its associated Validator class. -The Constraint object describes the rule to check and the Validator implementation runs the validation logic. diff --git a/components/validator/custom_validation.rst b/components/validator/custom_validation.rst deleted file mode 100755 index af561df589f..00000000000 --- a/components/validator/custom_validation.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. index:: - single: Validator; Custom Validation - -Custom Validation -================= diff --git a/components/validator/index.rst b/components/validator/index.rst index a18caeaeb2b..22cabeeaae6 100644 --- a/components/validator/index.rst +++ b/components/validator/index.rst @@ -7,7 +7,3 @@ Validator introduction resources metadata - builtin_validators - validation_groups - custom_validation - internationalization diff --git a/components/validator/internationalization.rst b/components/validator/internationalization.rst deleted file mode 100755 index bda6fb51756..00000000000 --- a/components/validator/internationalization.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. index:: - single: Validator; Internationalization - -Internationalization -==================== \ No newline at end of file diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 34c064820cf..3420787741e 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -6,9 +6,7 @@ The Validator Component ======================= The Validator component provides tools to validate values following the - `JSR-303 Bean Validation specification`_. With the component, this is done in two parts: - * ``Contraints``: a constraint describes a rule that need to be validated - * ``Validators``: a list of classes that implement the validation logic for common usages + `JSR-303 Bean Validation specification`_. Installation ------------ @@ -23,15 +21,18 @@ You can install the component in 2 different ways: Usage ----- -The Validator component allows you to use very advanced validation rules, but -it is also really easy to do easy validation tasks. For instance, if you want -to validate that a string is at least 10 character long, the only code you need is:: +The Validator component behavior is based on two concepts: + +* Contraints, which define the rules to be validated; +* Validators, which are the classees that contain the actual validation logic. + +The following example shows how to validate that a string is at least 10 +characters long:: 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)) { @@ -45,23 +46,17 @@ 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 recommended to use the :class:`Symfony\\Component\\Validator\\Validation` -class. - -You can get a very basic ``Validator`` by calling -:method:`Validation::createValidator() `:: +point of the Validator component. To create a new instance of this class, it's +recommended to use the :class:`Symfony\\Component\\Validator\\Validation` class:: use Symfony\Component\Validator\Validation; $validator = Validation::createValidator(); -The created validator can be used to validate strings, arrays, numbers, but it -can't validate classes. In order to achieve 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() ` -method:: +This ``$validator`` object can validate simple variables such as strings, numbers +and arrays, but it can't validate objects. To do so, use the +:class:`Symfony\\Component\\Validator\\ValidatorBuilder` class to configure the +``Validator`` class:: use Symfony\Component\Validator\Validation; @@ -69,16 +64,11 @@ method:: // ... build a custom instance of the Validator ->getValidator(); -In the next sections, you'll learn about all things you can configure in the Validator. - -Sections --------- +In the next sections, you'll learn about all the validator features that you +can configure: * :doc:`/components/validator/resources` -* :doc:`/components/validator/builtin_validators` -* :doc:`/components/validator/validation_groups` -* :doc:`/components/validator/internationalization` -* :doc:`/components/validator/custom_validation` +* :doc:`/components/validator/metadata` .. _`JSR-303 Bean Validation specification`: http://jcp.org/en/jsr/detail?id=303 .. _Packagist: https://packagist.org/packages/symfony/validator diff --git a/components/validator/metadata.rst b/components/validator/metadata.rst index 9ef2e76e2f4..335ed4fe481 100755 --- a/components/validator/metadata.rst +++ b/components/validator/metadata.rst @@ -4,15 +4,15 @@ Metadata ======== -The :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` class represents and manages all the configured constraints on a given class. +The :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` class +represents and manages all the configured constraints on a given class. Properties ---------- -Validating class properties is the most basic validation technique. Validation component -allows you to validate private, protected or public properties. The next -listing shows you how to configure the ``$firstName`` property of an ``Author`` -class to have at least 3 characters:: +The Validator component can validate public, protected or private properties. +The following example shows how to validate that the ``$firstName`` property of +the ``Author`` class has at least 3 characters:: // ... use Symfony\Component\Validator\Mapping\ClassMetadata; @@ -35,16 +35,20 @@ class to have at least 3 characters:: Getters ------- -Constraints can also be applied to the return value of a method. Symfony -allows you to add a constraint to any public method whose name starts with -"get" or "is". In this guide, both of these types of methods are referred -to as "getters". +Constraints can also be applied to the value returned by any public *getter* +method, which are the methods whose names start with ``get`` or ``is``. This +feature allows to validate your objects dynamically. -The benefit of this technique is that it allows you to validate your object -dynamically. For example, suppose you want to make sure that a password field -doesn't match the first name of the user (for security reasons). You can -do this by creating an ``isPasswordLegal`` method, and then asserting that -this method must return ``true``:: +Suppose that, for security reasons, you want to validate that a password field +doesn't match the first name of the user. First, create a public method called +``isPasswordSafe`` to define this custom validation logic:: + + public function isPasswordSafe() + { + return $this->firstName !== $this->password; + } + +Then, add the Validator component configuration to the class:: // ... use Symfony\Component\Validator\Mapping\ClassMetadata; @@ -54,31 +58,22 @@ this method must return ``true``:: { public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addGetterConstraint('passwordLegal', new Assert\True(array( + $metadata->addGetterConstraint('passwordSafe', new Assert\True(array( 'message' => 'The password cannot match your first name', ))); } } -Now, create the ``isPasswordLegal()`` method and include the logic you need:: - - public function isPasswordLegal() - { - return $this->firstName !== $this->password; - } - .. note:: The keen-eyed among you will have noticed that the prefix of the getter - ("get" or "is") is omitted in the mapping. This allows you to move the + (``get`` or ``is``) is omitted in the mapping. This allows you to move the constraint to a property with the same name later (or vice versa) without changing your validation logic. Classes ------- -Some constraints apply to the entire class being validated. For example, -the :doc:`Callback ` constraint is a generic -constraint that's applied to the class itself. When that class is validated, -methods specified by that constraint are simply executed so that each can -provide more custom validation. +Some constraints allow to validate the entire object. For example, the +:doc:`Callback ` constraint is a generic +constraint that's applied to the class itself. diff --git a/components/validator/resources.rst b/components/validator/resources.rst index 2ee1a212778..2c19734c1c9 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -4,14 +4,13 @@ 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 must be passed to the validate methods. +The Validator component uses metadata to validate a value. This metadata defines +how a class, array or any other value should be validated. When validating a +class, the metadata is defined by the class itself. When validating simple values, +the metadata must be passed to the validation 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. +Class metadata can be defined in a configuration file or in the class itself. +The Validator component retrieves that metadata using a set of loaders. .. seealso:: @@ -22,10 +21,10 @@ The StaticMethodLoader 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 +This loader gets the metadata by calling a static method of the class. The name +of the method is configured using the :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addMethodMapping` -method of the Validator builder:: +method of the validator builder:: use Symfony\Component\Validator\Validation; @@ -33,8 +32,8 @@ method of the Validator builder:: ->addMethodMapping('loadValidatorMetadata') ->getValidator(); -Now, the retrieved ``Validator`` tries to find the ``loadValidatorMetadata()`` -method of the class to validate to load its metadata:: +In this example, the validation metadata is retrieved executing the +``loadValidatorMetadata()`` method of the class:: use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; @@ -55,15 +54,14 @@ method of the class to validate 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` + You can call this method multiple times to add several 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 +The component also provides two 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 @@ -91,10 +89,9 @@ The AnnotationLoader -------------------- At last, the component provides an -:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader`. -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:: +:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader` to get +the metadata from the annotations of the class. Annotations are defined as ``@`` +prefixed classes included in doc block comments (``/** ... */``). For example:: use Symfony\Component\Validator\Constraints as Assert; // ... @@ -128,8 +125,7 @@ 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. +execute several loaders sequentially in the same order they were defined: The ``ValidatorBuilder`` will already take care of this when you configure multiple mappings:: @@ -145,12 +141,10 @@ multiple mappings:: Caching ------- -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 problem, you can configure a cacher which will be used to cache -the ``ClassMetadata`` after it was loaded. +Using many loaders to load metadata from different places is convenient, but it +can slow down your application because each file needs to be parsed, validated +and converted to a :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` +instance. To solve this problem, you can cache the ``ClassMetadata`` information. The Validator component comes with an :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\ApcCache` @@ -165,9 +159,9 @@ implements :class:`Symfony\\Component\\Validator\\Mapping\\Cache\\CacheInterface 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:: +Enable the cache calling the +:method:`Symfony\\Component\\Validator\\ValidatorBuilder::setMetadataCache` +method of the Validator builder:: use Symfony\Component\Validator\Validation; use Symfony\Component\Validator\Mapping\Cache\ApcCache; @@ -180,7 +174,7 @@ the Validator builder:: Using a Custom MetadataFactory ------------------------------ -All loaders and the cacher are passed to an instance of +All the loaders and the cache 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. @@ -201,7 +195,7 @@ this custom implementation using .. caution:: Since you are using a custom metadata factory, you can't configure loaders - and cachers using the ``add*Mapping()`` methods anymore. You now have to + and caches using the ``add*Mapping()`` methods anymore. You now have to inject them into your custom metadata factory yourself. .. _Packagist: https://packagist.org diff --git a/components/validator/validation_groups.rst b/components/validator/validation_groups.rst deleted file mode 100755 index 68a6b2711f5..00000000000 --- a/components/validator/validation_groups.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. index:: - single: Validator; Validation Groups - -Validation Groups -================= From 7f24bcc86b75f92e76a1fd715f65e12b5f6e7282 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 18:44:57 +0200 Subject: [PATCH 17/24] Fixed a typo --- components/validator/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 3420787741e..56dee16ed1d 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -24,7 +24,7 @@ Usage The Validator component behavior is based on two concepts: * Contraints, which define the rules to be validated; -* Validators, which are the classees that contain the actual validation logic. +* Validators, which are the classes that contain the actual validation logic. The following example shows how to validate that a string is at least 10 characters long:: From d7e0b4b0c6563218033ed8c29f49571d4b57934b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 20 Jun 2016 12:35:58 +0200 Subject: [PATCH 18/24] Updated the code of the example --- components/validator/introduction.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 56dee16ed1d..93a1d486a74 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -31,9 +31,13 @@ characters long:: use Symfony\Component\Validator\Validation; use Symfony\Component\Validator\Constraints\Length; + use Symfony\Component\Validator\Constraints\NotBlank; $validator = Validation::createValidator(); - $violations = $validator->validateValue('Bernhard', new Length(array('min' => 10))); + $violations = $validator->validate('Bernhard', array( + new Length(array('min' => 10)), + new NotBlank() + )); if (0 !== count($violations)) { // there are errors, now you can show them From bfc59d8f1a6e3d18b9449f872dbb33999aedd9c0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 4 Jul 2016 13:10:35 +0200 Subject: [PATCH 19/24] Fixed typos --- components/validator/introduction.rst | 2 +- components/validator/resources.rst | 15 +++++++++------ 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index 93a1d486a74..c115daff522 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -11,7 +11,7 @@ The Validator Component Installation ------------ -You can install the component in 2 different ways: +You can install the component in two different ways: * :doc:`Install it via Composer ` (``symfony/validator`` on `Packagist`_); * Use the official Git repository (https://github.com/symfony/Validator). diff --git a/components/validator/resources.rst b/components/validator/resources.rst index 2c19734c1c9..40a31ebe58c 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -96,10 +96,13 @@ prefixed classes included in doc block comments (``/** ... */``). For example:: use Symfony\Component\Validator\Constraints as Assert; // ... - /** - * @Assert\NotBlank() - */ - protected $name; + class User + { + /** + * @Assert\NotBlank() + */ + protected $name; + } To enable the annotation loader, call the :method:`Symfony\\Component\\Validator\\ValidatorBuilder::enableAnnotationMapping` @@ -118,7 +121,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 from _Packagist. + ``doctrine/annotations`` and ``doctrine/cache`` packages from `Packagist`_. Using Multiple Loaders ---------------------- @@ -198,4 +201,4 @@ this custom implementation using and caches using the ``add*Mapping()`` methods anymore. You now have to inject them into your custom metadata factory yourself. -.. _Packagist: https://packagist.org +.. _`Packagist`: https://packagist.org From e2a5c6f84be3e41ad791d2c2544a26460c4bd837 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 4 Jul 2016 13:11:22 +0200 Subject: [PATCH 20/24] Added a missing file to the file map --- components/map.rst.inc | 1 + 1 file changed, 1 insertion(+) diff --git a/components/map.rst.inc b/components/map.rst.inc index 2d2ba2eec9c..4237ef3b679 100644 --- a/components/map.rst.inc +++ b/components/map.rst.inc @@ -139,6 +139,7 @@ * :doc:`/components/validator/introduction` * :doc:`/components/validator/resources` + * :doc:`/components/validator/metadata` * :doc:`/components/yaml/index` From 5d587d0985dffee7634886cfd9a00f6ff3a72073 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 4 Jul 2016 13:18:10 +0200 Subject: [PATCH 21/24] Fixed RST syntax --- components/validator/resources.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/validator/resources.rst b/components/validator/resources.rst index 40a31ebe58c..c765e6022c8 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -96,8 +96,8 @@ prefixed classes included in doc block comments (``/** ... */``). For example:: use Symfony\Component\Validator\Constraints as Assert; // ... - class User - { + class User + { /** * @Assert\NotBlank() */ From 5ee8dd13a6bcac2119697590977eb88bc66892bd Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 4 Jul 2016 13:18:50 +0200 Subject: [PATCH 22/24] Added a missing trailing comma --- components/validator/introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index c115daff522..d7301d26085 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -36,7 +36,7 @@ characters long:: $validator = Validation::createValidator(); $violations = $validator->validate('Bernhard', array( new Length(array('min' => 10)), - new NotBlank() + new NotBlank(), )); if (0 !== count($violations)) { From 7d003afec1709e4978063e35ecbb1c33f84c2e6f Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 4 Jul 2016 16:09:25 +0200 Subject: [PATCH 23/24] Lots of minor fixes --- components/validator/resources.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/components/validator/resources.rst b/components/validator/resources.rst index c765e6022c8..b5251eb630c 100644 --- a/components/validator/resources.rst +++ b/components/validator/resources.rst @@ -10,7 +10,7 @@ class, the metadata is defined by the class itself. When validating simple value the metadata must be passed to the validation methods. Class metadata can be defined in a configuration file or in the class itself. -The Validator component retrieves that metadata using a set of loaders. +The Validator component collects that metadata using a set of loaders. .. seealso:: @@ -54,12 +54,13 @@ In this example, the validation metadata is retrieved executing the .. tip:: - You can call this method multiple times to add several method names. You can - also use :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addMethodMappings` + Instead of calling ``addMethodMapping()`` multiple times to add several + method names, you can also use + :method:`Symfony\\Component\\Validator\\ValidatorBuilder::addMethodMappings` to set an array of supported method names. -The FileLoaders ---------------- +The File Loaders +---------------- The component also provides two file loaders, one to load YAML files and one to load XML files. Use @@ -146,7 +147,7 @@ Caching Using many loaders to load metadata from different places is convenient, but it can slow down your application because each file needs to be parsed, validated -and converted to a :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` +and converted into a :class:`Symfony\\Component\\Validator\\Mapping\\ClassMetadata` instance. To solve this problem, you can cache the ``ClassMetadata`` information. The Validator component comes with an From 6da7a0d43dad9c32c54b68ff23a5a2f7185340bd Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 8 Jul 2016 19:51:54 +0200 Subject: [PATCH 24/24] Final rewords --- components/validator/introduction.rst | 14 ++------------ components/validator/metadata.rst | 7 ------- 2 files changed, 2 insertions(+), 19 deletions(-) diff --git a/components/validator/introduction.rst b/components/validator/introduction.rst index d7301d26085..37915f170ed 100644 --- a/components/validator/introduction.rst +++ b/components/validator/introduction.rst @@ -58,18 +58,8 @@ recommended to use the :class:`Symfony\\Component\\Validator\\Validation` class: $validator = Validation::createValidator(); This ``$validator`` object can validate simple variables such as strings, numbers -and arrays, but it can't validate objects. To do so, use the -:class:`Symfony\\Component\\Validator\\ValidatorBuilder` class to configure the -``Validator`` class:: - - use Symfony\Component\Validator\Validation; - - $validator = Validation::createValidatorBuilder() - // ... build a custom instance of the Validator - ->getValidator(); - -In the next sections, you'll learn about all the validator features that you -can configure: +and arrays, but it can't validate objects. To do so, configure the +``Validator`` class as explained in the next sections: * :doc:`/components/validator/resources` * :doc:`/components/validator/metadata` diff --git a/components/validator/metadata.rst b/components/validator/metadata.rst index 335ed4fe481..645ab9f0ac9 100755 --- a/components/validator/metadata.rst +++ b/components/validator/metadata.rst @@ -64,13 +64,6 @@ Then, add the Validator component configuration to the class:: } } -.. note:: - - The keen-eyed among you will have noticed that the prefix of the getter - (``get`` or ``is``) is omitted in the mapping. This allows you to move the - constraint to a property with the same name later (or vice versa) without - changing your validation logic. - Classes -------