[Form] Add ability to clear form errors #27580

colinodell · 2018-06-11T22:00:36Z

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#14060
License	MIT
Doc PR	symfony/symfony-docs#9916

This PR adds the ability to manually clear form errors, thus improving the DX issue reported in #14060.

Unlike my original approach in #14233 and #27571 which break BC, this adds a new ClearableErrorInterface which Form implements. (Button does not implement it because buttons can't have errors.)

yceruto · 2018-06-11T23:27:09Z

src/Symfony/Component/Form/ClearableErrorInterface.php

+     *
+     * @return $this
+     */
+    public function clearErrors($deep = false);


Could true be a better default here? How frequent is to clear errors for root form only? I think most of the time it happens inside a child field.

There is an issue about the same default but getErrors($deep = false) method #25738 and was reported as confusing.

I don't have a strong preference either way, but I do think the default value here should match getErrors().

TerjeBr · 2018-06-12T08:11:42Z

I have now thought about this, what about adding a FormExtendedInterface that extends both FormInterface and ClearableErrorInterface? The use case for the interface after all is to have a way to pass around form objects to functions and methods, and then you want an all inclusive interface that can cover all the methods implemented in the Form class. What do you think?

apfelbox · 2018-06-12T09:50:01Z

src/Symfony/Component/Form/Form.php

