..  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 types
    :yaml:`DatePicker` and :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.
