[DOCS] Document the form state and validation configuration events

Documentation/ApiOverview/Events/Events/Form/AfterFormDefinitionValidationConfigurationIsBuiltEvent.rst

@@ -0,0 +1,42 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; AfterFormDefinitionValidationConfigurationIsBuiltEvent
+
+..  _AfterFormDefinitionValidationConfigurationIsBuiltEvent:
+
+========================================================
+`AfterFormDefinitionValidationConfigurationIsBuiltEvent`
+========================================================
+
+..  versionadded:: 15.0
+    :changelog: feature-109849-1716115200
+
+    The event replaces the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['buildFormDefinitionValidationConfiguration']`.
+
+The event
+:php:`\TYPO3\CMS\Form\Event\AfterFormDefinitionValidationConfigurationIsBuiltEvent`
+is dispatched after the validation configuration of the form editor has
+been built for a prototype. The form editor only saves the properties that
+this configuration allows. A listener can add property paths for a custom
+inspector editor that does not declare its paths in the YAML configuration,
+for example with `propertyPath`.
+
+..  _AfterFormDefinitionValidationConfigurationIsBuiltEvent-example:
+
+Example: Allow the form editor to save a custom property
+========================================================
+
+The following listener allows the form editor to save the property
+`properties.my.custom.property` of the custom form element
+`MyCustomElement`. A custom inspector editor sets this property without a
+`propertyPath` in the YAML configuration:
+
+..  literalinclude:: _AfterFormDefinitionValidationConfigurationIsBuiltEvent/_CustomPropertyPathListener.php
+    :caption: EXT:my_extension/Classes/EventListener/CustomPropertyPathListener.php
+
+..  _AfterFormDefinitionValidationConfigurationIsBuiltEvent-api:
+
+API
+===
+
+..  typo3:api-class:: \TYPO3\CMS\Form\Event\AfterFormDefinitionValidationConfigurationIsBuiltEvent

Documentation/ApiOverview/Events/Events/Form/AfterFormStateInitializedEvent.rst

@@ -0,0 +1,41 @@
+..  include:: /Includes.rst.txt
+..  index:: Events; AfterFormStateInitializedEvent
+
+..  _AfterFormStateInitializedEvent:
+
+================================
+`AfterFormStateInitializedEvent`
+================================
+
+..  versionadded:: 15.0
+    :changelog: feature-109811-1759230000
+
+    The event replaces the removed hook
+    :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/form']['afterFormStateInitialized']`
+    and the interface
+    :php:`\TYPO3\CMS\Form\Domain\Runtime\FormRuntime\Lifecycle\AfterFormStateInitializedInterface`.
+
+The event :php:`\TYPO3\CMS\Form\Event\AfterFormStateInitializedEvent` is
+dispatched after the form runtime has restored the form state from the
+request. The submitted values and the form definition are both available.
+A listener can read and change the form state through `$formRuntime` and
+read the request in `$request`.
+
+..  _AfterFormStateInitializedEvent-example:
+
+Example: Fill a form field from a query parameter
+=================================================
+
+The following listener writes the query parameter `campaign` into the form
+field `campaign`, unless the field already has a value. The form then sends
+the campaign that the visitor came from along with the other values:
+
+..  literalinclude:: _AfterFormStateInitializedEvent/_CampaignFromQueryListener.php
+    :caption: EXT:my_extension/Classes/EventListener/CampaignFromQueryListener.php
+
+..  _AfterFormStateInitializedEvent-api:
+
+API
+===
+
+..  typo3:api-class:: \TYPO3\CMS\Form\Event\AfterFormStateInitializedEvent

Documentation/ApiOverview/Events/Events/Form/Index.rst

@@ -9,11 +9,13 @@ Form
 The following list contains :ref:`PSR-14 events <eventdispatcher>`
 in EXT:form.
 
-..  versionchanged:: 14.0
-    All former hooks of EXT:form are now available as PSR-14 events.
+..  versionchanged:: 15.0
+    :changelog: breaking-109811-1759230001
 
-    Some `Legacy hooks <https://docs.typo3.org/permalink/typo3-cms-form:apireference-events-legacy-hooks>`_
-    are still supported.
+    The last hooks of EXT:form, `afterFormStateInitialized` and
+    `buildFormDefinitionValidationConfiguration`, were replaced by
+    PSR-14 events. See also
+    `Breaking: #109849 - Removed "buildFormDefinitionValidationConfiguration" hook <https://docs.typo3.org/permalink/changelog:breaking-109849-1716115200>`_.
 
 
 **Contents:**

Documentation/ApiOverview/Events/Events/Form/_AfterFormDefinitionValidationConfigurationIsBuiltEvent/_CustomPropertyPathListener.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Form\Event\AfterFormDefinitionValidationConfigurationIsBuiltEvent as Event;
+
+final readonly class CustomPropertyPathListener
+{
+  #[AsEventListener(
+    identifier: 'my-extension/custom-property-path',
+  )]
+  public function __invoke(Event $event): void
+  {
+    $configuration = $event->getConfiguration();
+    $element = $configuration['formElements']['MyCustomElement'] ?? [];
+    // Allow the form editor to write a property that a custom
+    // inspector editor sets without a "propertyPath"
+    $element['additionalPropertyPaths'][] = 'properties.my.custom.property';
+    $configuration['formElements']['MyCustomElement'] = $element;
+    $event->setConfiguration($configuration);
+  }
+}

Documentation/ApiOverview/Events/Events/Form/_AfterFormStateInitializedEvent/_CampaignFromQueryListener.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\EventListener;
+
+use TYPO3\CMS\Core\Attribute\AsEventListener;
+use TYPO3\CMS\Form\Event\AfterFormStateInitializedEvent;
+
+final readonly class CampaignFromQueryListener
+{
+  #[AsEventListener(
+    identifier: 'my-extension/campaign-from-query',
+  )]
+  public function __invoke(AfterFormStateInitializedEvent $event): void
+  {
+    $formState = $event->formRuntime->getFormState();
+    if ($formState === null) {
+      return;
+    }
+    // Remember the campaign the visitor came from, unless already set
+    $campaign = $event->request->getQueryParams()['campaign'] ?? '';
+    if ($campaign !== '' && $formState->getFormValue('campaign') === null) {
+      $formState->setFormValue('campaign', $campaign);
+    }
+  }
+}