DOCSP-49217: disable id alias conversion in embedded docs (#3346)

* DOCSP-49217: disable id alias conversion in embedded docs

* add cross link

* typo fix

* JT tech review comment

* JT tech review comment 2

Author: rustagir

Diff for: 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,47 @@ 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,
+perform either of the following actions:
+
+1. Set the ``rename_embedded_id_field`` setting to ``false`` in your
+   ``config/database.php`` file:
+
+   .. code-block:: php
+      :emphasize-lines: 6
+   
+      'connections' => [
+          'mongodb' => [
+              'dsn' => 'mongodb+srv://mongodb0.example.com/',
+              'driver' => 'mongodb',
+              'database' => 'sample_mflix',
+              'rename_embedded_id_field' => false,
+              // Other settings
+          ],
+      ],
+
+#. Pass ``false`` to the ``setRenameEmbeddedIdField()`` method in your
+   application:
+
+   .. code-block:: php
+   
+      DB::connection('mongodb')->setRenameEmbeddedIdField(false);
+
+.. important::
+
+   We recommend using this option only to provide backwards
+   compatibility with existing document schemas. In new projects,
+   avoid using ``id`` for field names in embedded documents so that
+   you can maintain {+odm-long+}'s default behavior.

Diff for: 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

Diff for: docs/upgrade.txt

@@ -127,6 +127,11 @@ This library version introduces the following breaking changes:
   method results before hydrating a Model instance. When passing a complex query
   filter, use the ``DB::where()`` method instead of ``Model::raw()``.
 
+  Starting in v5.3, you can disable automatic conversion of ``id`` to
+  ``_id`` for embedded documents. To learn more, see the
+  :ref:`laravel-disable-id-alias` section of the Connection Options
+  guide.
+
 - Removes support for the ``$collection`` property. The following code shows
   how to assign a MongoDB collection to a variable in your ``User`` class in
   older versions compared to v5.0: