[Form] Form Events documentation incorrectly states fields cannot be removed/added during SUBMIT event

[bkosborne]

The form events page indicate

"At this point, you cannot add or remove fields to the form."

when describing the SUBMIT event. It then follows up with an example listener that the Form component provides:

The Symfony\Component\Form\Extension\Core\EventListener\ResizeFormListener subscribes to the FormEvents::SUBMIT event in order to remove the fields that need to be removed whenever manipulating a collection of forms for which allow_delete has been enabled.

Indeed, when looking at the code for that listener, you can see that it is removing fields from the form, which the docs indicate cannot be done.

If someone confirms this is indeed an error, I'll create a PR.

[ogizanagi]

Even if it is actually possible, I doubt it is useful, because it won't change data at this point. The removal of a field at this point for instance won't influence the data you'll get from your form. However, if a validation error happens, the form will be rendered without the removed field. Which would be weird, in most cases.

I guess the ResizeFormListener matches this exact particular usage: As this event is planned for, it mainly modifies normalized data. The field removal here is not much important IMO: it only removes empty fields in the collection so that they won't appear back in the form in case of a validation error for instance.

So, I'm not sure it should be fixed. I think it won't help discerning which event is the most appropriated from another.

[xabbuh]

I tend to agree with @ogizanagi here. Even if it is technically possible to do that here without getting an error message, removing the warning may cause people to get confused and end up with hard to debug errors.

[bkosborne]

The jarring and confusing part is that immediately after the docs say you cannot remove fields to the form, it provides an example where fields are removed.

[ogizanagi]

@bkosborne: You're absolutely right ! I misinterpreted your intentions here, sorry.

We should probably not mention the field removal, and only talk about the modified normalized data instead, or even find another & simpler example like the FixUrlProtocolListener for instance, in order to avoid any confusion.

[xabbuh]

You are right about this. I suggest that we replace the existing example with the FixUrlProtocolListener which ensure that the value entered in a url type always has a protocol.

[bkosborne]

PR opened.