#160 - Full control over the launch form fields (type, options, constraints, default) through the new form UI option

[clever-age-gtonon]

Description

Implements #160 (rebased on main): the process configuration has full control over the UI launch form (ui_launch_mode: form). For the input field and each context key, it declares the form type (FQCN), its options (with the field constraints) and its default value. Example: the delimiter context value becomes a "Delimiter" select instead of two free text inputs.

options:
    ui:
        ui_launch_mode: form
        form:
            input:
                type: Symfony\Component\Form\Extension\Core\Type\FileType
                options:
                    label: CSV file
                    constraints:
                        - File: { extensions: { csv: ['text/csv', 'text/plain'] } }
            context:
                delimiter:
                    type: Symfony\Component\Form\Extension\Core\Type\ChoiceType
                    default: ','
                    options:
                        label: Delimiter
                        choices: { 'Comma (,)': ',', 'Semicolon (;)': ';' }
                        required: true
            allow_extra_context: false     # default true: free key/value pairs for the undeclared keys
            constraints: []                # constraints of the whole {input, context} data (replaces ui.constraints)

The data of the form keeps its shape ({input, context: {key => value}}), so the dispatched message is unchanged.

Changes

• form UI option:
  • form.input / form.context.<key>: type (FQCN of a form type, not a button), options (with constraints, same syntax as the global constraints), default;
  • an EnumType default is an enum case (!php/enum);
  • the declared context fields are not required by default.
• Free pairs: form.allow_extra_context (default true). A free pair whose key is a declared field is a validation error (reserved_keys option of ProcessContextType).
• Values: the typed values are converted into process values after the validation (internal ContextValueNormalizer). A value that cannot be converted is reported as an error of its field.
• Resolution:
  • the launch form is resolved by the internal LaunchFormOptionsResolver (ProcessConfigurationsManager::getLaunchFormOptions()), only on the launch page;
  • getUiOptions() keeps its 3.2 shape: the process list and the executions list do not depend on the launch form, and trigger no deprecation.
• Checks when the container is built (internal LaunchFormsCacheWarmer, not optional, also run on the automatic rebuild in debug mode): each launch form is resolved, then built with the form factory of the application (form type options and type extensions, default values, constraint validators). An invalid launch form fails cache:clear with a message naming the process.
• Deprecations (removal in 4.0): entrypoint_type → form.input.type, default → form.*.default, constraints → form.constraints.
  • They are folded into form, and mixing a deprecated option with its replacement is refused.
  • They are triggered when the launch form is displayed.
• Documentation: reference (02-process_ui_options.md), cookbook (form_file_upload.md), upgrade guide, changelog.

Tests

PHPUnit (also with pcov and strict coverage metadata, as in the CI), PHPStan level 10, PHP-CS-Fixer, Rector, twig-cs-fixer: OK.

Breaking changes

None for a configuration that keeps working with the deprecated options (minor, 3.3). See UPGRADE.md:

• the free context pairs of the launch form are renamed launch[context][extra][<index>], as context is now a compound FormType (form theme blocks _launch_context_extra_entry_*);
• the duplicated default.context keys are merged (the last one wins).

🤖 Generated with Claude Code

[njoubert-cleverage]

Thanks for this work: the feature covers the whole scope of #160, the deprecated options are cleanly folded into form, the deprecation messages name the process, and the docs, upgrade guide and tests (403 → 588) are thorough. CI is green and the CHANGELOG conflict of #161 is solved.

Requesting changes for the points below (details in the inline comments).

Blocking

1. Scope. The PR bundles three changes that are not part of #160 and deserve their own issue/PR (and changelog entry):
   • execution_user always set to the connected user and reserved (security-related behaviour change, previously a context value could override it);
   • the format rule on the keys of the free context pairs, including the schedules;
   • ProcessConfigurationsManager resolving only the requested option (ui / notification / logs), which changes how invalid notification / logs options are reported.
2. Key format rule = BC break in a minor. Free keys such as api.token, a/b or a b used to work and are now refused at launch, and existing schedules can no longer be saved from the UI. The root cause is in process-bundle: ContextualOptionResolver builds its regex from the context keys without preg_quote() (that is what the zz)|x|(?:zz / a/b tests show). It should be fixed there; here the naming rule should only apply to the keys declared in form.context, which must be valid form field names anyway.
3. Form type: FQCN only. FORM_TYPE_ALIASES introduces a second naming scheme for the form types: a closed list of 35 entries to maintain, while any type (including a project-specific one) can already be given by its FQCN. It also requires symfony/doctrine-bridge only for the entity alias. I'd remove it and accept FQCNs only, as the Symfony form builder does and as in the draft of #160: resolveFormType() then only checks class_exists / FormTypeInterface / not a button, and symfony/doctrine-bridge can be dropped from composer.json (docs, changelog and tests to update). This also solves the entity issue: its data is the entity itself, converted through __toString(), i.e. its label rather than its identifier, and its default value cannot be written in YAML.
   The short names of the constraints (Choice, File...) are not concerned: that is the existing ConstraintLoader syntax. A test with a constraint given by its FQCN (e.g. a project-specific constraint) is missing though: it is documented but not covered.

