Initial validation chapter import #158

Closed
wants to merge 2 commits into
from

Conversation

Projects
None yet
2 participants
Member

weaverryan commented Mar 13, 2011

Hey guys-

This is the refactoring of the validation guides into one official book chapter. Some pieces were moved into the cookbook and others into the reference section. There are also random formatting fixes.

What I'm really looking for is any feedback on the validation chapter itself. It's not complete (e.g. validation groups aren't covered), but we'll merge this in as a start.

Thanks!

@weaverryan weaverryan [book][validation] Initial import of the re-worked validation chapter
The validation sections have been replaced and the constraints have been moved to the reference section.

The custom constraints portion was moved to the cookbook.
2491728
Member

weaverryan commented Mar 13, 2011

Also, this will break a link on the following page: http://symfony.com/doc/2.0/

The Validation link will now need to be /doc/2.0/book/validator.html

@fabpot fabpot commented on the diff Mar 13, 2011

cookbook/validation/custom_constraint.rst
+constraint are represented as public properties on the constraint class. For
+example, the :doc:`Url</reference/constraints/Url>` constraint includes
+the ``message`` and ``protocols`` properties:
+
+.. code-block:: php
+
+ namespace Symfony\Component\Validator\Constraints;
+
+ class Url extends \Symfony\Component\Validator\Constraint
+ {
+ public $message = 'This value is not a valid URL';
+ public $protocols = array('http', 'https', 'ftp', 'ftps');
+ }
+
+As you can see, a constraint class is fairly minimal. The actual validation is
+performed by a another "constraint validator" class. The constraint validator
@fabpot

fabpot Mar 13, 2011

Owner

"by another" ("a" should be removed)

@fabpot fabpot commented on an outdated diff Mar 13, 2011

book/validation.rst
@@ -0,0 +1,577 @@
+.. index::
+ single: Validation
+
+Validation
+==========
+
+Validation is a very common task in web applications. Data entered in forms
+needs to be validated. Data also needs to be validated before it is written
+into a database or passed to a web service.
+
+Symfony2 ships with a `Validator`_ component that makes this task easy and transparent.
+This component is based on the `JSR303 Bean Validation specification`_. What?
+A Java specification in PHP? You heard right, but it's not as bad as it sounds.
+Let's look at how it can be used it in PHP.
@fabpot

fabpot Mar 13, 2011

Owner

I think the last "it" should be removed.

@fabpot fabpot commented on an outdated diff Mar 13, 2011

book/validation.rst
+ {
+ /**
+ * @validation:NotBlank()
+ */
+ private $name;
+ }
+
+ .. code-block:: php
+
+ // Acme/BlogBundle/Author.php
+ use Symfony\Component\Validator\Mapping\ClassMetadata;
+ use Symfony\Component\Validator\Constraints\NotBlank;
+
+ class Author
+ {
+ private $name;
@fabpot

fabpot Mar 13, 2011

Owner

was public above.

@fabpot fabpot commented on an outdated diff Mar 13, 2011

book/validation.rst
+.. code-block:: text
+
+ Acme\BlogBundle\Author.name:
+ This value should not be blank
+
+If you insert a value into the ``name`` property, the happy success message
+will appear.
+
+Each validation error (called a "constraint violation"), is represented by
+a :class:`Symfony\\Component\\Validator\\ConstraintViolation` object, which
+holds a message describing the error. Moreover, the ``validate`` method returns
+a :class:`Symfony\\Component\\Validator\\ConstraintViolationList` object,
+which acts like an array. That's a long way of saying that you can use the
+errors returned by ``validate`` in more advanced ways:
+
+.. code-block:: php
@fabpot

fabpot Mar 13, 2011

Owner

I would have used Twig here as this is our default templating system.

@fabpot fabpot commented on an outdated diff Mar 13, 2011

book/validation.rst
+
+ if (count($errorList) > 0) {
+ $html = '<h3>The Author object has the following errors</h3>';
+ $html .= '<ul>';
+ foreach ($errorList as $constraintViolation) {
+ $html .= sprintf('<li>%s</li>', $constraintViolation->getMessage());
+ }
+ $html .= '</ul>';
+
+ return new Response($html);
+ } else {
+ // ...
+ }
+
+.. note::
+
@fabpot

fabpot Mar 13, 2011

Owner

ok, I understand why you've used PHP above, but I think you can just use a template here. People reading this chapter will probably understand how to do the link between the controller and the template.

@fabpot fabpot commented on the diff Mar 13, 2011

book/validation.rst
+ $author = new Acme\BlogBundle\Author();
+ $form = new Acme\BlogBundle\AuthorForm('author', $author, $this->get('validator');
+ $form->bind($this->get('request')->request->get('customer'));
+
+ if ($form->isValid()) {
+ // process the Author object
+ } else {
+ // render the template with the errors
+ $this->render('BlogBundle:Author:form.html.twig', array('form' => $form));
+ }
+
+For more information, see the :doc:`Forms</book/forms/overview>` chapter.
+
+.. index::
+ pair: Validation; Configuration
+
@fabpot

fabpot Mar 13, 2011

Owner

What about adding a section "Validation and Doctrine"? I think this is quite useful to show how you can validate a Doctrine object before saving it even if it does not come from a form.

@fabpot fabpot commented on the diff Mar 13, 2011

book/validation.rst
+
+ class Author
+ {
+ protected $gender;
+
+ public static function loadValidatorMetadata(ClassMetadata $metadata)
+ {
+ $metadata->addPropertyConstraint('gender', new Choice(array('male', 'female')));
+ }
+ }
+
+Be sure not to let the two different methods of specifying options confuse
+you. If you're unsure, either check the API documentation for the constraint
+or play it safe by always passing in an array of options (the first method
+shown above).
+
@fabpot

fabpot Mar 13, 2011

Owner

This makes me think that we probably need a recipe on how to use the choice constraint with a callback and/or Doctrine.

@fabpot fabpot commented on the diff Mar 13, 2011

book/validation.rst
+
+ 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.
+
+Final Thoughts
+--------------
+
+The Symfony2 ``validator`` is a powerful tool that can be leveraged to
+guarantee that the data of any object is "valid". The power behind validation
+lies in "constraints", which are rules that you can apply to properties or
+getter methods of your object. And while you'll most commonly use the validation
+framework indirectly when using forms, remember that it can be used anywhere
+to validate any object.
+
@fabpot

fabpot Mar 13, 2011

Owner

We probably need to add a section/tip/note about how to validate an array as I think many people will have this question at some point.

Owner

fabpot commented Mar 13, 2011

I like this chapter very much. It's easy to read, simple, and concise. Great job Ryan!

Member

weaverryan commented Mar 14, 2011

Fabien-

Thanks for the feedback :) - I've made all of the fixes you've noted. I've also added the following to our running spreadsheet of documentation todos (which I'll plan to move into Jira when we get that far):

  • Add section about Doctrine+Validation
  • Add cookbook about Choice + callback and also Doctrine choice (link to from chapter)
  • Add note on validating an array

I'll merge this in now - I've got everything fixed or noted.

Thanks!

This issue was closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment