Validation
Hopefully the examples of the previous chapters made you shudder or at least
raised some questions. Although it’s surely nice to have one-liners for actions
like create
and update
we need some more code to validate the incoming
values before they are eventually persisted and the outgoing content before it’s
rendered to the browser.
You won’t have to care too much about the latter if you’re using Fluid to render
your View because, because it escapes your data by default.
As a result, even if the post subject contains the string
<script>alert("danger")</script>
outputting it via {post.subject}
will
result in the unaesthetic but harmless
<script>alert("danger")</script>
.
But most applications come with additional rules that apply to the domain model. Maybe you want to make sure that a post subject must consist of at least 3 and at maximum 50 characters for example. But do you really want these checks in your action methods? Shouldn’t we rather separate the concerns 1 of the action methods (show, create, update, …) from others like validation, logging and security?
Fortunately Flow’s validation framework doesn’t ask you to add any additional PHP code to your action methods. Validation has been extracted as a separated concern which does it’s job almost transparently to the developer.
Declaring Validation Rules
When we’re talking about validation, we usually refer to validating models. The rules defining how a model should be validated can be classified into three types:
Base Properties – a set of rules defining the minimum requirements on the properties of a model which must be met before a model may be persisted.
Base Model – a set of rules or custom validator enforcing the minimum requirements on the combination of properties of a model which must be met before a model may be persisted.
Supplemental – a set of rules defining additional requirements on a model for a specific situation, for example for a certain action method.
Note
Base model and supplemental rules are not covered by this tutorial. Detailed information is available in Part III - Validation.
Rules for the base properties are defined directly in the model in form of annotations:
Classes/Acme/Blog/Domain/Model/Post.php:
/**
* @Flow\Validate(type="NotEmpty")
* @Flow\Validate(type="StringLength", options={ "minimum"=3, "maximum"=50 })
* @var string
*/
protected $subject;
/**
* @Flow\Validate(type="NotEmpty")
* @var string
*/
protected $author;
/**
* @Flow\Validate(type="NotEmpty")
* @ORM\ManyToOne(inversedBy="posts")
* @var Blog
*/
protected $blog;
The Validate
annotations define one or more validation rules which should apply to a
property. Multiple rules can be defined in dedicated lines by further Validate
annotations.
Note
Per convention, every validator allows (passes) empty values, i.e. empty strings or null values. This is for achieving fields which are not mandatory, but if filled in, must satisfy a given validation. Consider an email address field for example which is not mandatory, but has to match an email pattern as soon as filled in.
If you want to make a field mandatory at all, use the NotEmpty
validator in addition,
like in the example above.
The technical background is the acceptsEmptyValues
property of the AbstractValidator,
being true
per default. When writing customized validators, it’s basically possible
to set this field to false
, however this is not generally recommended due to the convention
that every validator could principally be empty.
Tip
Flow provides a range of built-in validators which can be found in the
Flow\Validation\Validator
sub package. The names used in the
type
attributes are just the unqualified class names of these validators.
It is possible and very simple to program custom validators by implementing
the Neos\Flow\Validation\Validator\ValidatorInterface
.
Such validators must, however, be referred to by their fully qualified
class name (i.e. including the namespace).
Make sure the above validation rules are set in your Post
model, click on the
Create a new post
link below the list of posts and submit the empty form. If all went fine,
you should end up again in the new post form, with the tiny difference
that the text boxes for title and author are now framed in red:
![Validation errors shown in form](../../_images/CreateNewPostValidationError1.png)
Validation errors shown in form
Displaying Validation Errors
The validation rules seem to be in effect but the output could be a bit more meaningful. We’d like to display a list of error messages for exactly this case when the form has been submitted but contained errors.
Fluid comes with a specialized view helper which allows for iterating over
validation errors, the <f:validation.results>
view helper.
We’ll need validation results for the create and the update case, so let’s put the
View Helper in a new partial FormErrors
:
*Resources/Private/Partials/FormErrors.html*:
<f:validation.results for="{for}">
<f:if condition="{validationResults.flattenedErrors}">
<dl class="errors">
<f:for each="{validationResults.flattenedErrors}" key="propertyName" as="errors">
<dt>
{propertyName}:
</dt>
<dd>
<f:for each="{errors}" as="error">{error}</f:for>
</dd>
</f:for>
</dl>
</f:if>
</f:validation.results>
And include that partial to both, the New.html
and the Edit.html
templates just above the
form:
*Resources/Private/Templates/Post/New.html*:
<f:render partial="FormErrors" arguments="{for: 'newPost'}" />
<f:form action="create" objectName="newPost">
...
and:
*Resources/Private/Templates/Post/Edit.html*:
<f:render partial="FormErrors" arguments="{for: 'post'}" />
<f:form action="update" object="{post}" objectName="post">
...
Similar to the <f:for>
view helper <f:validation.results>
defines a loop
iterating over validation errors. The attribute as
is optional and if it’s
not specified (like in the above example) as="error"
is assumed.
To clearly understand this addition to the template you need to know that
errors can be nested: There is a global error object containing the errors of
the different domain objects (such as newPost
) which contain errors for
each property which in turn can be multiple errors per property.
After saving the modified template and submitting the empty form again you should see some more verbose error messages:
![More verbose validation errors shown in form](../../_images/CreateNewPostValidationError2.png)
More verbose validation errors shown in form
Validating Existing Data
The validation rules are enforced as soon as the GET or POST arguments are mapped to the action’s arguments.
But what if you add new validation rules when there are already persisted entities that might violate these?
For example if you had created a post with a subject of “xy” and added the StringLength
annotation
afterwards?
Doing so would prevent you from invoking any of the actions for that particular post. All you will see is an error message:
Validation failed while trying to call Acme\Blog\Controller\PostController->showAction().
So the problem is that Flow tries to validate the $post
argument for the
action although we don’t need a valid post at this point.
What’s important is that the post submitted to updateAction
or createAction
is
valid, but we don’t really care about the showAction
or editAction
which only displays the post or a form.
There’s a very simple remedy to this problem: don’t validate the post. With one additional annotation the whole mechanism works as expected:
Classes/Acme/Blog/Controller/PostController.php:
/**
* Displays a single post
*
* @Flow\IgnoreValidation("$post")
*/
public function showAction(Post $post): void
{
$this->view->assignMultiple([
'post' => $post,
'nextPost' => $this->postRepository->findNext($post),
'previousPost' => $this->postRepository->findPrevious($post),
]);
}
Now the showAction
can be called even though $post
is not valid.
You probably want to add the same annotation to the editAction
and even the deleteAction
so that
invalid posts can be fixed or removed.
- 1
See also: Separation of Concerns (Wikipedia)