Important

4. Default values of object types: the docs cover date / dateinterval (input: string), but not enum (a YAML scalar where the field expects an enum case). Either refuse it at resolution or document it.
5. Late configuration errors: an invalid field option gives a 500 on the launch page, and a non-convertible value gives a 500 after the user filled and submitted the form. At least the latter should be reported as a form error.
6. Process list: list.html.twig resolves the UI options of every process, so one invalid form configuration breaks the whole page, and every rendering triggers one deprecation per process using the deprecated options.

Minor

• ProcessConfigurationsManager grows to ~700 lines, mostly the launch form resolution: it could move to a dedicated (internal) resolver.
• Public API surface: getLaunchFormDefaults() is only used by the tests; buildLaunchFormDefaults(), the ui_options option of LaunchType and ContextValueNormalizer (instantiated with new in the controller) should be @internal.
• The declared context fields are required: true by default (Symfony default): a checkbox must then be checked (the dry_run example of #160 needs an explicit required: false). A false default for the declared context fields would be safer.
• The CHANGELOG entry is a single ~2000-character paragraph: it would be easier to read split into bullets.
• One 3k-line commit makes the review hard: splitting per point 1 would help.

🤖 Generated with Claude Code

[njoubert-cleverage]

This rejects keys that used to work (api.token, a/b, a b...) in the launch form and the schedules: BC break in a minor. The underlying problem is ContextualOptionResolver in process-bundle, which puts the context keys into a regex without preg_quote(); it should be fixed there. Here, the naming rule is only needed for the keys declared in form.context (form field names).

[clever-age-gtonon]

Reverted in eba7505: the free context pairs (launch form and schedules) accept any non-empty key again, as on main. The naming rule only applies to the keys declared in form.context (form field names).

[njoubert-cleverage]

I'd drop this alias table and accept FQCNs only for type (as the Symfony form builder and the draft of #160): one naming scheme, nothing to maintain, a project-specific type works the same way, and symfony/doctrine-bridge is no longer needed.

[clever-age-gtonon]

Done in 399d67b: the alias table is removed, type is the FQCN of a form type only (class_exists, FormTypeInterface, not a button), the short names are refused with an explicit message.

[njoubert-cleverage]

The data of an EntityType is the entity: through ContextValueNormalizer it becomes its __toString() (a label, not the identifier), and its default value cannot be written in YAML. Removing the aliases (see above) removes this one too.

[clever-age-gtonon]

Solved by 399d67b: no entity alias anymore. An EntityType can still be given by its FQCN; the docs describe the object data (must be \Stringable) and recommend a ChoiceType with scalar choices.

[njoubert-cleverage]

Only required for the entity alias: can be removed with FQCN-only types.

[clever-age-gtonon]

Removed in 399d67b.

[njoubert-cleverage]

Only used by the tests: new public API without a caller. Could be removed (or @internal), same question for buildLaunchFormDefaults().

[clever-age-gtonon]

Removed in ef621a2: getLaunchFormDefaults() and buildLaunchFormDefaults() are gone, the initial data is part of the launch form resolved by the new internal getLaunchFormOptions() / LaunchFormOptionsResolver; the launch_form option of LaunchType is internal.

[njoubert-cleverage]

Resolving only the requested option is a sensible change, but it is not part of #160 and changes how invalid notification / logs options are reported (no longer by the process list): it deserves its own issue/PR.

[clever-age-gtonon]

Reverted in f299867: the getters resolve the ui, notification and logs options together again, as on main. Moreover, since ef621a2 getUiOptions() no longer resolves form (see the review summary).

[njoubert-cleverage]

This is raised after the user filled and submitted the form, and ends as a 500. It would be friendlier as a form error (or detected earlier). Also, this class is instantiated with new in the controller: @internal?

[clever-age-gtonon]

Done: e63af6a reports a value that cannot be converted as an error of its field (input, declared field or free pairs), the form is displayed again and nothing is dispatched. ContextValueNormalizer is @internal (b66b4b4). Besides, the launch forms are now checked each time the container is built, by a cache warmer that resolves them and builds them with the form factory of the application: form type options, default values, constraint validators (eef9ada, 8883fe1).

[njoubert-cleverage]

According to symfony best pratices for bundles, services should not use autowiring or autoconfiguration. Instead, all services should be defined explicitly.