+            // Clear errors from children
+            foreach ($this as $child) {
+                if ($child instanceof ClearableErrorInterface) {
+                    $child->clearErrors(true);


Is it possible to have a clearable form type nested in a non-clearable one?

Yes, buttons are not clearable and they could be included in a form that is clearable.

The question was the other way round. As the code here stops the traversal of the form tree as soon as a non-clearable form type is encountered, it will not clear clearable fields nested in non-clearable ones.

The only non-clearable fields we have in the symfony core are buttons that can't have children.

This could append in libraries but then it can be considered the responsibility of the library to implement this interface if needed.

Yeah, I know. But why risk it, if the change would be fairly easy?

It would mean children won't be able to implement custom error cleaning logic, that's something someone might want to do.

Yeah, I know. But why risk it, if the change would be fairly easy?

We can't add clearErrors() to FormInterface as that would be a BC break. And even if we could, that would require us to implement clearErrors() on the Button class, which makes no sense because buttons can't have errors or children - it'll either be a pointless no-op or throw a BadMethodCallException.

I wasn't hinting at implementing it everywhere, but decoupling the traversal of the form tree from the actual form field clearing.

Like the visitor pattern, if you will.
But this edge case doesn't seem too severe.

vudaltsov · 2018-06-14T23:27:55Z

src/Symfony/Component/Form/ClearableErrorInterface.php

+     *
+     * @return $this
+     */
+    public function clearErrors($deep = false);


Let's add type hint to argument public function clearErrors(bool $deep = false);.
But please don't add : self, we already had discussion on this (#27190 (comment)).

Added and amended! Thanks for the feedback 👍

vudaltsov · 2018-06-14T23:52:50Z

If the method is clearErrors than probably the interface might be ClearableErrorsInterface?

colinodell · 2018-06-14T23:57:13Z

Good idea @vudaltsov, I like that better! I have made that change.

vudaltsov

Awesome! Looking forward to AJAX partial form reloading without errors workarounds 😃

HeahDude

Looks good, thanks!

HeahDude · 2018-06-16T10:58:31Z

src/Symfony/Component/Form/ClearableErrorsInterface.php

+     *
+     * @return $this
+     */
+    public function clearErrors(bool $deep = false);


You should type hint : self here

@HeahDude , we had a discussion on return types here: #27190 (comment)
The problem will be that when using ->clearErrors()-> on actual object implementing this interface, the IDE will not show any other methods in autocomplete, because : self is not : static. So from my opinion it's much better to leave @return $this phpdoc.

You can leave the @return $this phpdoc and add : self at the same time. AFAIK phpdoc takes precedence with type declaration for IDE auto completion, this means we would get both the correct auto completion and strictness at the language level (that an instance of the interface is returned).

okay, then let's use : self 😄

Using : self on an interface forces the Form subclass implementation to use a : ClearableErrorsInterace typehint:

Fatal error: Declaration of Symfony\Component\Form\Form::clearErrors(bool $deep = false): Symfony\Component\Form\Form must be compatible with Symfony\Component\Form\ClearableErrorsInterface::clearErrors(bool $deep = false): Symfony\Component\Form\ClearableErrorsInterface in src/Symfony/Component/Form/Form.php on line 61

I'm not sure this is what we want.

AFAIK phpdoc takes precedence with type declaration for IDE auto completion

I could not get this working in the latest version of PhpStorm:

Furthermore, I could not find any other interfaces in Symfony with a : self return type hint. For these reasons I think we should leave it as-is.

The fact that we don't have any existing interfaces with a self return type hint is probably because we couldn't make use of them before Symfony 4. So I would still use it here and use the docblock to be more precise.

HeahDude · 2018-06-16T11:01:31Z

src/Symfony/Component/Form/ClearableErrorsInterface.php

+    /**
+     * Removes all the errors of this form.
+     *
+     * @param bool $deep whether to remove errors from child forms as well


Symfony code base uses capital style to comment params.

Fixed, amended, and force-pushed :) Thanks for catching that!

xabbuh · 2018-06-19T09:59:56Z

src/Symfony/Component/Form/Form.php

+    /**
+     * {@inheritdoc}
+     */
+    public function clearErrors(bool $deep = false)


missing return type hint (same in the interface)

actually I am not even sure if it makes sense that this method returns anything

All form methods are chainable, so it makes sense to keep it here.

@xabbuh see #27580 (comment)

I think it's time to decide this once and for all in https://symfony.com/doc/current/contributing/code/standards.html

Well, fluent methods are a pain for return types. so even if we want to have as much return types as possible for new APIs, I'm not sure we want them for fluent APIs.

@xabbuh @stof I have removed return $this; from the method for a few reasons:

You're right, this method doesn't really need to be chainable.

ClearableTokenStorageInterface (a new and similar interface introduced in SF4) does not return anything, so perhaps we should be consistent here.

It seems like there's no definitive rule on how to type hint interface methods that return $this / self. I don't want to set a bad precedent here.

Then you should add : void in interface and class

But I am for consistency with FormInterface which has @return $this on methods like addError. Although I agree that fluent interfaces are pain.

I've changed my mind and added return $this; back in. I could see developers wanting to call $form->clearErrors()->createView() so this definitely has value.

The last unanswered question is what to do about return types. Our ultimate goal is to have Form::clearErrors() return that original Form instance. Here's what the Return Type Declarations RFC has to say about our current situation:

The enforcement of the declared return type during inheritance is invariant; this means that when a sub-type overrides a parent method then the return type of the child must exactly match the parent and may not be omitted.

This is why using : self on the interface requires the Form method to use : ClearableErrorsInterface which is not ideal.

However, the RFC goes on to say:

If the parent does not declare a return type then the child is allowed to declare one.

Because this is a valid approach, I think omitting the return type from the interface but using : self on the Form makes the most sense in this situation:

A return type on the interface is pointless because there are literally no other methods on ClearableErrorsInterface. Is somebody really going to call $form->clearErrors()->clearErrors()->clearErrors()?

This gives us the functionality we want (accurate return type hint on Form) despite PHP's current limitations with invariant return types.

colinodell · 2018-06-19T13:11:15Z

src/Symfony/Component/Form/Form.php

+     *
+     * @return $this
+     */
+    public function clearErrors(bool $deep = false): self


@xabbuh I have added a : self return type here per your request. See #27580 (comment) for an explanation of why I didn't also add a return type to the interface. Let me know your thoughts :)

colinodell · 2018-06-20T20:11:34Z

Tests are failing, but I don't think it's because of my changes. All tests under src/Symfony/Component/Form are passing locally.

fabpot · 2018-06-25T09:52:05Z

Thank you @colinodell.

This PR was squashed before being merged into the 4.2-dev branch (closes #27580). Discussion ---------- [Form] Add ability to clear form errors | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #14060 | License | MIT | Doc PR | symfony/symfony-docs#9916 This PR adds the ability to manually clear form errors, thus improving the DX issue reported in #14060. Unlike my original approach in #14233 and #27571 which break BC, this adds a new `ClearableErrorInterface` which `Form` implements. (`Button` does not implement it because buttons can't have errors.) Commits ------- 9eb755c [Form] Add ability to clear form errors

fabpot · 2018-06-25T09:53:22Z

Changelog added in a1eb649 (forgot to comment before merging)

…uiluz) This PR was merged into the master branch. Discussion ---------- [Form] Ability to clear form errors Documenting the new feature proposed in symfony/symfony#27580 Commits ------- f07f536 Wrap long lines and add the versionadded directive 7a4465d Clarify that clearing errors makes the form valid d4143f1 [Form] Ability to clear form errors

carsonbot added Status: Needs Review Form Feature labels Jun 11, 2018

This was referenced Jun 11, 2018

[DX] [Form] Ability to reset form validation errors (or prevent them from rendering) #14060

Closed

[Form] Ability to clear form errors symfony/symfony-docs#9916

Merged

colinodell force-pushed the feature/clearable-forms branch from ff852b9 to 10985d3 Compare June 11, 2018 22:16

yceruto reviewed Jun 11, 2018

View reviewed changes

apfelbox reviewed Jun 12, 2018

View reviewed changes

nicolas-grekas added this to the next milestone Jun 14, 2018

vudaltsov suggested changes Jun 14, 2018

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels Jun 14, 2018

colinodell force-pushed the feature/clearable-forms branch 2 times, most recently from f365b92 to f86e407 Compare June 14, 2018 23:47

colinodell force-pushed the feature/clearable-forms branch from f86e407 to 17c427e Compare June 14, 2018 23:55

carsonbot removed the Status: Needs Work label Jun 15, 2018

vudaltsov approved these changes Jun 15, 2018

View reviewed changes

carsonbot added the Status: Reviewed label Jun 15, 2018

HeahDude reviewed Jun 16, 2018

View reviewed changes

colinodell force-pushed the feature/clearable-forms branch from 17c427e to 5c1a657 Compare June 17, 2018 14:32

vudaltsov mentioned this pull request Jun 19, 2018

[Form] Add ability to clear form errors #27571

Closed

HeahDude approved these changes Jun 19, 2018

View reviewed changes

xabbuh requested changes Jun 19, 2018

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Reviewed labels Jun 19, 2018

colinodell force-pushed the feature/clearable-forms branch from c69e507 to ed74efd Compare June 19, 2018 13:04

colinodell commented Jun 19, 2018

View reviewed changes

nicolas-grekas approved these changes Jun 21, 2018

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Work labels Jun 21, 2018

maxhelias approved these changes Jun 21, 2018

View reviewed changes

xabbuh approved these changes Jun 25, 2018

View reviewed changes

fabpot approved these changes Jun 25, 2018

View reviewed changes

[Form] Add ability to clear form errors

9eb755c

fabpot force-pushed the feature/clearable-forms branch from ed74efd to 9eb755c Compare June 25, 2018 09:51

fabpot merged commit 9eb755c into symfony:master Jun 25, 2018

nicolas-grekas modified the milestones: next, 4.2 Nov 1, 2018

This was referenced Nov 3, 2018

Release v4.2.0-BETA1 #29072

Closed

Release v4.2.0-BETA1 #29073

Merged

[Form] Add ability to clear form errors #27580

[Form] Add ability to clear form errors #27580

Conversation

colinodell commented Jun 11, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TerjeBr commented Jun 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vudaltsov commented Jun 14, 2018

colinodell commented Jun 14, 2018

vudaltsov left a comment

Choose a reason for hiding this comment

HeahDude left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vudaltsov Jun 16, 2018 • edited Loading

Choose a reason for hiding this comment

jvasseur Jun 16, 2018 • edited Loading

Choose a reason for hiding this comment

vudaltsov Jun 16, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

colinodell commented Jun 20, 2018

fabpot commented Jun 25, 2018

fabpot commented Jun 25, 2018

colinodell commented Jun 11, 2018 •

edited

Loading

TerjeBr commented Jun 12, 2018 •

edited

Loading

vudaltsov Jun 16, 2018 •

edited

Loading

jvasseur Jun 16, 2018 •

edited

Loading

vudaltsov Jun 16, 2018 •

edited

Loading