SaveToDatabaseFinisher extends AbstractFinisher

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

Configuration

options.table (mandatory)

Save or update values into this table

options.mode (default: insert)

Possible values are 'insert' or 'update'.

insert: will create a new database row with the values from the submitted form and/or some predefined values. See options.elements and options.databaseFieldMappings update: will update a given database row with the values from the submitted form and/or some predefined values. 'options.whereClause' is then required.

options.whereClause

This where clause will be used for a database update action

options.elements

Use this to map form element values to existing database columns. Each key within options.elements has to match with a form element identifier within your form definition. The value for each key within options.elements is an array with additional information.

options.elements.<elementIdentifier>.mapOnDatabaseColumn (mandatory)

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

options.elements.<elementIdentifier>.skipIfValueIsEmpty (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 '<elementIdentifier>' is empty (think about password fields etc.)

options.elements.<elementIdentifier>.saveFileIdentifierInsteadOfUid (default: false)

This setting only rules for form elements which creates a FAL object like FileUpload or ImageUpload. 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 (1:/user_uploads/some_uploaded_pic.jpg) instead.

options.databaseColumnMappings

Use this to map database columns to static values (which can be made dynamic through typoscript overrides of course). Each key within options.databaseColumnMappings has to match with a existing database column. The value for each key within options.databaseColumnMappings is an array with additional information.

This mapping is done before the options.elements mapping. This means if you map a database column to a value through options.databaseColumnMappings and map a submitted form element value to the same database column, the submitted form element value will override the value you set within options.databaseColumnMappings.

options.databaseColumnMappings.<databaseColumnName>.value

The value which will be written to the database column. You can use the FormRuntime accessor feature to access every getable property from the TYPO3\CMS\Form\Domain\Runtime\FormRuntime Read the description within TYPO3\CMS\Form\Domain\Finishers\AbstractFinisher::parseOption In short: use something like {<elementIdentifier>} to get the value from the submitted form element with the identifier <elementIdentifier>

Don't be confused. If you use the FormRuntime accessor feature within options.databaseColumnMappings, the functionality is nearly equal to the options.elements configuration.

options.databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty (default: false)

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

Example

finishers:

 identifier: SaveToDatabase
 options:
   table: 'fe_users'
   mode: update
   whereClause:
     uid: 1
   databaseColumnMappings:
     pid:
       value: 1
   elements:
     text-1:
       mapOnDatabaseColumn: 'first_name'
     text-2:
       mapOnDatabaseColumn: 'last_name'
     text-3:
       mapOnDatabaseColumn: 'username'
     advancedpassword-1:
       mapOnDatabaseColumn: 'password'
       skipIfValueIsEmpty: true

Multiple database operations

You can write options as an array to perform multiple database operations.

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}'

This would perform 2 database operations. One insert and one update. You can access the inserted uids with '{SaveToDatabase.insertedUids.<theArrayKeyNumberWithinOptions>}' If you perform an insert operation, the value of the inserted database row will be stored within the FinisherVariableProvider. <theArrayKeyNumberWithinOptions> references to the numeric key within options within which the insert operation is executed.

Scope: frontend

Properties

$databaseConnection : Connection
$defaultOptions : array<string|int, mixed>: These are the default options of the finisher.
$finisherContext : FinisherContext
$finisherIdentifier : string
$options : array<string|int, mixed>: The options which have been set from the outside. Instead of directly accessing them, you should rather use parseOption().
$shortFinisherIdentifier : string

Methods

