Datetime

Changed in version 14.0

The TCA configuration config option type=datetime can now specify the format=datetimesec format to offer a date/time picker for entering a date (day, month, year) with a specific time (hour, minute, second).

Previously, only a datepicker for hour and minute was available, even though the utilized component (Flatpickr) supports entering seconds.

This format can either be specified for dbType=datetime (native SQL datetime columns based on a timestamp that always includes seconds) or for the integer-based storage without a dbType option (UNIX timestamp).

The TCA type datetime should be used to input values representing a date time or datetime.

The according database field is generated automatically as bigint signed (with the exception of the columns tstamp, crdate, starttime, endtime that still use int signed). This allows to store dates from some million years ago to far into the future.

Note

TYPO3 does not handle the following dates properly:

Before Christ (negative year)
double-digit years

Table of contents:

Example: A simple date field, stored as bigint

The date of a conference, stored as bigint in the database:

EXT:my_extension/Configuration/TCA/tx_myextension_conference.php

<?php

return [
  'ctrl' => [
    'title' => 'my_extension.db:conference',
    'label' => 'title',
    'descriptionColumn' => 'internal_notes',
    'default_sortby' => 'conference_date DESC',
    'tstamp' => 'tstamp',
    'crdate' => 'crdate',
    'delete' => 'deleted',
    'editlock' => 'editlock',
    'enablecolumns' => [
      'disabled' => 'hidden',
      'starttime' => 'starttime',
      'endtime' => 'endtime',
      'fe_group' => 'fe_group',
    ],
    'languageField' => 'sys_language_uid',
    'transOrigPointerField' => 'l10n_parent',
    'transOrigDiffSourceField' => 'l10n_diffsource',
    'translationSource' => 'l10n_source',
    'versioningWS' => true,
    'origUid' => 't3_origuid',
    'iconfile' => 'EXT:my_extension/Resources/Public/Icons/Conference.svg',
    'security' => [
      'ignorePageTypeRestriction' => true,
    ],
  ],
  'columns' => [
    'title' => [
      'label' => 'my_extension.db:conference.title',
      'config' => [
        'type' => 'input',
        'required' => true,
        'max' => 255,
        'eval' => 'trim',
      ],
    ],
    'conference_date' => [
      'label' => 'my_extension.db:conference.conference_date',
      'config' => [
        'type' => 'datetime',
        'format' => 'date',
        'required' => true,
      ],
    ],
    'internal_notes' => [
      'label' => 'my_extension.db:conference.internal_notes',
      'config' => [
        'type' => 'text',
        'rows' => 3,
      ],
    ],
  ],
  // The fields of the other tabs are added in Configuration/TCA/Overrides/
  'types' => [
    '0' => [
      'showitem' => '
        title, conference_date,
        --div--;my_extension.db:tab.program,
        --div--;my_extension.db:tab.details,
        --div--;core.form.tabs:categories,
        --div--;core.form.tabs:access,
          hidden, --palette--;;access, fe_group, editlock,
        --div--;core.form.tabs:language,
          --palette--;;language,
        --div--;my_extension.db:tab.comments,
        --div--;core.form.tabs:notes,
          internal_notes,
      ',
    ],
  ],
  'palettes' => [
    'access' => [
      'label' => 'core.form.palettes:access',
      // The labels of the fields tell the editors what the dates are for
      'showitem' => '
        starttime;my_extension.db:conference.starttime,
        endtime;my_extension.db:conference.endtime,
      ',
    ],
    'language' => [
      'showitem' => 'sys_language_uid, l10n_parent',
    ],
  ],
];

Example: A simple date field with seconds

A date field that also shows the seconds, formatted with datetimesec:

'format' => 'datetimesec',

Properties of the TCA column type `datetime`

Name	Type	Scope
behaviour
allowLanguageSynchronization	boolean	Proc.
dbType	string	Proc.
default	string	Display / Proc.
disableAgeDisplay	boolean	Display
fieldControl
fieldInformation
fieldWizard
defaultLanguageDifferences	array
localizationStateSelector	array
otherLanguageContent	array
format	string (keyword)	Display
mode	string (keywords)	Display
nullable	boolean	Proc.
placeholder	integer Unix timestamp	Display
range	array	Proc.
readOnly	boolean	Display
searchable	boolean	Display
softref	string	Proc.

behaviour

