Re-check all form types inherited options #20104

javiereguiluz · 2024-08-09T14:10:21Z

Some form types extend other parent types (e.g. CountryType and EnumType extend ChoiceType). In the docs of the child classes, we display all options defined by them and all options defined by their parent types.

However, we handle this manually, so we miss options from time to time (this is a recurrent problem; see #2360).

So, we have two options:

Re-check all options again and fix errors manually
Re-think how we solve this

About rethinking:

We could just list the names of all the inherited options and link to the parent descriptions, instead of embedding all the descriptions in all child constrains
We could add some PHP logic in the docs-builder tool used to build docs to fix this somehow

Thoughts?

OskarStark · 2024-08-11T08:23:22Z

We could just list the names of all the inherited options and link to the parent descriptions, instead of embedding all the descriptions in all child constrains

Would be easier to maintain, but harder to consume by the user IMHO

We could add some PHP logic in the docs-builder tool used to build docs to fix this somehow

Would avoid manual errors, but hard to achieve with versionadded directives, without comparing to older branches I think.

MrYamous · 2024-08-22T08:33:16Z

As a first step of simplification, instead of including the options one by one, could we group them together in a parent class file and include that ? This implies that we can use include in an rst.inc file, I don't know if that's possible.

This would allow, if we take EnumType as an example, to include a file like choice_options.rst.inc which would itself include the twenty files for the different options.
Then, if a ChoiceType option is added tomorrow, we only have to add it in one place, without having to check every type that inherits from ChoiceType.

stof · 2025-02-07T15:02:54Z

This won't work well with the overriden options section, which handles some of the parent options in a special way (and so they must be excluded from inherited options)

yceruto · 2025-02-07T16:32:14Z

An automated script to sync this doc with its code would be great here.

this reminds me that I wrote this project some years ago: https://github.com/phplancer/symfony-form to explore this idea using the debug:form command, which exposes all this information easily in JSON format (using the --format=json option).

with debug:form --format=json, we will get all builtin_form_types, then go in with debug:form ChoiceType --format=json to gather all options (grouped into "own", "overridden", "parent" and those that come from "type extensions"), then go deeper with debug:form ChoiceType choice_filter --format=json to get the option details.

we could run it per Symfony version and generate a diff to know when we should add a versionadded directive with a generic text.

the missing part would be how to link each form type and its options with their corresponding documentation… maybe using some naming conventions to load it!? And if the doc doesn't exist, we can always display the option "info" (if provided) as a fallback doc.

I can help with this if it works for you, but I’d need to explore the building system first to understand it better.

javiereguiluz mentioned this issue Aug 9, 2024

[Form] Re-adding choice_label to EnumType #19499

Closed

javiereguiluz marked this as a duplicate of #20634 Feb 7, 2025

javiereguiluz mentioned this issue Feb 7, 2025

The reference documentation for form fields misses some inherited options #20634

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Re-check all form types inherited options #20104

Re-check all form types inherited options #20104

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Re-check all form types inherited options #20104

Re-check all form types inherited options #20104

Comments

Uh oh!

Uh oh!

Uh oh!

Uh oh!