4.x datetime type

en/appendices/4-0-migration-guide.rst

@@ -145,6 +145,12 @@ Miscellaneous
 New Features
 ============
 
+Database
+--------
+
+* If your database's timezone does not match PHP timezone then you can use the
+  ``DateTime::setTimezone()`` method. See :ref:`datetime-type` for details.
+
 Filesystem
 ----------
 

en/orm/database-basics.rst

@@ -346,14 +346,11 @@ boolean
 binary
     Maps to the ``BLOB`` or ``BYTEA`` type provided by the database.
 date
-    Maps to a timezone naive ``DATE`` column type. The return value of this column
+    Maps to a native ``DATE`` column type. The return value of this column
     type is :php:class:`Cake\\I18n\\Date` which extends the native ``DateTime``
     class.
 datetime
-    Maps to a timezone naive ``DATETIME`` column type. In PostgreSQL, and SQL Server
-    this turns into a ``TIMESTAMP`` type. The default return value of this column
-    type is :php:class:`Cake\\I18n\\Time` which extends the built-in
-    ``DateTime`` class and `Chronos <https://github.com/cakephp/chronos>`_.
+    See :ref:`datetime-type`.
 timestamp
     Maps to the ``TIMESTAMP`` type.
 time
@@ -372,6 +369,25 @@ automatically convert input parameters from ``DateTime`` instances into a
 timestamp or formatted datestrings. Likewise, 'binary' columns will accept file
 handles, and generate file handles when reading data.
 
+.. _datetime-type:
+
+DateTime Type
+-------------
+
+.. php:class:: Type\DateTimeType
+
+Maps to a native ``DATETIME`` column type. In PostgreSQL, and SQL Server
+this turns into a ``TIMESTAMP`` type. The default return value of this column
+type is :php:class:`Cake\\I18n\\FrozenTime` which extends the built-in
+``DateTimeImmutable`` class and `Chronos <https://github.com/cakephp/chronos>`_.
+
+.. php:method:: setTimezone(string|\DateTimeZone|null $timezone)
+
+If your database server's timezone does not match your application's PHP timezone
+then you can use this method to specify your database's timezone. This timezone
+will then used when converting PHP objects to database's datetime string and
+vice versa.
+
 .. _adding-custom-database-types:
 
 Adding Custom Types