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

Table of Contents

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

Properties

$defaultOptions

These are the default options of the finisher.

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

$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 = ''

Methods

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', ...]

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>

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
Tags
throws
FinisherException

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 

        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results