DOCSP-41335: Id alias

Author: norareidy

docs/fundamentals/read-operations.txt

@@ -552,6 +552,11 @@ This example queries for documents in which the value of the ``runtime`` field i
 ``30`` and returns the first matching document according to the value of the ``_id``
 field.
 
+.. note::
+
+   This example uses the ``id`` alias to represent the ``_id`` field, since {+odm-short+}
+   converts from ``id`` to ``_id`` automatically.
+
 .. tabs::
 
    .. tab:: Query Syntax
@@ -582,7 +587,7 @@ field.
                 public function show()
                 {
                     $movie = Movie::where('runtime', 30)
-                        ->orderBy('_id')
+                        ->orderBy('id')
                         ->first();
 
                     return view('browse_movies', [

docs/includes/query-builder/QueryBuilderTest.php

@@ -10,6 +10,7 @@
 use MongoDB\BSON\Regex;
 use MongoDB\Laravel\Collection;
 use MongoDB\Laravel\Tests\TestCase;
+use MongoDB\BSON\ObjectId;
 
 use function file_get_contents;
 use function json_decode;
@@ -63,7 +64,7 @@ public function testOrWhere(): void
         // begin query orWhere
         $result = DB::connection('mongodb')
             ->collection('movies')
-            ->where('year', 1955)
+            ->where('id', new ObjectId('573a1398f29313caabce9682'))
             ->orWhere('title', 'Back to the Future')
             ->get();
         // end query orWhere

docs/query-builder.txt

@@ -176,15 +176,23 @@ Logical OR Example
 
 The following example shows how to chain the ``orWhere()``
 query builder method to retrieve documents from the
-``movies`` collection that either match the ``year``
-value of ``1955`` or match the ``title`` value ``"Back to the Future"``:
+``movies`` collection that either match the ``_id``
+value of ``ObjectId('573a1398f29313caabce9682')`` or match
+the ``title`` value ``"Back to the Future"``:
 
 .. literalinclude:: /includes/query-builder/QueryBuilderTest.php
    :language: php
    :dedent:
    :start-after: begin query orWhere
    :end-before: end query orWhere
 
+.. note::
+
+   Beginning in {+odm-short+} v4.6, you can use the ``id`` alias to
+   represent the ``_id`` field, as shown in the preceding code. When you
+   run a find operation using the query builder, {+odm-short+}
+   automatically converts between ``id`` and ``_id``.
+
 .. _laravel-query-builder-logical-and:
 
 Logical AND Example