DOCSP-43158: carbon date values db query results (#3133)

* DOCSP-43158: carbon date values db query results

* add to upgrade guide

* wip

Author: rustagir

docs/eloquent-models/model-class.txt

@@ -216,8 +216,8 @@ type, to the Laravel ``datetime`` type.
    To learn more, see `Attribute Casting <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-mutators#attribute-casting>`__
    in the Laravel documentation.
 
-This conversion lets you use the PHP `DateTime <https://www.php.net/manual/en/class.datetime.php>`__
-or the `Carbon class <https://carbon.nesbot.com/docs/>`__ to work with dates
+This conversion lets you use the PHP `DateTime
+<https://www.php.net/manual/en/class.datetime.php>`__ class to work with dates
 in this field. The following example shows a Laravel query that uses the
 casting helper on the model to query for planets with a ``discovery_dt`` of
 less than three years ago:
@@ -226,6 +226,13 @@ less than three years ago:
 
    Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get();
 
+.. note:: Carbon Date Class
+
+   Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB
+   are returned as `Carbon <https://carbon.nesbot.com/docs/>`__ date
+   classes in query results. The {+odm-short+} applies the default
+   timezone when performing this conversion.
+
 To learn more about MongoDB's data types, see :manual:`BSON Types </reference/bson-types/>`
 in the Server manual.
 

docs/query-builder.txt

@@ -346,6 +346,13 @@ query builder method to retrieve documents from the
    :start-after: begin query whereDate
    :end-before: end query whereDate
 
+.. note:: Date Query Result Type
+
+   Starting in {+odm-long+} v5.0, ``UTCDateTime`` BSON values in MongoDB
+   are returned as `Carbon <https://carbon.nesbot.com/docs/>`__ date
+   classes in query results. The {+odm-short+} applies the default
+   timezone when performing this conversion.
+
 .. _laravel-query-builder-pattern:
 
 Text Pattern Match Example

docs/upgrade.txt

@@ -22,7 +22,7 @@ Overview
 
 On this page, you can learn how to upgrade {+odm-long+} to a new major version.
 This page also includes the changes you must make to your application to upgrade
-your object-document mapper (ODM) version without losing functionality, if applicable.
+your version of the {+odm-short+} without losing functionality, if applicable.
 
 How to Upgrade
 --------------
@@ -61,6 +61,19 @@ version releases that introduced them. When upgrading library versions,
 address all the breaking changes between your current version and the
 planned upgrade version.
 
+- :ref:`laravel-breaking-changes-v5.x`
+- :ref:`laravel-breaking-changes-v4.x`
+
+.. _laravel-breaking-changes-v5.x:
+
+Version 5.x Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library version introduces the following breaking changes:
+
+- In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon``
+  date classes, applying the default timezone.
+
 .. _laravel-breaking-changes-v4.x:
 
 Version 4.x Breaking Changes