TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:24 +02:00
commit aad9daaefd
1506 changed files with 94005 additions and 0 deletions
@@ -0,0 +1,268 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-customfinisherimplementations:
+
+===============
+Custom finisher
+===============
+
+..  include:: /Includes/_NoteFinisher.rst
+
+..  contents:: Table of contents
+    :local:
+
+..  _concepts-finishers-custom-howtowrite:
+
+Write a custom finisher
+=======================
+
+To make your finisher configurable by users in the backend form editor, see
+:ref:`here <concepts-finishers-customfinisherimplementations-extend-gui>`.
+
+Add a new finisher to the form configuration prototype by defining a
+`finishersDefinition`. Set the `implementationClassName` property to your new implementation class.
+
+..  literalinclude:: _codesnippets/_finishersDefinition.yaml
+    :caption: EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
+
+`Register <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-custom-extend-gui-configuration>`_
+your custom form definition.
+
+Add options to your finisher with the `options` property. Options
+are default values which can be overridden in the `form definition`.
+
+..  _concepts-finishers-custom-default-value:
+
+Define default values
+---------------------
+
+..  literalinclude:: _codesnippets/_CustomFinisher.yaml
+    :caption: EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
+
+..  _concepts-finishers-custom-option-override:
+
+Override options using the `form definition`
+--------------------------------------------
+
+..  literalinclude:: _codesnippets/_my_form.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+A finisher must implement :php-short:`TYPO3\CMS\Form\Domain\Finishers\FinisherInterface`
+and should extend :php-short:`TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher`.
+In doing so, in the logic of the
+finisher the method `executeInternal()` will be called first.
+
+..  _concepts-finishers-customfinisherimplementations-accessingoptions:
+
+Accessing finisher options
+==========================
+
+If your finisher class extends :php-short:`TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher`,
+you can access the option values in the finisher using method `parseOption()`:
+
+..  code-block:: php
+
+    $yourCustomOption = $this->parseOption('yourCustomOption');
+
+`parseOption()` looks for 'yourCustomOption' in your
+`form definition`.
+
+..  literalinclude:: _codesnippets/_CustomFinisher.yaml
+    :caption: EXT:my_site_package/Classes/Domain/Finishers/CustomFinisher.yaml
+
+If it can't find it, `parseOption()` checks
+
+1.  for a default value in the `prototype` configuration,
+
+2.  for `$defaultOptions` inside your finisher class:
+
+
+
+If it doesn't find anything, `parseOption()` returns `null`.
+
+If it finds the option, the process checks whether the option value will
+access :ref:`FormRuntime values <concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`.
+If the `FormRuntime` returns a positive result, it is checked whether the
+option value :ref:`can access values of preceding finishers <concepts-finishers-customfinisherimplementations-finishercontext-sharedatabetweenfinishers>`.
+At the end, it :ref:`translates the finisher options <concepts-frontendrendering-translation-finishers>`.
+
+..  _concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor:
+
+Accessing form runtime values
+=============================
+
+You can populate finisher options with
+submitted form values using the `parseOption()` method.
+You can access values of the `FormRuntime` and therefore values in every
+form element by encapsulating option values with `{}`. Below, if there is a
+form element with the `identifier` 'subject', you can access the value
+in the finisher configuration:
+
+..  literalinclude:: _codesnippets/_my_form_extended.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  code-block:: php
+
+    // $yourCustomOption contains the value of the form element with the
+    // identifier 'subject'
+    $yourCustomOption = $this->parseOption('yourCustomOption');
+
+You can use `{__currentTimestamp}` as an option value to return the
+current UNIX timestamp.
+
+..  _concepts-finishers-customfinisherimplementations-finishercontext:
+
+Finisher Context
+================
+
+The :php-short:`TYPO3\CMS\Form\Domain\Finishers\FinisherContext` class takes care of
+transferring a finisher context to each finisher. If your finisher class extends
+:php-short:`TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher` the
+finisher context will be available via:
+
+..  code-block:: php
+
+    $this->finisherContext
+
+The  `cancel` method prevents the execution of successive finishers:
+
+..  code-block:: php
+
+    $this->finisherContext->cancel();
+
+The method `getFormValues` returns the submitted form values.
+
+..  code-block:: php
+
+    $this->finisherContext->getFormValues();
+
+The method `getFormRuntime` returns the `FormRuntime`:
+
+..  code-block:: php
+
+    $this->finisherContext->getFormRuntime();
+
+..  _concepts-finishers-customfinisherimplementations-finishercontext-sharedatabetweenfinishers:
+
+Share data between finishers
+============================
+
+The method `getFinisherVariableProvider` returns an
+object (:php-short:`TYPO3\CMS\Form\Domain\Finishers\FinisherVariableProvider`) which allows you
+to store data and transfer it to other finishers. The data
+can be easily accessed programmatically or inside your configuration:
+
+..  code-block:: php
+
+    $this->finisherContext->getFinisherVariableProvider();
+
+The data is stored in :php-short:`TYPO3\CMS\Form\Domain\Finishers\FinisherVariableProvider` and is accessed
+by a user-defined 'finisher identifier' and a custom option value path. The
+name of the 'finisher identifier' should consist of the name of the finisher
+without the 'Finisher' appendix. If your finisher class extends
+:php-short:`TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher`, the finisher
+identifier name is stored in the following variable:
+
+..  code-block:: php
+
+    $this->shortFinisherIdentifier
+
+For example, if the name of your finisher class is 'CustomFinisher', this
+variable will contain 'Custom'.
+
+There are 4 methods to access and manage data in the `FinisherVariableProvider`:
+
+*   Add data:
+
+    ..  code-block:: php
+
+        $this->finisherContext->getFinisherVariableProvider()->add(
+            $this->shortFinisherIdentifier,
+            'unique.value.identifier',
+            $value
+        );
+
+*   Get data:
+
+    ..  code-block:: php
+
+        $this->finisherContext->getFinisherVariableProvider()->get(
+            $this->shortFinisherIdentifier,
+            'unique.value.identifier',
+            'default value'
+        );
+
+*   Check the existence of data:
+
+    ..  code-block:: php
+
+        $this->finisherContext->getFinisherVariableProvider()->exists(
+            $this->shortFinisherIdentifier,
+            'unique.value.identifier'
+        );
+
+*   Delete data:
+
+    ..  code-block:: php
+
+        $this->finisherContext->getFinisherVariableProvider()->remove(
+            $this->shortFinisherIdentifier,
+            'unique.value.identifier'
+        );
+
+In this way, finishers can access `FinisherVariableProvider` data programmatically.
+However, it is also possible to access `FinisherVariableProvider` data using form configuration.
+
+Assuming that a finisher called 'Custom' adds data to a `FinisherVariableProvider`:
+
+..  code-block:: php
+
+    $this->finisherContext->getFinisherVariableProvider()->add(
+        $this->shortFinisherIdentifier,
+        'unique.value.identifier',
+        'Wouter'
+    );
+
+other finishers can access the value 'Wouter' by setting
+`{Custom.unique.value.identifier}` in the form definition file.
+
+
+..  literalinclude:: _codesnippets/_my_form_custom.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _concepts-finishers-customfinisherimplementations-extend-gui:
+
+Add finisher to backend UI
+==========================
+
+After registering  a new finisher in the yaml form definition file, you can also
+add it to the backend form editor for your backend users ( `formEditor:`
+section below) to work with in the GUI:
+
+..  literalinclude:: _codesnippets/_backend-ui.yaml
+    :caption: EXT:my_site_package/Configuration/Form/CustomFormSetup.yaml
+    :linenos:
+
+..  important::
+
+    Make sure to define an  `iconIdentifier` in the `finishersDefinition` of your
+    finisher, otherwise the button to remove the finisher from the
+    form will not be visible.
+
+..  _concepts-finishers-custom-extend-gui-configuration:
+
+Configuration registration
+--------------------------
+
+Place your YAML files in a form set directory — no PHP registration needed:
+
+..  code-block:: none
+
+    EXT:my_extension/
+      Configuration/
+        Form/
+          MyFinisher/
+            config.yaml
+
+..  seealso::
+
+    :ref:`concepts-configuration-yaml-autodiscovery`
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MySitePackage\Domain\Finishers;
+
+class CustomFinisher extends \TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher
+{
+    protected $defaultOptions = [
+        'yourCustomOption' => 'Olli',
+    ];
+
+    // ...
+    protected function executeInternal()
+    {
+        // TODO: Implement executeInternal() method.
+    }
+}
@@ -0,0 +1,7 @@
+prototypes:
+  standard:
+    finishersDefinition:
+      CustomFinisher:
+        implementationClassName: 'MyVendor\MySitePackage\Domain\Finishers\CustomFinisher'
+        options:
+          yourCustomOption: 'Ralf'
@@ -0,0 +1,64 @@
+prototypes:
+  standard:
+    formElementsDefinition:
+      Form:
+        formEditor:
+          editors:
+            900:
+              # Extend finisher drop down
+              selectOptions:
+                35:
+                  value: 'CustomFinisher'
+                  label: 'Custom Finisher'
+          propertyCollections:
+            finishers:
+              # add finisher fields
+              25:
+                identifier: 'CustomFinisher'
+                editors:
+                  100:
+                    identifier: header
+                    templateName: Inspector-CollectionElementHeaderEditor
+                    label: "Custom Finisher"
+                  # custom field (input, required)
+                  110:
+                    identifier: 'customField'
+                    templateName: 'Inspector-TextEditor'
+                    label: 'Custom Field'
+                    propertyPath: 'options.customField'
+                    propertyValidators:
+                      10: 'NotEmpty'
+                  # email field
+                  120:
+                    identifier: 'email'
+                    templateName: 'Inspector-TextEditor'
+                    label: 'Subscribers email'
+                    propertyPath: 'options.email'
+                    enableFormelementSelectionButton: true
+                    propertyValidators:
+                      10: 'NotEmpty'
+                      20: 'FormElementIdentifierWithinCurlyBracesInclusive'
+                  9999:
+                    identifier: removeButton
+                    templateName: Inspector-RemoveElementEditor
+    finishersDefinition:
+      CustomFinisher:
+        formEditor:
+          iconIdentifier: 'form-finisher'
+          label: 'Custom Finisher'
+          predefinedDefaults:
+            options:
+              customField: ''
+              email: ''
+        # displayed when overriding finisher settings
+        FormEngine:
+          label: 'Custom Finisher'
+          elements:
+            customField:
+              label: 'Custom Field'
+              config:
+                type: 'text'
+            email:
+              label: 'Subscribers email'
+              config:
+                type: 'text'
@@ -0,0 +1,6 @@
+prototypes:
+  standard:
+    finishersDefinition:
+      CustomFinisher:
+        implementationClassName: 'MyVendor\MySitePackage\Domain\Finishers\CustomFinisher'
+
@@ -0,0 +1,13 @@
+identifier: sample-form
+label: 'Simple Contact Form'
+prototype: standard
+type: Form
+
+finishers:
+  -
+    identifier: CustomFinisher
+    options:
+      yourCustomOption: 'Björn'
+
+renderables:
+  # ...
@@ -0,0 +1,15 @@
+identifier: sample-form
+label: 'Simple Contact Form'
+prototype: standard
+type: Form
+
+finishers:
+  -
+    identifier: Custom
+    options:
+      yourCustomOption: 'Frans'
+
+  -
+    identifier: SomeOtherStuff
+    options:
+      someOtherCustomOption: '{Custom.unique.value.identifier}'
@@ -0,0 +1,16 @@
+identifier: simple-contact-form
+label: 'Simple Contact Form'
+prototype: standard
+type: Form
+
+finishers:
+  -
+    identifier: Custom
+    options:
+      yourCustomOption: '{subject}'
+
+renderables:
+  -
+    identifier: subject
+    label: 'Subject'
+    type: Text
@@ -0,0 +1,40 @@
+:navigation-title: Finishers
+
+..  include:: /Includes.rst.txt
+..  _concepts-finishers:
+
+============================================
+Finishers: post-submission actions for forms
+============================================
+
+When a form has been submitted in TYPO3, finishers decide what happens
+next - sending an email, redirecting to another page, or showing a
+confirmation message. This page gives you a quick tour of built-in finishers.
+For more details, see :ref:`Finisher Options <apireference-finisheroptions>`.
+
+There is also a dedicated chapter on
+:ref:`translations of finisher options <concepts-frontendrendering-translation-finishers>`.
+
+..  toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    ReadyToUseFinishers/Index
+    CustomFinisherImplementations/Index
+
+..  _concepts-finishers-execution-order:
+
+Finisher execution order
+========================
+
+..  important::
+    Finishers are executed in the order that is defined in your form definition. The
+    `Redirect finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-redirectfinisher>`_
+    terminates all finishers.
+
+If you are using the `redirect finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-redirectfinisher>`_, make sure it is the last finisher
+that is executed. The redirect finisher stops the
+execution of all subsequent finishers in order to perform a redirect. Finishers
+that are defined after a redirect finisher will be ignored.
+
+..  literalinclude:: ReadyToUseFinishers/RedirectFinisher/_codesnippets/_example-redirect.yaml
@@ -0,0 +1,43 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-closurefinisher:
+
+================
+Closure finisher
+================
+
+The "Closure finisher" can only be used in programmatically-created forms. It allows
+you to execute your own finisher code without implementing/ declaring a finisher.
+
+..  contents:: Table of contents
+
+..  include:: /Includes/_NoteFinisher.rst
+
+..  _apireference-finisheroptions-closurefinisher-options:
+
+Closure finisher option
+=======================
+
+..  _apireference-finisheroptions-closurefinisher-options-closure:
+
+..  confval:: closure
+    :name: closurefinisher-closure
+    :required: true
+    :type: `?\Closure`
+    :default: `null`
+
+    The name of the field as shown in the form.
+
+..  _apireference-finisheroptions-closurefinisher:
+
+Using the closure finisher programmatically
+===========================================
+
+This finisher can only be used in programmatically-created forms. It allows
+you to execute your own finisher code without implementing/ declaring a finisher.
+
+Code example:
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+
+This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher`.
@@ -0,0 +1,20 @@
+<?php
+
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+
+class SomeClass
+{
+    private function addClosureFinisher(FormDefinition $formDefinition)
+    {
+
+        $closureFinisher = GeneralUtility::makeInstance(ClosureFinisher::class);
+        $closureFinisher->setOption('closure', function ($finisherContext)
+        {
+            $formRuntime = $finisherContext->getFormRuntime();
+            // ...
+        });
+        $formDefinition->addFinisher($closureFinisher);
+    }
+}
@@ -0,0 +1,109 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-confirmationfinisher:
+..  _finishers-confirmation-message:
+
+=====================
+Confirmation finisher
+=====================
+
+A basic finisher that outputs a text or content element.
+
+..  contents:: Table of contents
+
+..  include:: /Includes/_NoteFinisher.rst
+
+..  _apireference-finisheroptions-confirmationfinisher-options:
+
+Confirmation finisher options
+=============================
+
+This finisher outputs a text or a content element after the form has been submitted.
+
+The settings of the finisher are:
+
+..  _apireference-finisheroptions-confirmationfinisher-options-message:
+
+..  confval:: message
+    :name: confirmationfinisher-message
+    :type: string
+    :default: `The form has been submitted.`
+
+    Displays this text if the `contentElementUid` is not set.
+
+..  confval:: contentElementUid
+    :name: confirmationfinisher-contentElementUid
+    :type: int
+    :default: 0
+
+    Renders the content element with the supplied ID.
+
+..  confval:: translation.propertiesExcludedFromTranslation
+    :name: confirmationfinisher-translation-propertiesExcludedFromTranslation
+    :type: array
+    :default: `[]`
+
+    Defines a list of finisher option properties that should be excluded from
+    translation.
+
+    When specified, the listed properties are not processed by the
+    :php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation
+    of finisher options. This prevents their values from being replaced by
+    translated equivalents, even if translations exist for those options.
+
+    This option is usually generated automatically as soon as FlexForm overrides
+    are in place and normally does not need to be set manually in the form
+    definition.
+
+    See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
+    for an example.
+
+..  _concepts-finishers-confirmationfinisher-yaml:
+
+Confirmation finisher in the YAML form definition
+=================================================
+
+A basic finisher that outputs text or a content element.
+
+Outputs text ``message``:
+
+..  literalinclude:: _codesnippets/_form_with_confirmation_finisher.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+Outputs content element with id 42:
+
+..  literalinclude:: _codesnippets/_form_with_confirmation_content_element.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _concepts-finishers-confirmationfinisher-yaml-propertiesExcludedFromTranslation:
+
+Skip translation of overridden form finisher options
+====================================================
+
+The following is an example of the `translation.propertiesExcludedFromTranslation <https://docs.typo3.org/permalink/typo3/cms-form:confval-confirmationfinisher-translation-propertiesexcludedfromtranslation>`_
+option being used to exclude  three properties (subject, recipients and
+format) from translation.
+
+Using this translation option, the properties can only be overridden by a FlexForm, not by the
+:php-short:`\TYPO3\CMS\Form\Service\TranslationService`.
+
+This option is automatically generated as soon as FlexForm overrides are in place.
+
+The following syntax is only documented for completeness. Nonetheless, it can
+also be added to a form definition YAML file.
+
+..  literalinclude:: _codesnippets/_form_with_propertiesExcludedFromTranslation.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _apireference-finisheroptions-confirmationfinisher:
+
+Using the confirmation finisher in PHP code
+===========================================
+
+Developers can use the finisher key `Confirmation` to create
+confirmation finishers in their own classes:
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+
+Th confirmation finisher is implemented in
+:php:`TYPO3\CMS\Form\Domain\Finishers\ConfirmationFinisher`.
@@ -0,0 +1,19 @@
+<?php
+
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+
+class SomeClass
+{
+    private function addConfirmationnFinisherWithMessage(FormDefinition $formDefinition, string $message)
+    {
+        $formDefinition->createFinisher('Confirmation', [
+            'message' => $message,
+        ]);
+    }
+    private function addConfirmationnFinisherWithContentElement(FormDefinition $formDefinition, int $contentElementUid)
+    {
+        $formDefinition->createFinisher('Confirmation', [
+            'contentElementUid' => $contentElementUid,
+        ]);
+    }
+}
@@ -0,0 +1,10 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: Confirmation
+    options:
+      contentElementUid: 42
+  #...
@@ -0,0 +1,10 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: Confirmation
+    options:
+      message: 'Thx for using TYPO3'
+  # ...
@@ -0,0 +1,17 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    options:
+      identifier: EmailToSender
+      subject: 'Email to sender'
+      recipients:
+        recipient@example.org: 'Some Name'
+      translation:
+        propertiesExcludedFromTranslation:
+          - subject
+          - recipients
+          - format
+  # ...
@@ -0,0 +1,48 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-deleteuploadsfinisher:
+..  _finishers-delete-uploads:
+
+=======================
+DeleteUploads finishers
+=======================
+
+The "DeleteUploads finisher" removes files that have been submitted. You can use this
+finisher after the email finisher if you do not want to keep the files
+in your TYPO3 installation.
+
+..  note::
+
+    Finishers are only executed when a form is successfully submitted. If a user uploads
+    a file but does not finish filling out the form, the uploaded files will not
+    be deleted.
+
+..  contents:: Table of contents
+
+..  include:: /Includes/_NoteFinisher.rst
+
+..  _concepts-finishers-deleteuploadsfinisher-yaml:
+
+DeleteUploads finisher in the YAML form definition
+==================================================
+
+Use this finisher after the email finisher if you do not want to keep the files
+in your TYPO3 installation.
+
+Finishers are executed in the order they are listed in the form definition
+YAML file:
+
+..  literalinclude:: _codesnippets/_form.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _apireference-finisheroptions-deleteuploadsfinisher:
+
+Using the DeleteUploads finisher in PHP code
+============================================
+
+Developers can use the finisher key `DeleteUploads` to create
+deleteuploads finishers in their own classes:
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+
+This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\DeleteUploadsFinisher`.
@@ -0,0 +1,11 @@
+<?php
+
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+
+class SomeClass
+{
+    private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
+    {
+        $formDefinition->createFinisher('DeleteUploads');
+    }
+}
@@ -0,0 +1,13 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: EmailToSender
+    options:
+      subject: 'Your Message: {message}'
+  -
+    identifier: DeleteUploads
+    # Define the delete uploads finisher AFTER the email finisher
+# ...
@@ -0,0 +1,325 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-emailfinisher:
+
+==============
+Email finisher
+==============
+
+The EmailFinisher sends an email to one recipient. EXT:form has two
+EmailFinishers with the identifiers EmailToReceiver and EmailToSender.
+
+..  contents:: Table of contents
+
+..  include:: /Includes/_NoteFinisher.rst
+
+
+..  _concepts-finishers-emailfinisher-backend:
+..  _finishers-email-to-sender:
+..  _finishers-email-to-receiver:
+
+Using email finishers in the backend form editor
+================================================
+
+Editors can use two email finishers in the backend form editor:
+
+Email to sender (form submitter)
+    This finisher sends an email with the contents of the form to the user
+    submitting the form .
+
+Email to receiver (you)
+    This finisher sends an email with the contents of the form to the owner of the
+    website. The settings of this finisher are the
+    same as the "Email to sender" finisher
+
+..  _apireference-finisheroptions-emailfinisher-options:
+
+Options of the email finisher
+=============================
+
+..  _apireference-finisheroptions-emailfinisher-options-subject:
+
+..  confval:: Subject [subject]
+    :name: emailfinisher-subject
+    :type: string
+    :required: true
+
+    Subject of the email.
+
+..  _apireference-finisheroptions-emailfinisher-options-recipients:
+
+..  confval:: Recipients [recipients]
+    :name: emailfinisher-recipients
+    :type: array
+    :required: true
+
+    Email addresses and names of the recipients (To).
+
+    **Email Address**
+        Email address of a recipient, e.g. "some.recipient@example.com"
+        or "{email-1}".
+    **Name**
+        Name of a recipient, e.g. "Some Recipient" or "{text-1}".
+
+..  _apireference-finisheroptions-emailfinisher-options-senderaddress:
+
+..  confval:: Sender address [senderAddress]
+    :name: emailfinisher-senderAddress
+    :type: string
+    :required: true
+
+    Email address of the sender, for example "your.company@example.org".
+
+    If `smtp <https://docs.typo3.org/permalink/t3coreapi:mail-configuration-smtp>`_
+    is used, this email address needs to be allowed by the
+    SMTP server. Use `replyToRecipients` if you want to enable the receiver to
+    reply to the message.
+
+..  _apireference-finisheroptions-emailfinisher-options-sendername:
+
+..  confval:: Sender name [senderName]
+    :name: emailfinisher-senderName
+    :type: string
+    :default: `''`
+
+    Name of the sender, for example "Your Company".
+
+..  _apireference-finisheroptions-emailfinisher-options-replytorecipients:
+
+..  confval:: Reply-to Recipients [replyToRecipients]
+    :name: emailfinisher-replyToRecipients
+    :type: array
+    :default: `[]`
+
+    Email address which will be used when someone replies to the email.
+
+    **Email Address**:
+        Email address for reply-to.
+    **Name**
+        Name for reply-to.
+
+..  _apireference-finisheroptions-emailfinisher-options-carboncopyrecipients:
+
+..  confval:: CC Recipient [carbonCopyRecipients]
+    :name: emailfinisher-carbonCopyRecipients
+    :type: array
+    :default: `[]`
+
+    Email address to which a copy of the email is sent. The information is
+    visible to all other recipients.
+
+    **Email Address**:
+        Email address for CC.
+    **Name**
+        Name for CC.
+
+..  _apireference-finisheroptions-emailfinisher-options-blindcarboncopyrecipients:
+
+..  confval:: BCC Recipients [blindCarbonCopyRecipients]
+    :name: emailfinisher-blindCarbonCopyRecipients
+    :type: array
+    :default: `[]`
+
+    Email address to which a copy of the email is sent. The information is not
+    visible to any of the recipients.
+
+    **Email Address**:
+        Email address for BCC.
+    **Name**
+        Name for BCC.
+
+..  _apireference-finisheroptions-emailfinisher-options-addhtmlpart:
+
+..  confval:: Add HTML part [addHtmlPart]
+    :name: emailfinisher-addHtmlPart
+    :type: bool
+    :default: `true`
+
+    If set, emails will contain plaintext and HTML, otherwise only plaintext.
+    In this way, HTML can be disabled and plaintext-only emails enforced.
+
+..  _apireference-finisheroptions-emailfinisher-options-attachuploads:
+
+..  confval:: Attach uploads [attachUploads]
+    :name: emailfinisher-attachUploads
+    :type: bool
+    :default: `true`
+
+    If set, all uploaded items are attached to the email.
+
+..  _apireference-finisheroptions-emailfinisher-options-title:
+
+..  confval:: Title [title]
+    :name: emailfinisher-title
+    :type: string
+    :required: false
+    :default: `undefined`
+
+    The title shown in the email.
+
+..  _apireference-finisheroptions-emailfinisher-options-translation-language:
+
+..  confval:: Translation language [translation.language]
+    :name: emailfinisher-translation-language
+    :type: string
+    :required: false
+    :default: `undefined`
+
+    If not set, the finisher options are translated depending on the current
+    frontend language (if translations exist). This option allows you to force
+    translations for a given language isocode, e.g. `da` or `de`.
+    See :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>`.
+
+..  _apireference-finisheroptions-emailfinisher-options-options:
+
+Additional email finisher options
+=================================
+
+Additional options can be set in the form definition YAML and
+programmatically in the options array but **not** in the backend editor:
+
+..  _apireference-finisheroptions-emailfinisher-options-translation-propertiesExcludedFromTranslation:
+
+..  confval:: Properties excluded from translation [translation.propertiesExcludedFromTranslation]
+    :name: emailfinisher-translation-propertiesExcludedFromTranslation
+    :type: array
+    :required: false
+    :default: `undefined`
+
+    If not set, the finisher options are translated depending on the current frontend language (if translations exists).
+    This option allows you to force translations for a given language isocode, e.g 'da' or 'de'.
+    See :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>`.
+    It will be skipped for all specified finisher options.
+
+..  _apireference-finisheroptions-emailfinisher-options-translation-translationfiles:
+
+..  confval:: translation.translationFiles
+    :name: emailfinisher-translation-translationFiles
+    :type: array
+    :required: false
+    :default: `undefined`
+
+    If set, this translation file(s) will be used for finisher option
+    translations. If not set, the translation file(s) from the `Form` element
+    will be used.
+    Read :ref:`Translate finisher options<concepts-frontendrendering-translation-finishers>`.
+
+..  _apireference-finisheroptions-emailfinisher-options-layoutrootpaths:
+
+..  confval:: layoutRootPaths
+    :name: emailfinisher-layoutRootPaths
+    :type: array
+    :required: false
+    :default: `undefined`
+
+    Fluid layout paths.
+
+..  _apireference-finisheroptions-emailfinisher-options-partialrootpaths:
+
+..  confval:: partialRootPaths
+    :name: emailfinisher-partialRootPaths
+    :type: array
+    :required: false
+    :default: `undefined`
+
+    Fluid partial paths.
+
+..  _apireference-finisheroptions-emailfinisher-options-templaterootpaths:
+
+..  confval:: templateRootPaths
+    :name: emailfinisher-templateRootPaths
+    :type: array
+    :required: false
+    :default: `undefined`
+
+    Fluid template paths; all templates get the current :php:`FormRuntime`
+    assigned as :code:`form` and the :php:`FinisherVariableProvider` assigned
+    as :code:`finisherVariableProvider`.
+
+..  _apireference-finisheroptions-emailfinisher-options-variables:
+
+..  confval:: variables
+    :name: emailfinisher-variables
+    :type: array
+    :required: false
+    :default: `undefined`
+
+    Associative array of variables which are available inside the Fluid template.
+
+..  _concepts-finishers-emailfinisher-yaml:
+
+Email finishers in the YAML form definition
+===========================================
+
+This finisher sends an email to one recipient.
+EXT:form has two email finishers with identifiers
+`EmailToReceiver` and `EmailToSender`.
+
+..  literalinclude:: _codesnippets/_form.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _apireference-finisheroptions-emailfinisher:
+
+Using Email finishers in PHP code
+=================================
+
+Developers can create a confirmation finisher by using the key `EmailToReceiver`
+or `EmailToSender`.
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+
+This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\EmailFinisher`.
+
+..  _concepts-finishers-emailfinisher-bcc-recipients:
+
+Working with BCC recipients
+===========================
+
+Email finishers can work with different recipient types, including Carbon Copy
+(CC) and Blind Carbon Copy (BCC). Depending on the configuration of your server
+and TYPO3 instance, it may not be possible to send emails to BCC recipients.
+The :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport_sendmail_command']`
+configuration value is important here. As documented in :ref:`CORE API <t3coreapi:mail-configuration-sendmail>`,
+TYPO3 recommends using the parameter :php:`-bs` (instead of :php:`-t -i`) with
+:php:`sendmail`. The parameter :php:`-bs` tells TYPO3 to use the SMTP standard
+so that BCC recipients are properly set. `Symfony <https://symfony.com/doc/current/mailer.html#using-built-in-transports>`__
+also mentions the :php:`-t` parameter problem. Since TYPO3 7.5
+(`#65791 <https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/7.5/Feature-65791-UsePHPConfiguredSendmailPathIfMAILtransportSendmailIsActive.html>`__)
+the :php:`transport_sendmail_command` is automatically set from the PHP runtime
+configuration and saved. If you have problems sending emails to BCC
+recipients, this could be the solution.
+
+..  _concepts-finishers-emailfinisher-fluidemail:
+
+About FluidEmail
+================
+
+..  versionchanged:: 12.0
+    The :php:`EmailFinisher` always sends email via :php:`FluidEmail`.
+
+The FluidEmail finisher allows emails to be sent in a standardized way.
+
+The finisher has an :yaml:`option` property :yaml:`title` that adds an email title to the default
+FluidEmail template. Variables can be used in options using the bracket syntax.
+These variables can be overwritten by FlexForm configuration in the form plugin
+
+Use these options to customize the fluid templates:
+
+*   :yaml:`templateName`: The template name (for both HTML and plaintext, without the
+    extension)
+*   :yaml:`templateRootPaths`: The paths to the templates
+*   :yaml:`partialRootPaths`: The paths to the partials
+*   :yaml:`layoutRootPaths`: The paths to the layouts
+
+..  note::
+    The field :yaml:`templatePathAndFilename` is no longer evaluated.
+
+Here is an example finisher configuration:
+
+..  literalinclude:: _codesnippets/_example-email.yaml
+    :caption: public/fileadmin/forms/my_form_with_email_finisher.yaml
+
+These template files must exist:
+
+*   :file:`EXT:my_site_package/Resources/Private/Templates/Email/ContactForm.html`
+*   :file:`EXT:my_site_package/Resources/Private/Templates/Email/ContactForm.txt`
@@ -0,0 +1,15 @@
+identifier: contact
+type: Form
+prototypeName: standard
+finishers:
+  -
+    identifier: EmailToSender
+    options:
+      subject: 'Your Message: {message}'
+      title: 'Hello {name}, your confirmation'
+      templateName: ContactForm
+      templateRootPaths:
+        100: 'EXT:my_site_package/Resources/Private/Templates/Email/'
+      partialRootPaths:
+        100: 'EXT:my_site_package/Resources/Private/Partials/Email/'
+      addHtmlPart: true
@@ -0,0 +1,19 @@
+<?php
+
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+
+class SomeClass
+{
+    private function addEmailToReceiverFinisher(FormDefinition $formDefinition)
+    {
+        $formDefinition->createFinisher('EmailToReceiver', [
+            'subject' => 'Your message',
+            'recipients' => [
+                'your.company@example.com' => 'Your Company name',
+                'ceo@example.com' => 'CEO'
+            ],
+            'senderAddress' => $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress'],
+            'senderName' => $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromName'],
+        ]);
+    }
+}
@@ -0,0 +1,14 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: EmailToReceiver
+    options:
+      subject: 'Your message'
+      recipients:
+        your.company@example.com: 'Your Company name'
+        ceo@example.com: 'CEO'
+      senderAddress: 'form@example.com'
+      senderName: 'form submitter'
@@ -0,0 +1,116 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-flashmessagefinisher:
+
+=====================
+FlashMessage finisher
+=====================
+
+The "FlashMessage finisher" is a basic finisher that adds a message to the
+FlashMessageContainer.
+
+..  contents:: Table of contents
+
+..  note::
+
+    This finisher cannot be used in the backend form editor. It can only be used
+    in a form definition YAML file or programmatically.
+
+..  include:: /Includes/_NoteFinisher.rst
+
+..  _apireference-finisheroptions-flashmessagefinisher-options:
+
+FlashMessage finisher options
+=============================
+
+The following options can be set (in the form definition YAML or
+programmatically):
+
+..  _apireference-finisheroptions-flashmessagefinisher-options-messagebody:
+
+..  confval:: messageBody
+    :name: flashmessagefinisher-messageBody
+    :type: string
+    :required: true
+
+    The flash message. May contain placeholders like `%s` that
+    are replaced with `messageArguments`.
+
+..  _apireference-finisheroptions-flashmessagefinisher-options-messagetitle:
+
+..  confval:: messageTitle
+    :name: flashmessagefinisher-messageTitle
+    :type: string
+    :default: `''`
+
+    If set, is the flash message title.
+
+..  _apireference-finisheroptions-flashmessagefinisher-options-messagearguments:
+
+..  confval:: messageArguments
+    :name: flashmessagefinisher-messageArguments
+    :type: array
+    :default: `[]`
+
+    If `messageBody` contains placeholders (like `%s`), they will be replaced
+    by these.
+
+..  _apireference-finisheroptions-flashmessagefinisher-options-messagecode:
+
+..  confval:: messageCode
+    :name: flashmessagefinisher-messageCode
+    :type: ?int
+    :default: `null`
+
+    A unique code to identify the message. By convention, the
+    unix time stamp at the time when the message is created is used,
+    for example `1758455932`.
+
+..  _apireference-finisheroptions-flashmessagefinisher-options-severity:
+
+..  confval:: severity
+    :name: flashmessagefinisher-severity
+    :type: :php:`\TYPO3\CMS\Core\Type\ContextualFeedbackSeverity`
+    :default: `ContextualFeedbackSeverity::OK`
+
+    The severity influences the display (color and icon) of the flash message.
+
+..  confval:: translation.propertiesExcludedFromTranslation
+    :name: flashmessagefinisher-translation-propertiesExcludedFromTranslation
+    :type: array
+    :default: `[]`
+
+    Defines a list of finisher option properties to be excluded from
+    translation.
+
+    If set, these properties will not be processed by the
+    :php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation
+    of finisher options. This prevents their values from being replaced by
+    translated equivalents, even if translations exist for those options.
+
+    This option is usually generated automatically as soon as FlexForm overrides
+    are in place and normally does not need to be set manually in the form
+    definition.
+
+    See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
+    for an example.
+
+..  _concepts-finishers-flashmessagefinisher-yaml:
+
+FlashMessage finisher in a YAML form definition
+===============================================
+
+..  literalinclude:: _codesnippets/_form.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _apireference-finisheroptions-flashmessagefinisher:
+
+Using FlashMessage finishers in PHP code
+========================================
+
+Developers can use the finisher key `FlashMessage` to create
+flash message finishers in their own classes:
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+
+This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\FlashMessageFinisher`.
@@ -0,0 +1,18 @@
+<?php
+
+use TYPO3\CMS\Core\Type\ContextualFeedbackSeverity;
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+
+class SomeClass
+{
+    private function addFlashMessageFinisher(FormDefinition $formDefinition, string $message)
+    {
+        $formDefinition->createFinisher('FlashMessage', [
+            'messageTitle' => 'Merci',
+            'messageCode' => 201905041245,
+            'messageBody' => 'Thx for using %s',
+            'messageArguments' => ['TYPO3'],
+            'severity' => ContextualFeedbackSeverity::OK,
+        ]);
+    }
+}
@@ -0,0 +1,14 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: FlashMessage
+    options:
+      messageTitle: 'Merci'
+      messageCode: 201905041245
+      messageBody: 'Thx for using %s'
+      messageArguments:
+        - 'TYPO3'
+      severity: 0
@@ -0,0 +1,62 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-ready-to-use:
+..  _apireference-finisheroptions:
+
+======================
+Ready-to-use finishers
+======================
+
+The TYPO3 Form Framework provides several built-in finishers that can be
+used out of the box. These handle common post submission tasks such as
+sending emails, showing confirmation messages, and saving data.
+
+In addition, third-party extensions may provide further finishers, which
+can be found in the `TYPO3 Extension Repository (TER) <https://extensions.typo3.org/>`_.
+
+..  card-grid::
+    :columns: 1
+    :columns-md: 2
+    :gap: 4
+    :class: pb-4
+    :card-height: 100
+
+    ..  card:: `Closure finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-closurefinisher>`_
+
+        Executes a custom PHP closure after a successful submission—use
+        for ad-hoc logic without creating a full class.
+
+    ..  card:: `Confirmation finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher>`_
+
+        Renders a confirmation/thank-you message (or view) once the form
+        is submitted.
+
+    ..  card:: `DeleteUploads finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-deleteuploadsfinisher>`_
+
+        Removes files uploaded during the submission—useful if after
+        emailing them you don’t want to keep the files on the server.
+
+    ..  card:: `Email finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-emailfinisher>`_
+
+        Sends an email with the submitted data; supports Fluid
+        templates and placeholders for field values.
+
+    ..  card:: :doc:`Flash message finisher <FlashMessageFinisher/Index>`
+
+        Shows a flash message to the user after submit (e.g., success or
+        info notice).
+
+    ..  card:: `Redirect finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-redirectfinisher>`_
+
+        Redirects to another page or route after submit; must be last
+        finisher since it stops subsequent finishers.
+
+    ..  card:: `SaveToDatabase finisher <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-savetodatabasefinisher>`_
+
+        Persists submitted form values to a database table according to
+        your mapping/configuration.
+
+..  toctree::
+    :hidden:
+    :glob:
+
+    */Index
@@ -0,0 +1,135 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-redirectfinisher:
+..  _finishers-redirect:
+
+=================
+Redirect finisher
+=================
+
+This finisher redirects the user to a particular page after the form has been submitted.
+Parameters can be added to the URL.
+
+..  contents:: Table of contents
+
+..  important::
+
+    Finishers are executed in the order defined in your form definition.
+    This finisher stops the execution of all subsequent finishers in order to perform
+    the redirect. Therefore, this finisher should always be the last finisher to be
+    executed. Finishers placed after this one in the form definition will be ignored.
+
+..  _apireference-finisheroptions-redirectfinisher-options:
+
+Redirect finisher options
+=========================
+
+..  _apireference-finisheroptions-redirectfinisher-options-pageuid:
+
+..  confval:: Page: [pageUid]
+    :name: redirectfinisher-pageUid
+    :type: int
+    :required: true
+    :default: `1`
+
+    ID of the page to redirect to. Button :guilabel:`Page` can be used to select
+    a page from the page tree.
+
+..  _apireference-finisheroptions-redirectfinisher-options-additionalparameters:
+
+..  confval:: Additional parameters: [additionalParameters]
+    :name: redirectfinisher-additionalParameters
+    :type: string
+    :required: false
+    :default: `''`
+
+    URL parameters which will be appended to the URL.
+
+..  _apireference-finisheroptions-redirectfinisher-options-fragment:
+
+..  confval:: URL fragment: [fragment]
+    :name: redirectfinisher-fragment
+    :type: string
+    :required: false
+    :default: `''`
+
+    ID of a content element identifier or a custom fragment
+    identifier. This will be appended to the URL and used as section anchor.
+
+    Adds a fragment (e.g. :html:`#c9` or :html:`#foo`) to the redirect link.
+    The :html:`#` character can be omitted.
+
+..  _apireference-finisheroptions-redirectfinisher-options-additional:
+
+Additional redirect finisher options
+====================================
+
+These options can be set in the form definition YAML or
+programmatically in the options array. They cannot be set in the backend form editor:
+
+..  _apireference-finisheroptions-redirectfinisher-options-delay:
+
+..  confval:: delay
+    :name: redirectfinisher-delay
+    :type: int
+    :required: false
+    :default: `0`
+
+    The redirect delay in seconds.
+
+..  _apireference-finisheroptions-redirectfinisher-options-statuscode:
+
+..  confval:: statusCode
+    :name: redirectfinisher-statusCode
+    :type: int
+    :required: false
+    :default: `303`
+
+    The HTTP status code for the redirect. Default is "303 See Other".
+
+..  confval:: translation.propertiesExcludedFromTranslation
+    :name: redirectfinisher-translation-propertiesExcludedFromTranslation
+    :type: array
+    :default: `[]`
+
+    Defines a list of finisher option properties to be excluded from
+    translation.
+
+    If set, these properties are not processed by the
+    :php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation.
+    This prevents their values from being replaced by
+    translated equivalents, even if translations exist for those options.
+
+    This option is usually generated automatically shen FlexForm overrides
+    are in place and normally does not need to be set manually in the form
+    definition.
+
+    See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
+    for an example.
+
+..  _concepts-finishers-redirectfinisher-yaml:
+
+Redirect finisher in a YAML form definition
+===========================================
+
+..  literalinclude:: _codesnippets/_form.yaml
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _concepts-finishers-redirectfinisher-last:
+
+Example: Load the redirect finisher last
+========================================
+
+..  literalinclude:: _codesnippets/_example-redirect.yaml
+    :caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
+
+..  _apireference-finisheroptions-redirectfinisher:
+
+Using a Redirect finisher in PHP code
+=====================================
+
+Developers can use the finisher key `Redirect` to create redirect finishers in their own classes:
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+
+This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\RedirectFinisher`.
@@ -0,0 +1,17 @@
+identifier: contact
+type: Form
+prototypeName: standard
+finishers:
+  -
+    identifier: EmailToSender
+    options:
+      subject: 'Your Message: {message}'
+      ## ...
+  -
+    identifier: DeleteUploads
+  -
+    # Attention! The Redirect finisher stops the execution of all finishers
+    identifier: Redirect
+    options:
+      pageUid: 1
+      additionalParameters: 'param1=value1&param2=value2'
@@ -0,0 +1,14 @@
+<?php
+
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+
+class SomeClass
+{
+    private function addRedirectFinisher(FormDefinition $formDefinition)
+    {
+        $formDefinition->createFinisher('Redirect', [
+            'pageUid' => 1,
+            'additionalParameters' => 'param1=value1&param2=value2',
+        ]);
+    }
+}
@@ -0,0 +1,10 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: Redirect
+    options:
+      pageUid: 1
+      additionalParameters: 'param1=value1&param2=value2'
@@ -0,0 +1,245 @@
+..  include:: /Includes.rst.txt
+..  _concepts-finishers-savetodatabasefinisher:
+
+=======================
+SaveToDatabase finisher
+=======================
+
+The "SaveToDatabase finisher" saves data from a submitted form into a
+database table.
+
+..  contents:: Table of contents
+
+..  note::
+
+    This finisher cannot be used in the backend form editor. It can only be
+    used in a form definition YAML file or programmatically.
+
+..  include:: /Includes/_NoteFinisher.rst
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options:
+
+SaveToDatabase finisher options
+===============================
+
+The finisher options can be set in the form definition YAML file or
+programmatically:
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-table:
+
+..  confval:: table
+    :name: savetodatabasefinisher-table
+    :type: string
+    :required: true
+
+    Insert or update values in this table.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-mode:
+
+..  confval:: mode
+    :name: savetodatabasefinisher-mode
+    :type: string
+    :default: `'insert'`
+
+    `insert`
+        will create a new database row with the values from the submitted form
+        and/or some predefined values. See also :confval:`savetodatabasefinisher-elements` and
+        :confval:`savetodatabasefinisher-databaseColumnMappings`.
+
+    `update`
+        will update a database row with the values from the submitted form
+        and/or some predefined values. In this case :confval:`savetodatabasefinisher-whereClause` is required.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-whereclause:
+
+..  confval:: whereClause
+    :name: savetodatabasefinisher-whereClause
+    :type: array
+    :required: true (if mode = update)
+    :default: `[]`
+
+    The  ``where`` clause for a database update action.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-elements:
+
+..  confval:: elements
+    :name: savetodatabasefinisher-elements
+    :type: array
+    :required: true
+
+    Use `options.elements` to map form element values to database columns (they must exist).
+    Each key in `options.elements` has to match a form element identifier.
+    The value of each key in `options.elements` is an array containing additional information.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-elements-mapondatabasecolumn:
+
+..  confval:: elements.<formElementIdentifier>.mapOnDatabaseColumn
+    :name: savetodatabasefinisher-elements-mapOnDatabaseColumn
+    :type: string
+    :required: true
+
+    The value from the submitted form element with the identifier
+    `<formElementIdentifier>` will be written into this database column.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-elements-skipifvalueisempty:
+
+..  confval:: elements.<formElementIdentifier>.skipIfValueIsEmpty
+    :name: savetodatabasefinisher-elements-skipIfValueIsEmpty
+    :type: bool
+    :default: `false`
+
+    Set this to true if the database column should not be written if the value from the
+    submitted form element with the identifier `<formElementIdentifier>` is empty
+    (e.g. for password fields). Empty means strings without content, whitespace is valid content.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-elements-hashed:
+
+..  confval:: elements.<formElementIdentifier>.hashed
+    :name: savetodatabasefinisher-elements-hashed
+    :type: bool
+    :default: `false`
+
+    Set this to true if the value from the submitted form element should be hashed before
+    writing into the database.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-elements-savefileidentifierinsteadofuid:
+
+..  confval:: elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid
+    :name: savetodatabasefinisher-elements-saveFileIdentifierInsteadOfUid
+    :type: bool
+    :default: `false`
+
+    By default, the uid of the FAL object will be written into the database column.
+    Set this to true if you want to store the FAL identifier
+    (e.g. `1:/user_uploads/some_uploaded_pic.jpg`) instead.
+
+    This only applies for form elements which create a FAL object like
+    `FileUpload` or `ImageUpload`.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-elements-dateformat:
+
+..  confval:: elements.<formElementIdentifier>.dateFormat
+    :name: savetodatabasefinisher-elements-dateFormat
+    :type: string
+    :default: `'U'`
+
+    If the internal datatype is :php:`\DateTime` (true for the form element type
+    :yaml:`Date`), the object needs to be converted into a string.
+    This option defines the format of the date. You can use any format accepted by
+    the PHP :php:`date()` function.
+    Default is `'U'` (Unix timestamp).
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings:
+
+..  confval:: databaseColumnMappings
+    :name: savetodatabasefinisher-databaseColumnMappings
+    :type: array
+    :default: `[]`
+
+    Use this to map database columns to values.
+    Each key within `options.databaseColumnMappings` has to match an existing database column.
+    Each value in `options.databaseColumnMappings` is an array with
+    additional information.
+
+    This mapping is done *before* :confval:`savetodatabasefinisher-elements` are mapped.
+    If you map both, the value from :confval:`savetodatabasefinisher-elements` will override the
+    :confval:`savetodatabasefinisher-databaseColumnMappings-value`.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings-value:
+
+..  confval:: databaseColumnMappings.<databaseColumnName>.value
+    :name: savetodatabasefinisher-databaseColumnMappings-value
+    :type: string
+    :required: true
+
+    The value which will be written to the database column.
+    You can also use the :ref:`FormRuntime accessor feature
+    <concepts-finishers-customfinisherimplementations-accessingoptions-formruntimeaccessor>`
+    to access properties from the `FormRuntime`, e.g. `{<formElementIdentifier>}`.
+
+..  _apireference-finisheroptions-savetodatabasefinisher-options-databasecolumnmappings-skipifvalueisempty:
+
+..  confval:: databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty
+    :name: savetodatabasefinisher-databaseColumnMappings-skipIfValueIsEmpty
+    :type: bool
+    :default: `false`
+
+    Set this to true if the database column should not be written if the value from
+    :confval:`savetodatabasefinisher-databaseColumnMappings-value` is empty.
+
+..  confval:: translation.propertiesExcludedFromTranslation
+    :name: savetodatabasefinisher-translation-propertiesExcludedFromTranslation
+    :type: array
+    :default: `[]`
+
+    Defines a list of finisher option properties to be excluded from
+    translation.
+
+    If set, these properties are not processed by the
+    :php-short:`\TYPO3\CMS\Form\Service\TranslationService` during translation.
+    This prevents the values from being replaced by
+    translated equivalents, even if translations exist for those options.
+
+    This option is usually generated when FlexForm overrides
+    exist and normally does not need to be set manually in the form
+    definition.
+
+    See `Skip translation of overridden form finisher options <https://docs.typo3.org/permalink/typo3/cms-form:concepts-finishers-confirmationfinisher-yaml-propertiesexcludedfromtranslation>`_
+    for an example.
+
+..  _concepts-finishers-savetodatabasefinisher-yaml:
+
+SaveToDatabase finisher in a YAML form definition
+=================================================
+
+This finisher saves data from a submitted form into a database table.
+
+..  literalinclude:: _codesnippets/_form.yaml
+    :linenos:
+    :caption: public/fileadmin/forms/my_form.yaml
+
+..  _concepts-finishers-savetodatabasefinisher-example-news:
+
+Example: adding uploads to ext:news (fal_related_files and fal_media):
+======================================================================
+
+..  literalinclude:: _codesnippets/_example-fal-uploads_news.yaml
+    :linenos:
+    :caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
+
+..  _apireference-finisheroptions-savetodatabasefinisher:
+
+Using a SaveToDatabase finisher in PHP code
+================================================
+
+Developers can use the finisher key `SaveToDatabase` to create
+flash message finishers in their own classes:
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+    :linenos:
+
+This finisher is implemented in :php:`TYPO3\CMS\Form\Domain\Finishers\SaveToDatabaseFinisher`.
+
+..  _concepts-finishers-savetodatabasefinisher-multiple:
+
+Multiple database operations
+============================
+
+You can use options to perform multiple database operations.
+
+Example form definition file (performs inserts):
+
+..  literalinclude:: _codesnippets/_example-fal-uploads_news.yaml
+    :linenos:
+    :caption: public/fileadmin/forms/my_form_with_multiple_finishers.yaml
+
+Using PHP code (performs an update):
+
+..  literalinclude:: _codesnippets/_finisher.php.inc
+    :language: php
+    :linenos:
+
+You can access inserted UIDs with '{SaveToDatabase.insertedUids.<theArrayKeyNumberInsideOptions>}'.
+If you perform an insert operation, the inserted values will be stored in the FinisherVariableProvider.
+<theArrayKeyNumberInOptions> references the numeric options.* key.
@@ -0,0 +1,73 @@
+-
+  identifier: SaveToDatabase
+  options:
+    -
+      table: tx_news_domain_model_news
+      mode: insert
+      elements:
+        my-field:
+          mapOnDatabaseColumn: bodytext
+        imageupload-1:
+          mapOnDatabaseColumn: fal_media
+        fileupload-1:
+          mapOnDatabaseColumn: fal_related_files
+      databaseColumnMappings:
+        pid:
+          value: 3
+        tstamp:
+          value: '{__currentTimestamp}'
+        datetime:
+          value: '{__currentTimestamp}'
+        crdate:
+          value: '{__currentTimestamp}'
+        hidden:
+          value: 1
+    -
+      table: sys_file_reference
+      mode: insert
+      elements:
+        imageupload-1:
+          mapOnDatabaseColumn: uid_local
+          skipIfValueIsEmpty: true
+      databaseColumnMappings:
+        tablenames:
+          value: tx_news_domain_model_news
+        fieldname:
+          value: fal_media
+        tstamp:
+          value: '{__currentTimestamp}'
+        crdate:
+          value: '{__currentTimestamp}'
+        showinpreview:
+          value: 1
+        uid_foreign:
+          value: '{SaveToDatabase.insertedUids.0}'
+    -
+      table: sys_file_reference
+      mode: insert
+      elements:
+        fileupload-1:
+          mapOnDatabaseColumn: uid_local
+          skipIfValueIsEmpty: true
+      databaseColumnMappings:
+        tablenames:
+          value: tx_news_domain_model_news
+        fieldname:
+          value: fal_related_files
+        tstamp:
+          value: '{__currentTimestamp}'
+        crdate:
+          value: '{__currentTimestamp}'
+        uid_foreign:
+          value: '{SaveToDatabase.insertedUids.0}'
+    -
+      table: sys_file_reference
+      mode: update
+      whereClause:
+        uid_foreign: '{SaveToDatabase.insertedUids.0}'
+        uid_local: 0
+      databaseColumnMappings:
+        pid:
+          value: 0
+        uid_foreign:
+          value: 0
@@ -0,0 +1,30 @@
+<?php
+
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+class SomeClass
+{
+    private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
+    {
+        $formDefinition->createFinisher('SaveToDatabase', [
+            1 => [
+                'table' => 'my_table',
+                'mode' => 'insert',
+                'databaseColumnMappings' => [
+                    'some_column' => ['value' => 'cool'],
+                ],
+            ],
+            2 => [
+                'table' => 'my_other_table',
+                'mode' => 'update',
+                'whereClause' => [
+                    'pid' => 1,
+                ],
+                'databaseColumnMappings' => [
+                    'some_other_column' => ['value' => '{SaveToDatabase.insertedUids.1}'],
+                ],
+            ],
+        ]);
+    }
+}
@@ -0,0 +1,31 @@
+<?php
+
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+use TYPO3\CMS\Form\Domain\Finishers\ClosureFinisher;
+use TYPO3\CMS\Form\Domain\Model\FormDefinition;
+class SomeClass
+{
+    private function addDeleteUploadsFinisherWithMessage(FormDefinition $formDefinition, string $message)
+    {
+        $formDefinition->createFinisher('SaveToDatabase', [
+            'table' => 'fe_users',
+            'mode' => 'update',
+            'whereClause' => [
+                'uid' => 1,
+            ],
+            'databaseColumnMappings' => [
+                'pid' => ['value' => 1],
+            ],
+            'elements' => [
+                'textfield-identifier-1' => ['mapOnDatabaseColumn' => 'first_name'],
+                'textfield-identifier-2' => ['mapOnDatabaseColumn' => 'last_name'],
+                'textfield-identifier-3' => ['mapOnDatabaseColumn' => 'username'],
+                'advancedpassword-1' => [
+                    'mapOnDatabaseColumn' => 'password',
+                    'skipIfValueIsEmpty' => true,
+                    'hashed' => true
+                ],
+            ],
+        ]);
+    }
+}
@@ -0,0 +1,22 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: SaveToDatabase
+    options:
+      1:
+        table: 'my_table'
+        mode: insert
+        databaseColumnMappings:
+          some_column:
+            value: 'cool'
+      2:
+        table: 'my_other_table'
+        mode: update
+        whereClause:
+          pid: 1
+        databaseColumnMappings:
+          some_other_column:
+            value: '{SaveToDatabase.insertedUids.1}'
@@ -0,0 +1,28 @@
+identifier: example-form
+label: 'example'
+type: Form
+
+finishers:
+  -
+    identifier: SaveToDatabase
+    options:
+      table: 'fe_users'
+      mode: update
+      whereClause:
+        uid: 1
+      databaseColumnMappings:
+        tstamp:
+          value: '{__currentTimestamp}'
+        pid:
+          value: 1
+      elements:
+        textfield-identifier-1:
+          mapOnDatabaseColumn: 'first_name'
+        textfield-identifier-2:
+          mapOnDatabaseColumn: 'last_name'
+        textfield-identifier-3:
+          mapOnDatabaseColumn: 'username'
+        advancedpassword-1:
+          mapOnDatabaseColumn: 'password'
+          skipIfValueIsEmpty: true
+          hashed: true