DOCSP-43159: QB returns objects (#3135)

* DOCSP-43159: QB returns objects

* add to upgrade guide

* add depth layer

* JT tech review 2

* wip

Author: rustagir

docs/query-builder.txt

@@ -38,15 +38,20 @@ testability.
 
 The {+odm-short+} provides the ``DB`` method ``table()`` to access a collection.
 Chain methods to specify commands and any constraints. Then, chain
-the ``get()`` method at the end to run the methods and retrieve the results.
+the ``get()`` method at the end to run the methods and retrieve the
+results. To retrieve only the first matching result, chain the
+``first()`` method instead of the ``get()`` method. Starting in
+{+odm-long+} v5.0, the query builder returns results as ``stdClass`` objects.
+
 The following example shows the syntax of a query builder call:
 
 .. code-block:: php
 
    DB::table('<collection name>')
        // chain methods by using the "->" object operator
        ->get();
-.. tip::
+
+.. tip:: Set Database Connection
 
    Before using the ``DB::table()`` method, ensure that you specify MongoDB as your application's
    default database connection. For instructions on setting the database connection,

docs/upgrade.txt

@@ -14,7 +14,7 @@ Upgrade Library Version
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Overview
@@ -71,6 +71,26 @@ Version 5.x Breaking Changes
 
 This library version introduces the following breaking changes:
 
+- The query builder returns results as as ``stdClass`` objects instead
+  of as arrays. This change requires that you change array access to
+  property access when interacting with query results.
+
+  The following code shows how to retrieve a query result and access a
+  property from the result object in older versions compared to v5.0:
+
+  .. code-block:: php
+     :emphasize-lines: 8-9
+
+     $document = DB::table('accounts')
+         ->where('name', 'Anita Charles')
+         ->first();
+
+     // older versions
+     $document['balance'];
+
+     // v5.0
+     $document->balance;
+
 - Removes support for the following classes:
 
   - ``MongoDB\Laravel\Auth\DatabaseTokenRepository``. Instead, use the default