## Problem/Motivation Many ECA plugins support a special `_eca_token` option — labeled **"Defined by token"** in the UI — which defers a value to a companion token at runtime. It is a documented, first-class feature. For example `eca_render_markup`'s `mode` lists: ``` - `_eca_token` — Defined by token When using the "Defined by token" option, make sure there is a token with this name: eca_render_markup_mode ``` and the plugins branch on it explicitly, for example in `modules/content/src/Plugin/Action/NewEntity.php`: ```php line 160: if ($this->configuration['type'] === '_eca_token') { line 200: if ($config['type'] === '_eca_token') { line 218: elseif ($langcode === '_eca_token') { ``` However, the typed-config `Choice` constraints do not include the sentinel. In `modules/content/config/schema/eca_content.schema.yml`: ```yaml action.configuration.eca_new_entity: mapping: type: type: string label: 'Entity Type' constraints: Choice: callback: '\Drupal\eca\Validation\EcaConstraintCallbacks::getAllValidContentEntityTypesAndBundles' ``` and `EcaConstraintCallbacks::getAllValidContentEntityTypesAndBundles()` (`src/Validation/EcaConstraintCallbacks.php:50-52`) returns only real entity type and bundle keys: ```php return array_keys(\Drupal::service('eca.service.content_entity_types')->getTypesAndBundles()); ``` So configuration that uses a feature the plugin explicitly implements is reported invalid: ``` The value you selected is not a valid choice. ``` The same shape affects `eca_token_load_entity.entity_type` and `eca_render.action_base.mode`, and likely every other `Choice`-constrained key that offers "Defined by token". ## Steps to reproduce 1. Add an `eca_new_entity` action to an ECA model. 2. Set **Entity Type** to **"Defined by token"** in the UI, and add the companion `eca_new_entity_type` token setter. 3. Validate the resulting `eca.eca.*` config against its typed schema. **Result:** `The value you selected is not a valid choice.` **Expected:** No violation — the model is correct and works at runtime. ## Proposed resolution **Updated after a full audit of the sentinel surface. The original proposal below the line was based on an unsound heuristic; the corrected findings are authoritative and each carries file:line evidence.** ### The authoritative source is the form flag, not the branching The report originally suggested using "plugins that branch on `_eca_token`" as the authoritative list. That under-reports materially. The real declaration is the form-element flag `'#eca_token_select_option' => TRUE` — 54 declaration sites across 47 files — consumed at exactly one point, `src/Plugin/ECA/PluginFormTrait.php:77-84`, which is called from `src/Service/Actions.php:226`, `src/Plugin/ECA/Condition/ConditionBase.php:204` and `src/Plugin/ECA/Event/EventBase.php:212`. Branch-based enumeration misses four classes of case: - **Base-class fan-out** — one branch, many plugins. `RenderElementActionBase.php:221` covers 20 plugins; `StringComparisonBase.php:195,204` covers 11; also `CacheActionBase.php:50`, `ListAddBase.php:113`, `ListRemoveBase.php:136`, `FieldUpdateActionBase.php:111`, `FormAddFieldActionBase.php:119`. - **A service, not a plugin** — `modules/content/src/Service/EntityLoader.php:138,147,201` supplies `from`, `entity_type` and `langcode` by service injection. Grepping the class name finds zero consumers. This is where this report's own `eca_token_load_entity.entity_type` comes from. - **A trait** — `modules/miscellaneous/src/Plugin/RouteTrait.php:67`. - **Branch variable name differs from the config key** — `EntityFieldIsAccessible.php:45` branches on `$field_op` for key `operation`; `Cacheability.php:90` branches on `$key` for key `cache_type`. Two structural traps also defeat per-plugin grepping: schema **type inheritance** (`eca_render.action_base`, `eca_render.schema.yml:108`, owns `mode` for 20 plugins and the key appears in no per-plugin section) and **derivative section names** (`action.configuration.eca_render_views:views` and similar). ### Measured scope 101 `(schema-section, key)` pairs carry the sentinel: | | count | |---|---| | Has a `Choice` constraint — **broken today** | **69** | | Has `Choice` and already accepts the sentinel | 7 | | No `Choice` constraint — latent, not broken | 25 | The 7 already-correct keys sit under `EcaConstraintCallbacks::getAllValidLangcodes` (`src/Validation/EcaConstraintCallbacks.php:19`), which already returns both `_eca_token` **and** `''`. That is the existing precedent. ### The sentinel never travels alone `PluginFormTrait.php:80` also injects `'' => 'undefined'` whenever the element's `#required` is falsy. **43 of the 69 broken keys are non-required and currently accept neither value**, so a fix that adds only `_eca_token` leaves most of the defect in place. But `''` must not be blanket-added: 25 sentinel keys carry `NotBlank` beside `Choice`, and all 25 are `#required`. Adding `''` there would create a value the UI offers and validation rejects — the same defect in reverse. The empty-string must be gated on requiredness exactly as the trait gates it. ### Why a callback wrapper cannot work The originally proposed `::withEcaToken()` wrapper is not implementable. Symfony's `ChoiceValidator` invokes `$constraint->callback` with **no arguments** (`vendor/symfony/validator/Constraints/ChoiceValidator.php:48-58`), so a shared wrapper has no way to know which underlying list to wrap. It would also be useless for the 20 inline enums, impossible for `[\Drupal\user\Entity\Role, getAllValidPermissions]` (`eca_user.schema.yml:77,91` — Drupal core, uneditable), and unable to resolve the one genuine callback collision: `\Drupal\eca_views\Plugin\Action\ViewsQuery::getAllValidViews` is shared by `eca_views_query.view_id` and `eca_views_export.view_id`, which offer the sentinel, and `eca.event.views_base.view_id` (`eca_views.schema.yml:9`), an event which must not. ### The resolution Introduce a dedicated **constraint plugin**, `EcaChoice`, extending Symfony's `Choice`, whose validator resolves the declared choices — inline or callback — appends `_eca_token`, appends `''` when the key is not required, and delegates to the parent. Per key the change is one word: `Choice:` becomes `EcaChoice:`. This states "this key offers Defined by token" once, declaratively, per key, and resolves every hard case: inline enums stay inline, the shared callbacks stay untouched, core stays untouched, and the `views_base` collision dissolves because that key simply keeps plain `Choice`. Requiredness is read from the `NotBlank` constraint already present on the key rather than declared a second time in YAML. `#required` and `NotBlank` agree on 75 of the 76 affected locations; the single outlier, `eca_render.action_base.mode` (`#required` with no `NotBlank`), is corrected by adding `NotBlank`. ### Guard against recurrence The validation callbacks are **not** the source of the form `#options` — the two lists are independent, which is precisely how they drifted apart. A kernel test therefore walks every event, condition and action form, finds all elements carrying `#eca_token_select_option`, and asserts each corresponding schema key accepts `_eca_token`, and accepts `''` exactly when the element is not required. This turns the fix into a permanent invariant rather than a one-off repair. ### Known to be out of scope - `eca_render.action_base.name` — no `Choice` at all; it is `type: machine_name` (`eca_render.schema.yml:112-114`), pattern validation. Tracked in #3590374. - The 25 latent keys with no `Choice` constraint — they reject nothing. - **Four `type: integer` keys** where the sentinel is rejected by `PrimitiveTypeConstraintValidator` independently of `Choice`: `eca_route_match.request`, `eca_token_load_route_param.request`, `eca_write_log_message.severity`, `eca_enqueue_task_delayed.delay_unit`. Same class as the `machine_name` case above; needs its own issue. - Several `eca_render_*` actions have no config schema section at all (`eca_render_markup`, `eca_render_lazy`, `eca_render_file_contents`, and the `filter` / `image` / `responsive_image` derivatives), so their entire configuration is unvalidated. Separate, larger issue. ## Remaining tasks - [x] Audit which config keys expose the `_eca_token` option - [x] Establish the correct enumeration source and the `''` pairing rule - [ ] Add the `EcaChoice` constraint and route the 69 broken keys through it - [ ] Add the kernel guard test covering the sentinel and the empty-string rule - [ ] Review and merge ## User interface changes None. ## Data model changes None. --- **Environment:** ECA 3.1.5, Drupal 11. AI-Generated: Yes (Used OpenCode to analyze typed-config validation output on a production site, trace the sentinel handling through the plugin and validation source, and draft this report. All file and line references were verified against the installed code.) > Change record: [#3616767](https://www.drupal.org/node/3616767)