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.

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,
    ],
];
Copied!

Properties of the TCA column type datetime

Name Type Scope
boolean Proc.
string Proc.
string Display / Proc.
boolean Display
array
array
array
string (keyword) Display
string (keywords) Display
boolean Proc
integer Unix timestamp Display
array Proc.
boolean Display
array Search
boolean
boolean
string
string Proc.

behaviour

behaviour

allowLanguageSynchronization

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,
        ],
    ],
];
Copied!

dbType

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.

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
)
Copied!
EXT:some_extension/Configuration/TCA/tx_sometable.php
<?php

$temporaryColumns['synced_at'] = [
    'config' => [
        'type' => 'datetime',
        'dbType' => 'datetime',
        'nullable' => true,
    ],
];
Copied!
Example: Time picker stored in a datetime field
ext_tables.sql
CREATE TABLE tx_example_domain_model_foo (
   synced_at time default NULL
)
Copied!
EXT:some_extension/Configuration/TCA/tx_sometable.php
<?php

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

default

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

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

It will be respected if the field has the type datetime and it's eval is set to date.

fieldControl

fieldControl

For details see fieldControl.

fieldInformation

fieldInformation

For details see fieldInformation.

fieldWizard

fieldWizard

defaultLanguageDifferences

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

For details see defaultLanguageDifferences.

localizationStateSelector

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

For details see localizationStateSelector.

otherLanguageContent

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

For details see otherLanguageContent.

format

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

mode

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.

nullable

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

If set to true, a checkbox will appear, which by default deactivates the field. In the deactivated state the field is saved as NULL in the database. By activating the checkbox it is possible to set a value. If nothing is entered into the field, then an empty string will be saved and not a NULL.

The database field must allow the NULL value.

Example:
EXT:some_extension/Configuration/TCA/tx_sometable.php
<?php

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

placeholder

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',
    ],
];
Copied!

range

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),
];
Copied!

readOnly

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.

search

Type
array
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']
Scope
Search
Types
input

Defines additional search-related options for a given field.

pidonly

pidonly
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['pidonly']

Searches in the column only if search happens on the single page, does not search the field if searching in the whole table.

case

case
Type
boolean
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['case']

Makes the search case-sensitive. This requires a proper database collation for the field, see your database documentation.

andWhere

andWhere
Type
string
Path
$GLOBALS['TCA'][$table]['columns'][$field]['config']['search']['andWhere']

Additional SQL WHERE statement without 'AND'. With this it is possible to place an additional condition on the field when it is searched

EXT:some_extension/Configuration/TCA/tx_sometable.php
$temporaryColumns['some_date'] => [
    'config' => [
        'search' => [
            'andWhere' => '{#CType}=\'type_x\' OR {#CType}=\'type_y\'',
        ],
        // ...
    ],
];
Copied!

This means that the "some_date" field of the "tt_content" table will be searched in only for elements of type X and Y. This helps making any search more relevant.

The above example uses the special field quoting syntax {#...} around identifiers to be as DBAL-compatible as possible.

softref

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.