@@ -32,6 +32,7 @@ This guide covers the following topics:
3232
3333- :ref:`laravel-connection-auth-options`
3434- :ref:`laravel-driver-options`
35+ - :ref:`laravel-disable-id-alias`
3536
3637.. _laravel-connection-auth-options:
3738
@@ -349,3 +350,47 @@ item, as shown in the following example:
349350
350351See the `$driverOptions: array <https://www.mongodb.com/docs/php-library/current/reference/method/MongoDBClient__construct/#parameters>`__
351352section of the {+php-library+} documentation for a list of driver options.
353+
354+ .. _laravel-disable-id-alias:
355+
356+ Disable Use of id Field Name Conversion
357+ ---------------------------------------
358+
359+ Starting in {+odm-long+} v5.0, ``id`` is an alias for the ``_id`` field
360+ in MongoDB documents, and the library automatically converts ``id``
361+ to ``_id`` for both top level and embedded fields when querying and
362+ storing data.
363+
364+ When using {+odm-long+} v5.3 or later, you can disable the automatic
365+ conversion of ``id`` to ``_id`` for embedded documents. To do so,
366+ perform either of the following actions:
367+
368+ 1. Set the ``rename_embedded_id_field`` setting to ``false`` in your
369+ ``config/database.php`` file:
370+
371+ .. code-block:: php
372+ :emphasize-lines: 6
373+
374+ 'connections' => [
375+ 'mongodb' => [
376+ 'dsn' => 'mongodb+srv://mongodb0.example.com/',
377+ 'driver' => 'mongodb',
378+ 'database' => 'sample_mflix',
379+ 'rename_embedded_id_field' => false,
380+ // Other settings
381+ ],
382+ ],
383+
384+ #. Pass ``false`` to the ``setRenameEmbeddedIdField()`` method in your
385+ application:
386+
387+ .. code-block:: php
388+
389+ DB::connection('mongodb')->setRenameEmbeddedIdField(false);
390+
391+ .. important::
392+
393+ We recommend using this option only to provide backwards
394+ compatibility with existing document schemas. In new projects,
395+ avoid using ``id`` for field names in embedded documents so that
396+ you can maintain {+odm-long+}'s default behavior.
0 commit comments