execute() : string|null: Executes the finisher
getFinisherIdentifier() : string
isEnabled() : bool: Returns whether this finisher is enabled
setFinisherIdentifier() : void
setOption() : mixed: Sets a single finisher option (@see setOptions())
setOptions() : mixed
executeInternal() : string|void|null: Executes this finisher
getElementByIdentifier() : FormElementInterface|null: Returns a form element object for a given identifier.
getFormValues() : array<string|int, mixed>: Returns the values of the submitted form
getTypoScriptFrontendController() : TypoScriptFrontendController
parseOption() : string|array<string|int, mixed>|int|null: Read the option called $optionName from $this->options, and parse {...} as object accessors.
prepareData() : array<string|int, mixed>: Prepare data for saving to database
process() : mixed: Perform the current database operation
resolveRuntimeReference() : int|string|array<string|int, mixed>: Resolving property by name from submitted form data.
saveToDatabase() : mixed: Save or insert the values from $databaseData into the table $table
substituteRuntimeReferences() : mixed: You can encapsulate an option value with {}.
throwExceptionOnInconsistentConfiguration() : mixed: Throws an exception if some inconsistent configuration are detected.
translateFinisherOption() : array<string|int, mixed>|string: Wraps TranslationService::translateFinisherOption to recursively invoke all array items of resolved form state values or nested finisher option configuration settings.

$databaseConnection


    protected
        Connection
    $databaseConnection

$defaultOptions

These are the default options of the finisher.


    protected
        array<string|int, mixed>
    $defaultOptions
     = ['table' => null, 'mode' => 'insert', 'whereClause' => [], 'elements' => [], 'databaseColumnMappings' => []]

$finisherContext


    protected
        FinisherContext
    $finisherContext

$finisherIdentifier


    protected
        string
    $finisherIdentifier
     = ''

$options

The options which have been set from the outside. Instead of directly accessing them, you should rather use parseOption().


    protected
        array<string|int, mixed>
    $options
     = []

$shortFinisherIdentifier


    protected
        string
    $shortFinisherIdentifier
     = ''

execute()

Executes the finisher


    public
        final            execute(FinisherContext $finisherContext) : string|null

Parameters

$finisherContext : FinisherContext: The Finisher context that contains the current Form Runtime and Response

Return values

string|null

getFinisherIdentifier()


    public
                    getFinisherIdentifier() : string

Return values

string

isEnabled()

Returns whether this finisher is enabled


    public
                    isEnabled() : bool

Return values

bool

setFinisherIdentifier()


    public
                    setFinisherIdentifier(string $finisherIdentifier) : void

Parameters

$finisherIdentifier : string: The identifier for this finisher

setOption()

Sets a single finisher option (@see setOptions())


    public
                    setOption(string $optionName, mixed $optionValue) : mixed

Parameters

$optionName : string: name of the option to be set
$optionValue : mixed: value of the option

setOptions()


    public
                    setOptions(array<string|int, mixed> $options) : mixed

Parameters

$options : array<string|int, mixed>: configuration options in the format ['option1' => 'value1', 'option2' => 'value2', ...]

executeInternal()

Executes this finisher


    protected
                    executeInternal() : string|void|null

Return values

string|void|null

getElementByIdentifier()

Returns a form element object for a given identifier.


    protected
                    getElementByIdentifier(string $elementIdentifier) : FormElementInterface|null

Parameters

$elementIdentifier : string

Return values

FormElementInterface|null

getFormValues()

Returns the values of the submitted form


    protected
                    getFormValues() : array<string|int, mixed>

Return values

array<string|int, mixed>

getTypoScriptFrontendController()


    protected
                    getTypoScriptFrontendController() : TypoScriptFrontendController

Return values

TypoScriptFrontendController

parseOption()

Read the option called $optionName from $this->options, and parse {...} as object accessors.


    protected
                    parseOption(string $optionName) : string|array<string|int, mixed>|int|null

Then translate the value.

If $optionName was not found, the corresponding default option is returned (from $this->defaultOptions)

Parameters

$optionName : string

Return values

string|array<string|int, mixed>|int|null

prepareData()

Prepare data for saving to database


    protected
                    prepareData(array<string|int, mixed> $elementsConfiguration, array<string|int, mixed> $databaseData) : array<string|int, mixed>

