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 its format 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 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
Copied!
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.

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.