DOCSP-49217: disable id alias conversion in embedded docs

Author: rustagir

docs/fundamentals/connection/connection-options.txt

@@ -32,6 +32,7 @@ This guide covers the following topics:
 
 - :ref:`laravel-connection-auth-options`
 - :ref:`laravel-driver-options`
+- :ref:`laravel-disable-id-alias`
 
 .. _laravel-connection-auth-options:
 
@@ -349,3 +350,22 @@ item, as shown in the following example:
 
 See the `$driverOptions: array <https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBClient__construct/#parameters>`__
 section of the {+php-library+} documentation for a list of driver options.
+
+.. _laravel-disable-id-alias:
+
+Disable Use of id Field Name Conversion
+---------------------------------------
+
+Starting in {+odm-long+} v5.0, ``id`` is an alias for the ``_id`` field
+in MongoDB documents, and the library automatically converts ``id``
+to ``_id`` for both top level and embedded fields when querying and
+storing data.
+
+When using {+odm-long+} v5.3 or later, you can disable the automatic
+conversion of ``id`` to ``_id`` for embedded documents. To do so, set
+the ``renameEmbeddedIdField`` connection setting to ``false``, as
+shown in the following code:
+
+.. code-block:: php
+
+   DB::connection('mongodb')->setRenameEmbeddedIdField(false);

docs/query-builder.txt

@@ -195,7 +195,7 @@ the value of the ``title`` field is ``"Back to the Future"``:
    :start-after: begin query orWhere
    :end-before: end query orWhere
 
-.. note::
+.. note:: id Alias
 
    You can use the ``id`` alias in your queries to represent the
    ``_id`` field in MongoDB documents, as shown in the preceding
@@ -208,6 +208,9 @@ the value of the ``title`` field is ``"Back to the Future"``:
    Because of this behavior, you cannot have two separate ``id`` and ``_id``
    fields in your documents.
 
+   To learn how to disable this behavior for embedded documents, see the
+   :ref:`laravel-disable-id-alias` section of the Connection Options guide.
+
 .. _laravel-query-builder-logical-and:
 
 Logical AND Example