allowLanguageSynchronization

Type: boolean
Default: false
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['behaviour']['allowLanguageSynchronization']
Scope: Proc.

Allows an editor to select in a localized record whether the value is copied over from default or source language record, or if the field has an own value in the localization. If set to true and if the table supports localization and if a localized record is edited, this setting enables FieldWizard LocalizationStateSelector: Two or three radio buttons shown below the field input. The state of this is stored in a json encoded array in the database table called l10n_state. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.

        EXT:my_extension/Configuration/TCA/Overrides/215-tx_myextension_talk-start_time.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_talk', [
  'start_time' => [
    'label' => 'my_extension.db:talk.start_time',
    'config' => [
      'type' => 'datetime',
      'format' => 'datetime',
      'behaviour' => [
        'allowLanguageSynchronization' => true,
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_talk',
  'start_time',
  '',
  'after:speaker',
);

dbType

Type: string
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['dbType']
Scope: Proc.

If set, the date or time will not be stored as timestamp, but as native date, time or datetime field in the database. Keep in mind that no timezone conversion will happen.

TYPO3 creates the database column with the native type, so it does not need an entry in ext_tables.sql.

Note

When this property is not set the datetime value is automatically converted to an int.

Example: The registration deadline stored in a datetime field

        EXT:my_extension/Configuration/TCA/Overrides/117-tx_myextension_conference-registration_deadline.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'registration_deadline' => [
    'label' => 'my_extension.db:conference.registration_deadline',
    'displayCond' => 'FIELD:registration_open:REQ:true',
    'config' => [
      'type' => 'datetime',
      'dbType' => 'datetime',
      'nullable' => true,
      'searchable' => false,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'registration_deadline',
  '',
  'after:registration_open',
);

Example: The time the doors open, stored in a time field

        EXT:my_extension/Configuration/TCA/Overrides/114-tx_myextension_conference-doors_open.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'doors_open' => [
    'label' => 'my_extension.db:conference.doors_open',
    'config' => [
      'type' => 'datetime',
      'format' => 'time',
      'dbType' => 'time',
      'nullable' => true,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'doors_open',
  '',
  'after:end_date',
);

default

Type: string
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['default']
Scope: Display / Proc.

Default value set if a new record is created. If empty, no date gets initially selected.

disableAgeDisplay

Type: boolean
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['disableAgeDisplay']
Scope: Display

Disable the display of the age (for example "2015-08-30 (-27 days)") of date fields in some places of the backend, for instance the Content > Records module.

It will be respected if the field has the type datetime and its format is set to date.

fieldControl: For details see fieldControl.

fieldInformation: For details see fieldInformation.

fieldWizard

defaultLanguageDifferences

Type: array
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector

Type: array
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['localizationStateSelector']

For details see localizationStateSelector.

otherLanguageContent

Type: array
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['otherLanguageContent']

For details see otherLanguageContent.

format

Type: string (keyword)
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['format']
Scope: Display

Keywords: date, datetime, time, timesec, datetimesec

New in version 14.0

New format datetimesec to have the possibility to store times with seconds. Previously, only a datepicker for hour and minute was available.

Sets the output format if the field is set to read-only. Read-only fields with format set to "date" will be formatted as "date", "datetime" as "datetime", "time" as "time", "timesec" as "timesec" and "datetimesec" as "datetimesec".

The format datetimesec is only allowed for:

empty ['config']['dbType'] (defaults to integer-based storage type)
['config']['dbType'] = 'datetime' (native date and time storage type)

Other types (date, time, timesec) do not support both components and would yield unconsistent data.

datetimesec can be set for any TCA field that already internally receives a UNIX timestamp value.

Note

The format option defines how the field value will be displayed, for example, in FormEngine. The storage format is defined via dbType and falls back to eval=integer.

mode

Type: string (keywords)
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['mode']
Scope: Display

Possible keywords: useOrOverridePlaceholder

This property is related to the placeholder property. When defined, a checkbox will appear above the field. If that box is checked, the field can be used to enter whatever the user wants as usual. If the box is not checked, the field becomes read-only and the value saved to the database will be NULL.

Warning

In order for this property to apply properly, the DB column must be allowed to be NULL, and property nullable must be set to true.

nullable

Type: boolean
Default: false
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['nullable']
Scope: Proc.

If nothing is entered into the field, then it will be saved as NULL.

Changed in version 14.0.

For nullable integer-based datetime fields, the value 0 explicitly represents the Unix epoch time (1970-01-01T00:00:00Z) instead of being interpreted as an empty value by FormEngine.

Only an explicit null database value will be considered an empty value.

Nullable database fields will be automatically created with NULL as a default value:

Nullable datetime schema after this change

`end_date` bigint(20) DEFAULT NULL

Example: The last day of a conference that may last one day only

        EXT:my_extension/Configuration/TCA/Overrides/113-tx_myextension_conference-end_date.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'end_date' => [
    'label' => 'my_extension.db:conference.end_date',
    'config' => [
      'type' => 'datetime',
      'format' => 'date',
      'nullable' => true,
      // The conference series runs from 2020 to 2030
      'range' => [
        'lower' => mktime(0, 0, 0, 1, 1, 2020),
        'upper' => mktime(23, 59, 59, 12, 31, 2030),
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'end_date',
  '',
  'after:conference_date',
);

placeholder

Type: integer Unix timestamp
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['placeholder']
Scope: Display

Placeholder, containing a default date.

'placeholder' => '2027-05-12',
'nullable' => true,
'mode' => 'useOrOverridePlaceholder',

Note

As the TCA is cached it is not possible to set dynamic values such as now().

range

Type: array
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['range']
Scope: Proc.

An array which defines an integer range within which the value must be. Keys:

lower: Defines the earliest date.
upper: Defines the latest date.

It is allowed to specify only one or both of them.

In this example, the earliest end date of a conference is the first day of 2020, and the latest end date is the last day of 2030:

        EXT:my_extension/Configuration/TCA/Overrides/113-tx_myextension_conference-end_date.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'end_date' => [
    'label' => 'my_extension.db:conference.end_date',
    'config' => [
      'type' => 'datetime',
      'format' => 'date',
      'nullable' => true,
      // The conference series runs from 2020 to 2030
      'range' => [
        'lower' => mktime(0, 0, 0, 1, 1, 2020),
        'upper' => mktime(23, 59, 59, 12, 31, 2030),
      ],
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'end_date',
  '',
  'after:conference_date',
);

Note

As the TCA is cached, it is not possible to set dynamic values such as now().

readOnly

Type: boolean
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['readOnly']
Scope: Display

Renders the field in a way that the user can see the value but cannot edit it.

Warning

This property affects only the display. It is still possible to write to those fields when using the DataHandler.

Changed in version 14.0 Breaking: #106976 - Removal of TCA search field configuration options

The following TCA field level search configuration options have been removed:

search.case
search.pidonly
search.andWhere

They have not been supported by the Core or common Extensions.

searchable

Type: boolean
Default: true
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['searchable']
Scope: Display

New in version 14.0

TYPO3 now automatically includes all fields of suitable types in backend search operations in the Content > Records module.

This option can be used to explicitly exclude fields from being searchable, instead of having to list them in the now removed option $GLOBALS['TCA'][$table]['ctrl']['searchFields'].

By default, fields of type datetime are considered searchable unless they use a custom dbType.

To exclude a field from being searchable, set the following in the field's TCA configuration:

        EXT:my_extension/Configuration/TCA/Overrides/117-tx_myextension_conference-registration_deadline.php
    

<?php

use TYPO3\CMS\Core\Utility\ExtensionManagementUtility;

defined('TYPO3') or die();

ExtensionManagementUtility::addTCAcolumns('tx_myextension_conference', [
  'registration_deadline' => [
    'label' => 'my_extension.db:conference.registration_deadline',
    'displayCond' => 'FIELD:registration_open:REQ:true',
    'config' => [
      'type' => 'datetime',
      'dbType' => 'datetime',
      'nullable' => true,
      'searchable' => false,
    ],
  ],
]);
ExtensionManagementUtility::addToAllTCAtypes(
  'tx_myextension_conference',
  'registration_deadline',
  '',
  'after:registration_open',
);

softref

Type: string
TCA path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['softref']
Scope: Proc.
Types: input

Used to attach "soft reference parsers".

The syntax for this value is key1,key2[parameter1;parameter2;...],...

See Soft references of core API for more details about softref keys.

Datetime

Example: A simple date field, stored as bigint

Example: A simple date field with seconds

Properties of the TCA column type datetime

Properties of the TCA column type `datetime`