clever-age-gtonon · Oct 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@ Latest
 ------
 
 ## Changes
+* [#160](https://github.com/cleverage/ui-process-bundle/issues/160) Launch form: new `form` UI option declaring the `input` field and the context fields (`form.input`, `form.context.<key>`: `type`, a form type alias such as `text`, `choice`, `checkbox`, `date`, `entity`... or a form type FQCN; `options`, the form type options, with `constraints`; `default`, the initial value), whether free key/value context pairs are allowed (`form.allow_extra_context`, default `true`) and the constraints of the whole form (`form.constraints`). The typed values of the form are converted into process values after the validation by the new `ContextValueNormalizer` (enums, dates, date intervals, `Stringable` objects; files are refused in the context). New `ProcessConfigurationsManager::getLaunchFormDefaults()`; `getUiOptions()` returns the effective `form` option. New `reserved_keys` option of `ProcessContextType`: a free context pair whose key is a declared field is reported as a validation error. The free context pairs of the launch form are now named `launch[context][extra][<index>][key|value]` (was `launch[context][<index>][key|value]`). The `context` child of `LaunchType` is now a compound `FormType` (form theme blocks `_launch_context_extra_entry_*`), and the duplicated keys of `default.context` are merged (the last one wins). The key of a free context pair (launch form and schedules) must be a valid form field name, not only digits (new `key_constraints` option of `ProcessContextType`). The `execution_user` context value is always the email of the connected user (reserved in the free pairs of the launch form and of the schedules, and in `form.context`; constant `ProcessExecuteMessage::EXECUTION_USER_KEY`, constraint `ProcessContextType::createExecutionUserConstraint()`). Existing schedules with a key that is no longer valid keep running, but must be renamed to be saved from the UI. `ProcessConfigurationsManager` resolves only the requested option (an invalid launch form no longer breaks the notifications nor the purge of the logs; conversely, invalid `notification` or `logs` options are no longer reported by the process list, only when used: at the end of an execution in the worker, and by the purge command), and the launch action resolves the UI options once (new `ui_options` option of `LaunchType`, `ProcessConfigurationsManager::buildLaunchFormDefaults()`). Require `symfony/doctrine-bridge` (`entity` type alias). Deprecate the `entrypoint_type` (use `form.input.type`), `default` (use `form.input.default` and `form.context.<key>.default`) and `constraints` (use `form.constraints`) UI options, folded into `form` until 4.0, a deprecation being triggered each time the UI options of such a process are resolved. Add documentation, an upgrade guide and tests.
 * [#158](https://github.com/cleverage/ui-process-bundle/issues/158) CI: test the lowest versions allowed by `composer.json` (`--prefer-lowest`, PHP 8.2). Require `symfony/scheduler` ^6.4.44 || ^7.4.17 || ^8.1.5: the `every` expressions validation (`EveryExpressionValidator`) relies on the `PeriodicalTrigger` rejecting the intervals that do not move the run date forward or resolve to zero seconds (older versions loop forever on e.g. "yesterday", and fail with a `TypeError` on an invalid expression). `ProcessExecutionDurationFilter`: the number of seconds is cast to an integer and inlined in the DQL instead of being bound as a parameter (#111): with DBAL 3, the SQLite platform puts the `SECOND` intervals inside a string literal, so the parameter was never bound ("column index out of range" error on SQLite with DBAL 3).
 * [#156](https://github.com/cleverage/ui-process-bundle/issues/156) `LogRecord::contextIsEmpty()` (deprecated since v3.1, use `hasContextInfo()`) triggers a deprecation at runtime with `trigger_deprecation()` (`symfony/deprecation-contracts`, now required). Add tests.
 * [#154](https://github.com/cleverage/ui-process-bundle/issues/154) Add a `.gitattributes`: the development files (`.docker/`, `.github/`, `tests/`, quality tools and PHPUnit configurations, `Makefile`) are no longer part of the archive installed by Composer (`dist`), remove the unused `package.json` (Webpack Encore leftover of the Symfony skeleton: no `webpack.config.js`, no `assets/`).

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,6 +1,98 @@
 Upgrade Guide
 =============
 
+## v3.3
+
+### Deprecated UI options of the launch form
+
+The `entrypoint_type`, `default` and `constraints` UI options are deprecated in favor of the new `form` option (see
+[process UI options](docs/reference/02-process_ui_options.md#form-fields)), and will be removed in 4.0:
+
+| Deprecated option   | Replacement                                                                       |
+|---------------------|-----------------------------------------------------------------------------------|
+| `entrypoint_type`   | `form.input.type`                                                                 |
+| `default.input`     | `form.input.default`                                                              |
+| `default.context`   | `form.context.<key>.default` (or a free pair with `form.allow_extra_context`)     |
+| `constraints`       | `form.constraints`                                                                |
+
+```yaml
+# Before (3.2)
+options:
+    ui:
+        ui_launch_mode: form
+        entrypoint_type: file
+        default:
+            context:
+                - key: delimiter
+                  value: ','
+        constraints:
+            - Collection:
+                  fields:
+                      input:
+                          - File: { extensions: [csv] }
+                      context:
+                          - Collection:
+                                fields:
+                                    delimiter:
+                                        - Choice: { choices: [',', ';'] }
+
+# After (3.3)
+options:
+    ui:
+        ui_launch_mode: form
+        form:
+            input:
+                type: file
+                options:
+                    constraints:
+                        - File:
+                              # A CSV file is often detected as "text/plain" (semicolon delimiter, few lines): allow it explicitly
+                              extensions:
+                                  csv: ['text/csv', 'text/plain', 'application/csv', 'text/x-csv', 'text/x-comma-separated-values']
+            context:
+                delimiter:
+                    type: choice
+                    default: ','
+                    options:
+                        choices: { 'Comma (,)': ',', 'Semicolon (;)': ';' }
+```
+
+- Mixing a deprecated option and its replacement (e.g. `entrypoint_type` and `form.input`, or `constraints` and
+  `form.constraints`) raises an `InvalidOptionsException`.
+- The HTML names of the free context pairs of the launch form change from `launch[context][<index>][key|value]` to
+  `launch[context][extra][<index>][key|value]`: update the functional tests of your application that submit this
+  form.
+- The `context` child of `LaunchType` is now a compound `FormType` (the declared fields, then the `extra`
+  `CollectionType` of the free pairs) instead of a `CollectionType`: update the form theme blocks of your application
+  (`_launch_context_entry_*` becomes `_launch_context_extra_entry_*`), the form type extensions and the code using
+  `$form->get('context')`.
+- The duplicated keys of `default.context` are merged, the last pair wins (two pairs were displayed).
+- A process using a deprecated option triggers its deprecations each time its UI options are resolved (process list,
+  launch form, executions list): expect them in the deprecation logs until the process is migrated.
+
+### Context keys of the launch form and the schedules
+
+- The key of a free context pair (launch form and schedules) must contain letters, digits, `_`, `-` and `:`, start with
+  a letter, a digit or `_`, and not be only digits, like a declared context key.
+- The `execution_user` context value is always the email of the connected user when a process is launched from the
+  UI: a free pair `execution_user` is refused in the launch form and in the schedules, and `execution_user` cannot be
+  declared in `form.context`.
+- Existing schedules whose context contains a key that is no longer valid (or `execution_user`) keep running unchanged:
+  the cron does not validate their context. But they cannot be saved from the UI until the key is renamed (or the
+  pair removed), even to change another field: rename it, and update the process accordingly (e.g. its `{{ key }}`
+  contextualized options), as renaming the key changes the context received by the process. Enabling or disabling a
+  schedule from the list is not affected (no form).
+- The same applies to the deprecated `default.context` option: a pair whose key is not valid pre-fills a row that
+  prevents the launch form from being submitted, until the user changes it; the process configuration is not
+  reported as invalid. Rename the key (or move it to `form.context`).
+
+### Invalid notification and logs options
+
+`ProcessConfigurationsManager` now resolves only the requested option: invalid `notification` or `logs` options of a
+process are no longer reported by the process list. They are only reported when they are used: at the end of an
+execution, by the notifier in the Messenger worker (no notification is sent), and by the
+`cleverage:ui-process:purge-logs` command.
+
 ## v3.0
 
 ### Import routes

diff --git a/composer.json b/composer.json
@@ -53,6 +53,7 @@
     "symfony/console": "^6.4 || ^7.4 || ^8",
     "symfony/dependency-injection": "^6.4 || ^7.4 || ^8",
     "symfony/deprecation-contracts": "^2.5 || ^3",
+    "symfony/doctrine-bridge": "^6.4 || ^7.4 || ^8",
     "symfony/doctrine-messenger": "^6.4 || ^7.4 || ^8",
     "symfony/event-dispatcher": "^6.4 || ^7.4 || ^8",
     "symfony/event-dispatcher-contracts": "^3",

diff --git a/docs/cookbooks/form_file_upload.md b/docs/cookbooks/form_file_upload.md
@@ -17,25 +17,24 @@ clever_age_process:
                     source: CSV upload
                     target: Logs
                     ui_launch_mode: form
-                    entrypoint_type: file
-                    default:
+                    form:
+                        input:
+                            type: file
+                            options:
+                                label: CSV file
+                                constraints:
+                                    - NotNull: ~
+                                    - File:
+                                          # A CSV file is often detected as "text/plain" (semicolon delimiter, few lines): allow it explicitly
+                                          extensions:
+                                              csv: ['text/csv', 'text/plain', 'application/csv', 'text/x-csv', 'text/x-comma-separated-values']
                         context:
-                            - key: delimiter
-                              value: ','
-                    constraints:
-                        - Collection:
-                              fields:
-                                  input:
-                                      - NotNull: ~
-                                      - File:
-                                            extensions: [csv]
-                                  context:
-                                      - Collection:
-                                            fields:
-                                                delimiter:
-                                                    - Choice:
-                                                          choices: [',', ';']
-                                                          message: 'delimiter context must be , or ;. {{ value }} given.'
+                            delimiter:
+                                type: choice
+                                default: ','
+                                options:
+                                    label: Delimiter
+                                    choices: { 'Comma (,)': ',', 'Semicolon (;)': ';' }
             tasks:
                 log_file:
                     service: '@CleverAge\ProcessBundle\Task\Reporting\LoggerTask'
@@ -62,17 +61,16 @@ clever_age_process:
 How it works:
 - `ui_launch_mode: form` makes the "Launch" action of the process list open a form instead of a confirmation modal
   (see [launch modes](../reference/02-process_ui_options.md#launch-modes)).
-- `entrypoint_type: file` turns the `input` field into a file upload. As the process has an `entry_point`, the field
-  is required. The uploaded file is saved in the `upload_directory` directory and its path is sent to the
-  `log_file` task (see [launch form](../reference/02-process_ui_options.md#launch-form)).
-- `default.context` pre-fills a `delimiter` line in the context collection
-  (see [default values](../reference/02-process_ui_options.md#default-values)). It is injected into the
-  `InputCsvReaderTask` through the `{{ delimiter }}` contextualized option, exactly like `-c delimiter:";"` on the
-  console.
-- `constraints` validate the whole form data (`input` and `context`): the process is not queued while the file is not
-  a CSV or the delimiter is not `,` or `;` (see [constraints](../reference/02-process_ui_options.md#constraints)).
-  As the `Collection` constraint rejects extra fields, users cannot add other context values: add
-  `allowExtraFields: true` to allow them.
+- `form.input` with `type: file` turns the `input` field into a file upload. As the process has an `entry_point`, the
+  field is required (HTML attribute); its `NotNull` and `File` constraints are checked by the server: the process is
+  not queued while no file is uploaded or the file is not a CSV, and the error is displayed under the field. The
+  uploaded file is saved in the `upload_directory` directory and its path is sent to the `log_file` task (see
+  [launch form](../reference/02-process_ui_options.md#launch-form)).
+- `form.context.delimiter` adds a `delimiter` select, pre-selected on `,`
+  (see [form fields](../reference/02-process_ui_options.md#form-fields)). A value outside of the choices is refused by
+  the field itself. The selected value is injected into the `InputCsvReaderTask` through the `{{ delimiter }}`
+  contextualized option, exactly like `-c delimiter:";"` on the console.
+- Users can still add free key/value pairs to the context: set `form.allow_extra_context: false` to forbid them.
 - On submit, a message is sent to the `execute_process` transport, so a `messenger:consume execute_process` worker
   must be running (see [messenger](../reference/08-messenger.md)). The connected user email is added to the context
   as `execution_user`.
@@ -92,4 +90,4 @@ curl --location 'https://your-domain.com/http/process/execute' \
 --form 'context[delimiter]=";"'
 ```
 
-Note that the launch form `constraints` are not applied to HTTP API calls.
+Note that the launch form fields and constraints are not applied to HTTP API calls.