Feature: #97232 - New TCA type "datetime"

[sabbelasichon]

Feature: #97232 - New TCA type "datetime"

https://docs.typo3.org/c/typo3/cms-core/master/en-us/Changelog/12.0/Feature-97232-NewTCATypeDatetime.html
.. include:: /Includes.rst.txt

.. _feature-97232:

=========================================
Feature: #97232 - New TCA type "datetime"

See :issue:97232

Description

Especially TCA type :php:input has a wide range of use cases, depending
on the configured :php:renderType and the :php:eval options. Determination
of the semantic meaning is therefore usually quite hard and often leads to
duplicated checks and evaluations in custom extension code.

In our effort of introducing dedicated TCA types for all those use
cases, the TCA type :php:datetime has been introduced. It replaces the
:php:renderType=inputDateTime of TCA type :php:input.

The TCA type :php:datetime features the following column configuration:

• :php:behaviour: :php:allowLanguageSynchronization
• :php:dbType: :php:date, :php:time, :php:datetime
• :php:default
• :php:disableAgeDisplay
• :php:fieldControl
• :php:fieldInformation
• :php:fieldWizard
• :php:format: :php:datetime (default), :php:date, :php:time, :php:timesec
• :php:mode
• :php:nullable
• :php:placeholder
• :php:range: :php:lower, :php:upper
• :php:readOnly
• :php:required
• :php:search
• :php:size

.. note::

The :php:eval=integer option is now automatically set for the element
in case no specific :php:dbType has been defined. It should therefore
be removed from the TCA configuration.

.. note::

The :php:format option defines how the display of the field value
will be in e.g. FormEngine. The storage format is defined via :php:dbType
and falls back to :php:eval=integer.

The following column configuration can be overwritten by page TSconfig:

• :typoscript:readOnly
• :typoscript:size

A complete migration from :php:renderType=inputDateTime to :php:type=datetime
looks like the following:

.. code-block:: php

// Before

'a_datetime_field' => [
    'label' => 'Datetime field',
    'config' => [
        'type' => 'input',
        'renderType' => 'inputDateTime',
        'required' => true,
        'size' => 20,
        'max' => 1024,
        'eval' => 'date,int',
        'default' => 0,
    ],
],

// After

'a_datetime_field' => [
    'label' => 'Datetime field',
    'config' => [
        'type' => 'datetime',
        'format' => 'date',
        'required' => true,
        'size' => 20,
        'default' => 0,
    ]
]

An automatic TCA migration is performed on the fly, migrating all occurrences
to the new TCA type and triggering a PHP :php:E_USER_DEPRECATED error
where code adoption has to take place.

.. note::

The corresponding FormEngine class has been renamed from :php:`InputDateTimeElement`
to :php:`DatetimeElement`. An entry in the "ClassAliasMap" has been added
for extensions calling this class directly, which is rather unlikely. The
extension scanner will report any usage, which should then be migrated.

Automatic database fields

TYPO3 automatically creates database fields for TCA type :php:datetime
columns, if they have not already been defined in an extension's
:file:ext_tables.sql file. This also supports columns, having a
native database type (:php:dbType) defined. Fields without a native
type always define :sql:default 0 and are always signed (to allow
negative timestamps). As long as a column does not use :php:nullable=true,
the fields are also always defined as :sql:NOT NULL.

Impact

It's now possible to simplify the TCA configuration by using the new
dedicated TCA type :php:datetime. Next to reduced TCA configuration,
the new type allows to omit the corresponding database field definition.

.. index:: Backend, TCA, ext:backend