SaveToDatabase finisher 

The "SaveToDatabase finisher" saves data from a submitted form into a database table.

Table of contents

SaveToDatabase finisher options 

The finisher options can be set in the form definition YAML file or programmatically:

table

table
Type
string
Required

true

Insert or update values in this table.

mode

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 elements and databaseColumnMappings.
update
will update a database row with the values from the submitted form and/or some predefined values. In this case whereClause is required.

whereClause

whereClause
Type
array
Required

true

Default
[]

The where clause for a database update action.

elements

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.

elements.<formElementIdentifier>.mapOnDatabaseColumn

elements.<formElementIdentifier>.mapOnDatabaseColumn
Type
string
Required

true

The value from the submitted form element with the identifier <formElementIdentifier> will be written into this database column.

elements.<formElementIdentifier>.skipIfValueIsEmpty

elements.<formElementIdentifier>.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.

elements.<formElementIdentifier>.hashed

elements.<formElementIdentifier>.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.

elements.<formElementIdentifier>.saveFileIdentifierInsteadOfUid

elements.<formElementIdentifier>.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.

elements.<formElementIdentifier>.dateFormat

elements.<formElementIdentifier>.dateFormat
Type
string
Default
'U'

If the internal datatype is \DateTime (true for the form element types DatePicker and 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 date() function. Default is 'U' (Unix timestamp).

databaseColumnMappings

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 elements are mapped. If you map both, the value from elements will override the databaseColumnMappings.<databaseColumnName>.value.

databaseColumnMappings.<databaseColumnName>.value

databaseColumnMappings.<databaseColumnName>.value
Type
string
Required

true

The value which will be written to the database column. You can also use the FormRuntime accessor feature to access properties from the FormRuntime, e.g. {<formElementIdentifier>}.

databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty

databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty
Type
bool
Default
false

Set this to true if the database column should not be written if the value from databaseColumnMappings.<databaseColumnName>.value is empty.

translation.propertiesExcludedFromTranslation

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 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 for an example.

SaveToDatabase finisher in a YAML form definition 

This finisher saves data from a submitted form into a database table.

public/fileadmin/forms/my_form.yaml 
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
Copied!

Using a SaveToDatabase finisher in PHP code 

Developers can use the finisher key SaveToDatabase to create flash message finishers in their own classes:

<?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
                ],
            ],
        ]);
    }
}
Copied!

This finisher is implemented in \TYPO3\CMS\Form\Domain\Finishers\SaveToDatabaseFinisher .

Multiple database operations 

You can use options to perform multiple database operations.

Example form definition file (performs inserts):

public/fileadmin/forms/my_form_with_multiple_finishers.yaml 
-
  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
Copied!

Using PHP code (performs an update):

<?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
                ],
            ],
        ]);
    }
}
Copied!

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.