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 content
Example: A simple date field, stored as bigint
A simple date field, stored as bigint
in the database:
Properties of the TCA column type datetime
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_
. It tells the DataHandler which fields of the localization records should be kept in sync if the underlying default or source record changes.state
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
ordatetime
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
.
CREATE TABLE tx_example_domain_model_foo (
synced_at datetime default NULL
)
<?php
$temporaryColumns['synced_at'] = [
'config' => [
'type' => 'datetime',
'dbType' => 'datetime',
'nullable' => true,
],
];
CREATE TABLE tx_example_domain_model_foo (
synced_at time default NULL
)
<?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 list module.
It will be respected if the field has the type
datetime
and it's eval is set todate
.
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 toeval=integer
.
mode
-
- Type
- string (keywords)
- Path
- $GLOBALS['TCA'][$table]['columns'][$field]['config']['mode']
- Scope
- Display
Possible keywords:
use
Or Override Placeholder 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 beNULL
.Warning
In order for this property to apply properly, the DB column must be allowed to be
NULL
, and propertynullable
must be set totrue
.
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 aNULL
.The database field must allow the
NULL
value.
<?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.
<?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:
$temporaryColumns['my-date']['config']['range'] => [ 'upper' => gmmktime(23, 59, 59, 12, 31, 2022), 'lower' => gmmktime(0, 0, 0, 1, 1, 2014), ];
Copied!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.
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
-
- 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
-
- 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
-
- 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
$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
-
- 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.