Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[WIP] Documenting the Validator component #3710

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

[WIP] Documenting the Validator component #3710

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
29a4cc2
Get started with the Validator docs
wouterj Mar 22, 2014
609774b
Added small configuration section
wouterj Mar 23, 2014
8f98512
Added article about loaders
wouterj Mar 23, 2014
0bd220d
Applied comments by @cordoval
wouterj Mar 24, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Applied comments by @cordoval
  • Loading branch information
@wouterj
wouterj committed Mar 24, 2014
commit 0bd220dae72fc465efd7857432ee81fe367679a8
17 changes: 9 additions & 8 deletions components/validator/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say "do easy validation tasks with it"... Don´t you think the sentence is a bit weird right now?

to validate a string is at least 10 character long, the only code you need is::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn´t it be validate that a string...?


use Symfony\Component\Validator\Validation;
use Symfony\Component\Validator\Constraints\Length;
Expand All @@ -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)));
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would be good to put an example that fails to show some more detail on the output

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The string is 8 characters long, while the constraints expects a minimum of 10 character. So it already fails. However, I agree that we should put some "show error" logic in here (I copied this example from the README).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, it's already in there....


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>';
}
Expand All @@ -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`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is recommended to use

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();
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could you please provide a tip saying how it is done in symfony or maybe the service factory is shared but each time it creates a validator or how it is done, would be a good complement.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe let's also mention what the deps that configure a validator are:

    public function __construct(
        MetadataFactoryInterface $metadataFactory,
        ConstraintValidatorFactoryInterface $validatorFactory,
        TranslatorInterface $translator,
        $translationDomain = 'validators',
        array $objectInitializers = array()
    )


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

arrays instead of array

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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To do that is said twice... I am not native but what about something like "In order to achieve that"

This class can be retrieved by using the
:method:`Validation::createValidatorBuilder() <Symfony\\Component\\Validator\\Validation::createValidatorBuilder>`
method::

Expand Down
32 changes: 17 additions & 15 deletions components/validator/resources.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The metadata can also be passed to the validate methods

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not when validating a class

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should -> can

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well, it should be defined in a configuration file or the object isn't validated :)

class itself. The ``Validator`` needs to be able to retrieve this metadata
Expand All @@ -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
Expand All @@ -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::

Expand Down Expand Up @@ -70,8 +70,9 @@ The AnnotationLoader

At last, the component provides an
:class:`Symfony\\Component\\Validator\\Mapping\\Loader\\AnnotationLoader`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe let's add a note that it works together with the reader and the loader just loads the annotations but does not read them, for that it needs that collaborator

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::

// ...

Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence sounds weird to me, I would say you should have xxx and yyy packages installed from Packagist, but again I am not native :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I'm not a native either, but the current thing sounds better to me. What's the correct way @weaverryan ? :)

``doctrine/annotations`` and ``doctrine/cache`` packages of Packagist.
``doctrine/annotations`` and ``doctrine/cache`` packages from Packagist.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i wonder if the autoload.php for some projects is still needed to load the annotation reader, or if any comment should be made here, just to ensure or avoid some pitfalls for not being able to make it work.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good idea!

Using Multiple Loaders
----------------------
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should just be cache and no cacher but i give you the reasons sometimes the classes are not named Cacher

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

problems -> problem

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's still a cacher. We don't talk about the name here, just what it does.

My name is Wouter, yet I'm still a person... In the same way, something called YamlFile can be a cacher.

And using "cache" here seems like we configure the cache system behind it, strictly spoken we configure the adapter.

the ``ClassMetadata`` after it was loaded.
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This means instead of that means?

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
Expand Down Expand Up @@ -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.