TYPO3 v15 dev-main snapshot ()

Documentation/Changelog/14.0/Feature-107256-PSR-14EventToModifyOptionsInEmailFinisher.rst

@@ -0,0 +1,89 @@
+..  include:: /Includes.rst.txt
+
+..  _feature-107256-1754918566:
+
+==================================================================
+Feature: #107256 - PSR-14 event to modify options in EmailFinisher
+==================================================================
+
+See :issue:`107256`
+
+Description
+===========
+
+A new PSR-14 event :php:`\TYPO3\CMS\Form\Event\BeforeEmailFinisherInitializedEvent`
+has been introduced. This event is dispatched before the
+:php-short:`\TYPO3\CMS\Form\Finisher\EmailFinisher` is initialized and allows
+listeners to modify the finisher options dynamically.
+
+This enables developers to customize email behavior programmatically, such as:
+
+*   Setting alternative recipients based on frontend user permissions
+*   Modifying the email subject or content dynamically
+*   Replacing recipients with developer email addresses in test environments
+*   Adding or removing CC or BCC recipients conditionally
+*   Customizing reply-to addresses
+
+The event provides access to both the finisher context (read-only) and the
+options array, allowing for flexible manipulation of the email configuration.
+
+To modify the :php-short:`\TYPO3\CMS\Form\Finisher\EmailFinisher` options, the
+following methods are available:
+
+*   :php:`getFinisherContext()`: Returns the
+    :php-short:`\TYPO3\CMS\Form\Domain\Finishers\FinisherContext` containing
+    form runtime and request information
+*   :php:`getOptions()`: Returns the current finisher options array
+*   :php:`setOptions()`: Allows setting the modified options array
+
+Example
+=======
+
+The corresponding event listener class:
+
+..  code-block:: php
+    :caption: Example event listener class
+
+    <?php
+
+    namespace MyVendor\MyExtension\Form\EventListener;
+
+    use TYPO3\CMS\Core\Attribute\AsEventListener;
+    use TYPO3\CMS\Form\Event\BeforeEmailFinisherInitializedEvent;
+
+    final class BeforeEmailFinisherInitializedEventListener
+    {
+        #[AsEventListener('my_extension/form/modify-email-finisher-options')]
+        public function __invoke(BeforeEmailFinisherInitializedEvent $event): void
+        {
+            $options = $event->getOptions();
+            $context = $event->getFinisherContext();
+
+            // Overwrite recipients based on FormContext
+            if ($context->getFormRuntime()->getFormDefinition()->getIdentifier() === 'my-form-123') {
+                $options['recipients'] = ['user@example.org' => 'John Doe'];
+            }
+
+            // Modify subject dynamically
+            $options['subject'] = 'Custom subject: ' . ($options['subject'] ?? '');
+
+            // Clear CC and BCC recipients
+            $options['replyToRecipients'] = [];
+            $options['blindCarbonCopyRecipients'] = [];
+
+            $event->setOptions($options);
+        }
+    }
+
+Impact
+======
+
+It is now possible to dynamically modify
+:php-short:`\TYPO3\CMS\Form\Finisher\EmailFinisher` options before email
+processing begins, using the new PSR-14 event
+:php-short:`\TYPO3\CMS\Form\Event\BeforeEmailFinisherInitializedEvent`. This
+provides developers with full control over email configuration without needing
+to extend or override the
+:php-short:`\TYPO3\CMS\Form\Finisher\EmailFinisher` class.
+
+..  index:: PHP-API, ext:form