From f543557e172cb880330847210d70ba33e1414512 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 10 Apr 2025 15:36:52 -0400 Subject: [PATCH 1/5] DOCSP-49217: disable id alias conversion in embedded docs --- .../connection/connection-options.txt | 20 +++++++++++++++++++ docs/query-builder.txt | 5 ++++- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt index 03e98ed06..7b9d16ce4 100644 --- a/docs/fundamentals/connection/connection-options.txt +++ b/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 `__ 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); diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 68a9b2102..a73d5e791 100644 --- a/docs/query-builder.txt +++ b/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 From 2a2022af8d74a0023aa709b62de8b5d915bbb650 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 10 Apr 2025 15:46:56 -0400 Subject: [PATCH 2/5] add cross link --- docs/upgrade.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index a87d314a2..3c7e9642b 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -127,6 +127,9 @@ 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: From bbb9ab45058f40ae85ac40ece1729dbc4ccccd81 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 10 Apr 2025 15:49:05 -0400 Subject: [PATCH 3/5] typo fix --- docs/upgrade.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/upgrade.txt b/docs/upgrade.txt index 3c7e9642b..3c6ec40a4 100644 --- a/docs/upgrade.txt +++ b/docs/upgrade.txt @@ -128,7 +128,9 @@ This library version introduces the following breaking changes: 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.. + ``_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 From 9d835fdbc4824cc5bcf9942bed5d67d9392544ba Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 11 Apr 2025 09:29:10 -0400 Subject: [PATCH 4/5] JT tech review comment --- .../connection/connection-options.txt | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt index 7b9d16ce4..45a6b819e 100644 --- a/docs/fundamentals/connection/connection-options.txt +++ b/docs/fundamentals/connection/connection-options.txt @@ -362,10 +362,28 @@ 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); +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); From 1f3d3206459ad883f1ce1401ff48d83f341c4521 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 11 Apr 2025 10:03:44 -0400 Subject: [PATCH 5/5] JT tech review comment 2 --- docs/fundamentals/connection/connection-options.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/fundamentals/connection/connection-options.txt b/docs/fundamentals/connection/connection-options.txt index 45a6b819e..1a2cdb085 100644 --- a/docs/fundamentals/connection/connection-options.txt +++ b/docs/fundamentals/connection/connection-options.txt @@ -387,3 +387,10 @@ perform either of the following actions: .. 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.