Parameters

$elementsConfiguration : array<string|int, mixed>
$databaseData : array<string|int, mixed>

Return values

array<string|int, mixed>

process()

Perform the current database operation


    protected
                    process(int $iterationCount) : mixed

Parameters

$iterationCount : int

resolveRuntimeReference()

Resolving property by name from submitted form data.


    protected
                    resolveRuntimeReference(string $property, FormRuntime $formRuntime) : int|string|array<string|int, mixed>

Parameters

$property : string
$formRuntime : FormRuntime

Return values

int|string|array<string|int, mixed>

saveToDatabase()

Save or insert the values from $databaseData into the table $table


    protected
                    saveToDatabase(array<string|int, mixed> $databaseData, string $table, int $iterationCount) : mixed

Parameters

$databaseData : array<string|int, mixed>
$table : string
$iterationCount : int

substituteRuntimeReferences()

You can encapsulate an option value with {}.


    protected
                    substituteRuntimeReferences(string|array<string|int, mixed> $needle, FormRuntime $formRuntime) : mixed

This enables you to access every gettable property from the TYPO3\CMS\Form\Domain\Runtime\FormRuntime.

For example: {formState.formValues.<elementIdentifier>} or {<elementIdentifier>}

Both examples are equal to "$formRuntime->getFormState()->getFormValues()[<elementIdentifier>]" There is a special option value '{__currentTimestamp}'. This will be replaced with the current timestamp.

Parameters

$needle : string|array<string|int, mixed>
$formRuntime : FormRuntime

throwExceptionOnInconsistentConfiguration()

Throws an exception if some inconsistent configuration are detected.


    protected
                    throwExceptionOnInconsistentConfiguration() : mixed

translateFinisherOption()

Wraps TranslationService::translateFinisherOption to recursively invoke all array items of resolved form state values or nested finisher option configuration settings.


    protected
                    translateFinisherOption(string|array<string|int, mixed> $subject, FormRuntime $formRuntime, string $optionName, string|array<string|int, mixed> $optionValue, array<string|int, mixed> $translationOptions) : array<string|int, mixed>|string

Parameters

$subject : string|array<string|int, mixed>
$formRuntime : FormRuntime
$optionName : string
$optionValue : string|array<string|int, mixed>
$translationOptions : array<string|int, mixed>

Return values

array<string|int, mixed>|string

SaveToDatabaseFinisher extends AbstractFinisher

Configuration

options.table (mandatory)

options.mode (default: insert)

options.whereClause

options.elements

options.elements.<elementIdentifier>.mapOnDatabaseColumn (mandatory)

options.elements.<elementIdentifier>.skipIfValueIsEmpty (default: false)

options.elements.<elementIdentifier>.saveFileIdentifierInsteadOfUid (default: false)

options.databaseColumnMappings

options.databaseColumnMappings.<databaseColumnName>.value

options.databaseColumnMappings.<databaseColumnName>.skipIfValueIsEmpty (default: false)

Example

finishers:

Multiple database operations

finishers:

Table of Contents

Properties

Methods

Properties

$databaseConnection

$defaultOptions

$finisherContext

$finisherIdentifier

$options

$shortFinisherIdentifier

Methods

execute()

Parameters

Return values

getFinisherIdentifier()

Return values

isEnabled()

Return values

setFinisherIdentifier()

Parameters

setOption()

Parameters

setOptions()

Parameters

executeInternal()

Tags

Return values

getElementByIdentifier()

Parameters

Return values

getFormValues()

Return values

getTypoScriptFrontendController()

Return values

parseOption()

Parameters

Return values

prepareData()

Parameters

Return values

process()

Parameters

resolveRuntimeReference()

Parameters

Return values

saveToDatabase()

Parameters

substituteRuntimeReferences()

Parameters

throwExceptionOnInconsistentConfiguration()

Tags

translateFinisherOption()

Parameters

Return values