Merge pull request #12293 from nextcloud/developer/database-types

feat(developer): Document new database field types

Author: susnux

developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst

@@ -70,7 +70,8 @@ Added APIs
 
 - It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests.
   See the relevant :ref:`endpoint documentation<webdav-download-folders>`.
-- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks<setup-checks>` which need to check HTTP calls to the the server itself.
+- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks<setup-checks>`
+  which need to check HTTP calls to the the server itself.
 
 Changed APIs
 ^^^^^^^^^^^^
@@ -82,12 +83,28 @@ Changed APIs
   #. Add all parameter types to your implementation once Nextcloud 31 is the lowest supported version.
 
 - The Nextcloud implementation of the ``log`` method of ``Psr\Log\LoggerInterface`` now supports ``Psr\Log\LogLevel`` as log level parameter.
+- The ``OCP\DB\QueryBuilder\IQueryBuilder`` now supports more date / time related parameter types:
+
+  - ``PARAM_DATE_MUTABLE`` and ``PARAM_DATE_IMMUTABLE`` for passing a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the date part.
+  - ``PARAM_TIME_MUTABLE`` and ``PARAM_TIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the time part.
+  - ``PARAM_DATETIME_MUTABLE`` and ``PARAM_DATETIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance without handling of the timezone.
+  - ``PARAM_DATETIME_TZ_MUTABLE`` and ``PARAM_DATETIME_TZ_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance with handling of the timezone.
+
+- The ``OCP\\DB\\Types`` now support more date and time related types for usage with the ``Entity``:
+
+  - ``DATE_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the date part set.
+  - ``TIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the time part set.
+  - ``DATETIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set but without timezone information.
+  - ``DATETIME_TZ`` for fields that will (de)serialized as ``\DateTime`` instances with both the time part set and with timezone information.
+  - ``DATETIME_TZ_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set and with timezone information.
 
 Deprecated APIs
 ^^^^^^^^^^^^^^^
 
 - The ``/s/{token}/download`` endpoint for downloading public shares is deprecated.
   Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
+- ``OCP\DB\QueryBuilder\IQueryBuilder::PARAM_DATE`` is deprecated in favor of ``PARAM_DATETIME_MUTABLE``
+  to make clear that this type also includes the time part of a date time instance.
 
 Removed APIs
 ^^^^^^^^^^^^

developer_manual/basics/storage/database.rst

@@ -207,7 +207,9 @@ or::
 Entities
 --------
 
-Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore separated names to *lowerCamelCase* attributes:
+Entities are data objects that carry all the table's information for one row.
+Every Entity has an **id** field by default that is set to the integer type.
+Table rows are mapped from lower case and underscore separated names to *lowerCamelCase* attributes:
 
 * **Table column name**: phone_number
 * **Property name**: phoneNumber
@@ -220,6 +222,7 @@ Entities are data objects that carry all the table's information for one row. Ev
     namespace OCA\MyApp\Db;
 
     use OCP\AppFramework\Db\Entity;
+    use OCP\DB\Types;
 
     class Author extends Entity {
 
@@ -229,24 +232,35 @@ Entities are data objects that carry all the table's information for one row. Ev
 
         public function __construct() {
             // add types in constructor
-            $this->addType('stars', 'integer');
+            $this->addType('stars', Types::INTEGER);
+            // other fields are implicitly `Types::STRING`
         }
     }
 
 Types
 ^^^^^
 
-The following properties should be annotated by types, to not only assure that the types are converted correctly for storing them in the database (e.g. PHP casts false to the empty string which fails on PostgreSQL) but also for casting them when they are retrieved from the database.
+The following properties should be annotated by types, to not only assure that the types are converted correctly for storing them in the database
+(e.g. PHP casts false to the empty string which fails on PostgreSQL) but also for casting them when they are retrieved from the database.
 
-The following types can be added for a field:
+The following types (as part of ``OCP\DB\Types``) can be added for a field:
 
-* ``integer``
-* ``float``
-* ``boolean``
-* ``string`` - For text and string columns
-* ``blob`` - For binary data or strings longer than
-* ``json`` - JSON data is automatically decoded on reading
-* ``datetime`` - Providing ``\DateTime()`` objects
+* ``Types::INTEGER``
+* ``Types::FLOAT``
+* ``Types::BOOLEAN``
+* ``Types::STRING`` - For text and string columns
+* ``Types::BLOB`` - For binary data
+* ``Types::JSON`` - JSON data is automatically decoded on reading
+* For time and/or dates, provided as ``\DateTimeImmutable`` objects, the following types can be used:
+
+  * ``Types::DATE_IMMUTABLE`` - only the date is stored (without timezone)
+  * ``Types::TIME_IMMUTABLE`` - only the time is stored (without timezone)
+  * ``Types::DATETIME_IMMUTABLE`` - date and time are stored, but without timezone
+  * ``Types::DATETIME_TZ_IMMUTABLE`` - date and time are stored with timezone information
+  
+* ``Types::DATE``, ``Types::TIME``, ``Types::DATETIME``, ``Types::DATETIME_TZ`` - similar as the immutable variants, but these will be provided as ``\DateTime`` objects.
+  It is recommended to use the immutable variants as the internal state tracking of the ``Entity`` class only work with re-assignments,
+  so any changes on this mutable types will not be tracked and the update method will not write back the changes to the database.
 
 .. _database-entity-attribute-access:
 
@@ -346,14 +360,16 @@ You can add attributes to an entity class that do not map to a database column.
         }
     }
 
-It is important to define getters and setters for any transient attributes. Do not use the :ref:`magic getters and setters<database-entity-attribute-access>` of attributes that map to database columns.
+It is important to define getters and setters for any transient attributes.
+Do not use the :ref:`magic getters and setters<database-entity-attribute-access>` of attributes that map to database columns.
 
 Slugs
 ^^^^^
 
 .. deprecated:: 24
 
-Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain values, the entity base class provides a slugify method for it:
+Slugs are used to identify resources in the URL by a string rather than integer id.
+Since the URL allows only certain values, the entity base class provides a slugify method for it:
 
 .. code-block:: php