[TASK] Document \Datetime as extbase model type (#5565)

* [TASK] Document \Datetime as extbase model type

Releases: main, 13.4

* [TASK] Language checks

Releases: main

* [TASK] Updated code snippet paths

Releases: main

---------

Co-authored-by: Sarah McCarthy <[email protected]>

Author: linawolf

Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model/PropertyTypes/Index.rst

@@ -200,6 +200,46 @@ In TYPO3 v13, boolean values are typically managed using
         ..  literalinclude:: _codesnippets/_bool_example.php
             :caption: packages/my_extension/Configuration/TCA/tx_myextension_domain_model_boolexample.php
 
+..  _extbase-model-predefined-classes:
+
+Predefined classes as types of models
+=====================================
+
+..  _extbase-model-datetime:
+
+Datetime model types
+--------------------
+
+The PHP classes :php:`\DateTime` and :php:`\DateTimeImmutable` can be used with
+the TCA field type `datetime <https://docs.typo3.org/permalink/t3tca:columns-datetime>`_
+
+The value can be stored in the database as either a unix timestamp :sql:`int(11)`
+(default) or type :sql:`datetime` (TCA :ref:`dbType <t3tca:confval-datetime-dbtype>`
+`datetime`).
+
+In the frontend they are commonly displayed using the `f:format.date
+ViewHelper <f:format.date> <https://docs.typo3.org/permalink/t3viewhelper:typo3-fluid-format-date>`_.
+
+..  tabs::
+
+    ..  group-tab:: Model
+
+        ..  literalinclude:: _codesnippets/_DateExample.php
+            :caption: packages/my_extension/Classes/Domain/Model/DateExample.php
+
+        Use :php:`\DateTimeImmutable` if you want the date to be
+        immutable.
+
+    ..  group-tab:: TCA
+
+        ..  literalinclude:: _codesnippets/_date_example.php
+            :caption: packages/my_extension/Configuration/TCA/tx_myextension_domain_model_dateexample.php
+
+    ..  group-tab:: Fluid
+
+        ..  literalinclude:: _codesnippets/_Date.html
+            :caption: packages/my_extension/Resources/Private/Templates/Date/Show.html
+
 ..  _extbase-model-enumerations:
 
 Enumerations as Extbase model property
@@ -211,8 +251,7 @@ Enumerations as Extbase model property
     has been introduced. It is no longer necessary to extend the deprecated
     TYPO3 Core class :ref:`\\TYPO3\\CMS\\Core\\Type\\Enumeration <Enumerations-How-to-use>`.
 
-
-Native PHP enumerations can be used for properties, if a database field has a
+Native PHP enumerations can be used for properties where the database field has a
 set of values which can be represented by a backed enum. A property
 with an enum type should be used with a TCA field that only allows specific
 values to be stored in the database, for example `Select fields <https://docs.typo3.org/permalink/t3tca:columns-select>`_
@@ -247,7 +286,7 @@ and `Radio buttons <https://docs.typo3.org/permalink/t3tca:columns-radio>`_.
 
     ..  group-tab:: Fluid
 
-        ..  literalinclude:: _codesnippets/_enum_example.php
+        ..  literalinclude:: _codesnippets/_EnumExample.html
             :caption: packages/my_extension/Resources/Private/Templates/Paper/Show.html
 
     ..  group-tab:: Localization

Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model/PropertyTypes/_codesnippets/_Date.html

@@ -0,0 +1,7 @@
+<f:format.date format="%d. %B %Y">{example.datetimeInt}</f:format.date>
+<f:format.date format="%d. %B %Y">{example.datetimeDatetime}</f:format.date>
+
+Or inline:
+
+{example.datetimeInt -> f:format.date(format: '%d. %B %Y')}
+{example.datetimeDatetime -> f:format.date(format: '%d. %B %Y')}

Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model/PropertyTypes/_codesnippets/_DateExample.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Domain\Model;
+
+use TYPO3\CMS\Extbase\DomainObject\AbstractEntity;
+
+class DateExample extends AbstractEntity
+{
+    /**
+     * A datetime stored in an integer field
+     */
+    public ?\DateTime $datetimeInt = null;
+
+    /**
+     * A datetime stored in a datetime field
+     */
+    public ?\DateTime $datetimeDatetime = null;
+}

Documentation/ExtensionArchitecture/Extbase/Reference/Domain/Model/PropertyTypes/_codesnippets/_date_example.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+return [
+    // ...
+    'columns' => [
+        'datetime_text' => [
+            'exclude' => true,
+            'label' => 'type=datetime, db=text',
+            'config' => [
+                'type' => 'datetime',
+            ],
+        ],
+        'datetime_int' => [
+            'exclude' => true,
+            'label' => 'type=datetime, db=int',
+            'config' => [
+                'type' => 'datetime',
+            ],
+        ],
+        'datetime_datetime' => [
+            'exclude' => true,
+            'label' => 'type=datetime, db=datetime',
+            'config' => [
+                'type' => 'datetime',
+                'dbType' => 'datetime',
+                'nullable' => true,
+            ],
+        ],
+    ],
+];