DOCSP-41335: Id field alias (#3042)

Adds information and an example of the ID field alias.
---------

Co-authored-by: norareidy <norareidy@users.noreply.github.com>
Co-authored-by: rustagir <rea.rustagi@mongodb.com>

docs/eloquent-models/model-class.txt

@@ -302,12 +302,8 @@ including this trait, you can make the third-party class compatible with
 MongoDB.
 
 When you apply the ``DocumentModel`` trait to a model class, you must
-declare the following properties in your class:
-
-- ``$primaryKey = '_id'``, because the ``_id`` field uniquely
- identifies MongoDB documents
-- ``$keyType = 'string'``, because the {+odm-short+} casts MongoDB
- ``ObjectId`` values to type ``string``
+set the ``$keyType`` property to ``'string'`` as the {+odm-short+}
+casts MongoDB ``ObjectId`` values to type ``string``.
 
 Extended Class Example
 ~~~~~~~~~~~~~~~~~~~~~~

docs/includes/query-builder/QueryBuilderTest.php

@@ -7,6 +7,7 @@
 use Illuminate\Database\Query\Builder;
 use Illuminate\Pagination\AbstractPaginator;
 use Illuminate\Support\Facades\DB;
+use MongoDB\BSON\ObjectId;
 use MongoDB\BSON\Regex;
 use MongoDB\Laravel\Collection;
 use MongoDB\Laravel\Tests\TestCase;
@@ -63,7 +64,7 @@ public function testOrWhere(): void
  // begin query orWhere
  $result = DB::connection('mongodb')
  ->table('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,28 @@ 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 in which the value of the ``_id``
+field is ``ObjectId('573a1398f29313caabce9682')`` or
+the value of the ``title`` field is ``"Back to the Future"``:
 
 .. literalinclude:: /includes/query-builder/QueryBuilderTest.php
  :language: php
  :dedent:
  :start-after: begin query orWhere
  :end-before: end query orWhere
 
+.. note::
+
+ You can use the ``id`` alias in your queries to represent the
+ ``_id`` field in MongoDB documents, as shown in the preceding
+ code. When you run a find operation using the query builder, {+odm-short+}
+ automatically converts between ``id`` and ``_id``. This provides better
+ compatibility with Laravel, as the framework assumes that each record has a
+ primary key named ``id`` by default.
+
+ Because of this behavior, you cannot have two separate ``id`` and ``_id``
+ fields in your documents.
+
 .. _laravel-query-builder-logical-and:
 
 Logical AND Example

docs/upgrade.txt

@@ -74,6 +74,11 @@ 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.
 
+- ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library
+ automatically converts between ``id`` and ``_id`` when querying data. Because
+ of this behavior, you cannot have two separate ``id`` and ``_id`` fields in your
+ documents.
+
 .. _laravel-breaking-changes-v4.x:
 
 Version 4.x Breaking Changes