Misleading php templating guide for custom form types

[pauvos]

The documentation seems to be partly wrong/incomplete for php templating of custom form types:
http://symfony.com/doc/master/cookbook/form/create_custom_field_type.html#creating-a-template-for-the-field

1. "PHP" tab of the widget shows php syntax but the comment in the first line suggests the file should be named gender_widget.html.twig ... which does not make much sense.
2. Instead of declaring the new templates in the twig:form:resources section of the config.yml I think it should be framework:templating:form:resources. That's where the FrameworkBundle's templates are registered.
3. A hint to extend framework:templating:engines by 'php' could be helpful (although this is not specific to form type templates).

So while the how-to is precise and working for Twig templating, the alternative php examples are somewhat misleading.
Unfortunately I haven't been able to get this working.
If someone maybe can point me in the right direction I'll be happy to supply a corrected version in a pull request.

Still wondering... how does symfony know which template to render for my form type? Only by the name convention _widget.html.php?

[weaverryan]

Hi @Aal!

Yes, it looks like (1) and probably (2) are legit bugs with the docs. I've labeled this issue as actionable.

About which template to render, yes - it's all done by naming conventions. That's true for Twig (the names are the blocks) and PHP (the names are the files). Here is some more information about that: http://symfony.com/doc/current/book/forms.html#form-fragment-naming

Additionally, we do talk about the proper configuration when using PHP templates here: http://symfony.com/doc/current/book/forms.html#form-fragment-naming. But I think we should probably remove some of the form theming docs from the form chapter and consolidate them into the existing cookbook on this topic (http://symfony.com/doc/current/cookbook/form/form_customization.html) and make sure things are easy to read.

I hope this helps and thanks for the report! If you'd like, you can certainly fix (1) and (2) if it's clear to you.

Cheers!

[wouterj]

(1) and (2) are fixed by #4103 and as such, I believe this issue can be closed. If you don't agree, feel free to comment!