Datetime

Changed in version 13.0

The database type has changed from int signed to bigint signed when the field is auto-generated (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.

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.

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

A simple date field, stored as bigint in the database:

EXT:my_extension/Configuration/TCA/Overrides/some-table.php

<?php

$temporaryColumns['my-date'] = [
    'label' => 'Datetime field',
    'config' => [
        'type' => 'datetime',
        'format' => 'date',
        'default' => 0,
    ],
];

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
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/someTable.php

<?php

$datetimeField = [
    'config' => [
        'type' => 'datetime',
        'behaviour' => [
            'allowLanguageSynchronization' => true,
        ],
    ],
];

dbType

Type: string
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.

Note

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

Example: Date and time picker stored in a datetime field

ext_tables.sql

CREATE TABLE tx_example_domain_model_foo (
  synced_at datetime default NULL
)

EXT:some_extension/Configuration/TCA/tx_sometable.php

<?php

$temporaryColumns['synced_at'] = [
    'config' => [
        'type' => 'datetime',
        'dbType' => 'datetime',
        'nullable' => true,
    ],
];

Example: Time picker stored in a datetime field

ext_tables.sql

CREATE TABLE tx_example_domain_model_foo (
   synced_at time default NULL
)

EXT:some_extension/Configuration/TCA/tx_sometable.php

<?php

$temporaryColumns['synced_at'] =  [
    'config' => [
        'type' => 'datetime',
        'dbType' => 'time',
        'format' => 'time',
        'nullable' => true,
    ],
];

default

Type: string
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
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
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['fieldWizard']['defaultLanguageDifferences']

For details see defaultLanguageDifferences.

localizationStateSelector

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

For details see localizationStateSelector.

otherLanguageContent

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

For details see otherLanguageContent.

format

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

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" and "timesec" as "timesec".

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)
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
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']['nullable']
Default: false
Scope: Proc

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

Changed in version 14.0. 13.4

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

`mydatefield` bigint(20) DEFAULT NULL

Example:

EXT:some_extension/Configuration/TCA/tx_sometable.php

<?php

$temporaryColumns['my-date'] = [
    'title' => 'A nullable date',
    'config' => [
        'type' => 'datetime',
        'nullable' => true,
    ],
];

placeholder

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

Placeholder, containing a default date.

EXT:my_extension/Configuration/TCA/Overrides/some-table.php

<?php

$temporaryColumns['my-date'] = [
    'title' => 'My datetime field',
    'config' => [
        'type' => 'datetime',
        'placeholder' => gmmktime(0, 0, 0, 1, 1, 2024),
        'mode' => 'useOrOverridePlaceholder',
    ],
];

Note

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

range

Type: array
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
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 upper limit is set to the last day in year 2022 while the lowest possible value is set to the date of 2014:

EXT:some_extension/Configuration/TCA/tx_sometable.php

$temporaryColumns['my-date']['config']['range'] => [
    'upper' => gmmktime(23, 59, 59, 12, 31, 2022),
    'lower' => gmmktime(0, 0, 0, 1, 1, 2014),
];

Note

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

readOnly

Type: boolean
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

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.

See: Breaking: #106976 - Removal of TCA search field configuration options

searchable

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

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:

packages/my_extension/Configuration/TCA/Overrides/tx_my_table.php

$GLOBALS['TCA']['tx_my_table']['columns']['my_field'] = [
    'label' => 'My field',
    'config' => [
        'type' => 'datetime',
        'searchable' => false,
    ],
];

softref

Type: string
Path: $GLOBALS['TCA'][$table]['columns'][$field]['config']
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

Properties of the TCA column type datetime

behaviour

allowLanguageSynchronization

dbType

default

disableAgeDisplay

fieldControl

fieldInformation

fieldWizard

defaultLanguageDifferences

localizationStateSelector

otherLanguageContent

format

mode

nullable

placeholder

range

readOnly

searchable

softref

Properties of the TCA column type `datetime`