Setting rename_embedded_id_field to false prevents application setting the main id/_id field

[ctadlock]

• Laravel-mongodb Version: 5.4.1
• PHP Version: 8.4
• Laravel: 12.20.0

Description:

Steps to reproduce

1. Set rename_embedded_id_field to false in config
2. Set a documents id field to an application value "12345"
3. insert the model

Expected behaviour

The _id field should be "12345"

Actual behaviour

A generated ObjectID is used

Logs:

Insert log.txt here (if necessary)

Im setting this value because I have a nested object with id google.id that I dont want to be _id

[ctadlock]

I just noticed that both _id and id are being set in my Account document.

[alcaeus]

As the name implies, the rename_embedded_id_field option allows disabling ID field renaming in embedded documents. Since you are using id within the google embedded document, this is indeed the right option to enable so that the field will continue to be written and read as id. This setting however does not affect root documents.

In my quick testing, I was able to confirm that setting an id field on a model correctly maps this to _id, and no id field is being created:

$user        = new User();
$user->id    = 12345;
$user->name  = 'John Doe';
$user->title = 'admin';
$user->age   = 35;

$user->save();

While this behaviour is different from previous major versions of this library, it is the intended behaviour as the primary key in MongoDB is always _id. Since there are some Laravel libraries and modules that use a hardcoded id primary key, we had no other choice than to map id to _id - anything else would create documents that use a potentially unindexed (and thus not guaranteed to be unique) field as primary keys.

[ctadlock]

Well in my code its pretty clear that setting rename_embedded_id_field totally changes the behavior of the main primary key resulting in both _id and id.

I just worked around the problem.

[alcaeus]

Would you be able to share a reproducer for this? I tested it again and couldn't see that behaviour regardless of the rename_embedded_id_field setting. Just to confirm, this is not a document that already exists in the database, but it's freshly created?

[ctadlock]

Yes for new documents. I just double checked and the error still exists.

If rename_embedded_id_field is false it messes up the primary key on the model; it uses its own ObjectID, and then inserts my identifier in as id, but not as the primary key.

[ctadlock]

rename_embedded_id_field => false

• _id set to ObjectId and PK (bad)
• id present and my id, but not PK (bad)
• nested id (good)

[2025-07-18 06:30:41] dev.DEBUG: cloud: { "insert" : "accounts", "ordered" : true, "documents" : [ { "email" : { "value" : "xxx@gototags.com", "verified" : { "at" : { "$date" : { "$numberLong" : "1752820241437" } }, "value" : true } }, "description" : null, "name" : "Craig Tadlock", "social" : { "google" : { "at" : { "$date" : { "$numberLong" : "1752820218257" } }, "avatar" : "https://lh3.googleusercontent.com/a/ACg8ocJdNpd0gpyg6PvxiYLsHIAStkrCeMX5cW0CXv5nDeK0m_uFg4U=s96-c", "email" : "xxx@gototags.com", "name" : "Craig Tadlock", "id" : "114871314056949341862", "raw" : { "sub" : "114871314056949341862", "name" : "Craig Tadlock", "given_name" : "Craig", "family_name" : "Tadlock", "picture" : "https://lh3.googleusercontent.com/a/ACg8ocJdNpd0gpyg6PvxiYLsHIAStkrCeMX5cW0CXv5nDeK0m_uFg4U=s96-c", "email" : "xxx@gototags.com", "email_verified" : true, "hd" : "gototags.com" } } }, "registered" : { "at" : { "$date" : { "$numberLong" : "1752820241438" } }, "value" : true }, "id" : "nySKNo0y0Y", "created" : { "at" : { "$date" : { "$numberLong" : "1752820241438" } } }, "updated" : { "at" : { "$date" : { "$numberLong" : "1752820241438" } } }, "_id" : { "$oid" : "6879ea11bab1eea6c00c83d2" } } ] } []

rename_embedded_id_field => true

• no ObjectID (good)
• _id set to my ID as pk (good)
• nested _id (bad)

[2025-07-18 06:37:12] dev.DEBUG: cloud: { "insert" : "accounts", "ordered" : true, "documents" : [ { "email" : { "value" : "craig@gototags.com", "verified" : { "at" : { "$date" : { "$numberLong" : "1752820632114" } }, "value" : true } }, "description" : null, "name" : "Craig Tadlock", "social" : { "google" : { "at" : { "$date" : { "$numberLong" : "1752820607889" } }, "avatar" : "https://lh3.googleusercontent.com/a/ACg8ocJdNpd0gpyg6PvxiYLsHIAStkrCeMX5cW0CXv5nDeK0m_uFg4U=s96-c", "email" : "craig@gototags.com", "name" : "Craig Tadlock", "raw" : { "sub" : "116871314056999341861", "name" : "Craig Tadlock", "given_name" : "Craig", "family_name" : "Tadlock", "picture" : "https://lh3.googleusercontent.com/a/ACg8ocJdNpd0gpyg6PvxiYLsHIAStkrCeMX5cW0CXv5nDeK0m_uFg4U=s96-c", "email" : "craig@gototags.com", "email_verified" : true, "hd" : "gototags.com" }, "_id" : "116871314056999341861" } }, "registered" : { "at" : { "$date" : { "$numberLong" : "1752820632114" } }, "value" : true }, "created" : { "at" : { "$date" : { "$numberLong" : "1752820632115" } } }, "updated" : { "at" : { "$date" : { "$numberLong" : "1752820632115" } } }, "_id" : "5gWEZEU8AV" } ] } []  

WORKING

rename_embedded_id_field not set

• no ObjectID (good)
• _id set to my ID as pk (good)
• nested _id (bad)

[2025-07-18 06:32:02] dev.DEBUG: cloud: { "insert" : "accounts", "ordered" : true, "documents" : [ { "email" : { "value" : "xxx@gototags.com", "verified" : { "at" : { "$date" : { "$numberLong" : "1752820322595" } }, "value" : true } }, "description" : null, "name" : "Craig Tadlock", "social" : { "google" : { "at" : { "$date" : { "$numberLong" : "1752820303521" } }, "avatar" : "https://lh3.googleusercontent.com/a/ACg8ocJdNpd0gpyg6PvxiYLsHIAStkrCeMX5cW0CXv5nDeK0m_uFg4U=s96-c", "email" : "xxx@gototags.com", "name" : "Craig Tadlock", "raw" : { "sub" : "114871314056949341862", "name" : "Craig Tadlock", "given_name" : "Craig", "family_name" : "Tadlock", "picture" : "https://lh3.googleusercontent.com/a/ACg8ocJdNpd0gpyg6PvxiYLsHIAStkrCeMX5cW0CXv5nDeK0m_uFg4U=s96-c", "email" : "xxx@gototags.com", "email_verified" : true, "hd" : "gototags.com" }, "_id" : "114871314056949341862" } }, "registered" : { "at" : { "$date" : { "$numberLong" : "1752820322595" } }, "value" : true }, "created" : { "at" : { "$date" : { "$numberLong" : "1752820322596" } } }, "updated" : { "at" : { "$date" : { "$numberLong" : "1752820322596" } } }, "_id" : "Z57fu5A2E5" } ] } []  

The attributes look fine here...

[ctadlock]

I threw Claude Code at this to see how it would do.. I think its on to something. Stepping through that code I found the following is true..

• single inserts are being wrapped in an array so being treated as bulk inserts
• root is never set to true, even for the root part of my document, so this code is never ran...

$values['_id'] = $values['id'];
unset($values['id']);

● The bug is on line 1811 of /home/craig/git/gototags/internal/cloud/cloud-3/server/src/vendor/mongodb/laravel-mongodb/src/Query/Builder.php. When aliasIdForQuery recursively processes arrays, it incorrectly assumes all nested arrays are embedded documents and passes $root = false. However, in the case of batch inserts, these arrays are actually root documents that should have $root = true.

> but im inserting one row

● You're right, you're inserting a single document. Let me look at this more carefully.

  Looking at your logs, the insert command shows a single document in the documents array. So the issue isn't about batch inserts.

  Let me trace through what happens when you save a single Account model:

  1. The Account model has id field set
  2. When saving, it eventually calls the Query Builder's insert method
  3. The insert method wraps single documents in an array: $values = [$values]; (line 745)
  4. Then calls $values = $this->aliasIdForQuery($values); (line 748)

  Now, when aliasIdForQuery is called with [['id' => 'xxx', ...]]:
  - It iterates through the outer array
  - For each element (which is the document), it checks if (is_array($value))
  - Since the document is an array, it recursively calls $this->aliasIdForQuery($value, false)
  - This recursive call has $root = false!

  So the bug is that when processing a single document insert, the code wraps it in an array, then when aliasIdForQuery processes this wrapper array, it treats the actual document as a nested array and calls itself with $root = false.

  The fix would be to distinguish between:
  1. An array that represents a batch of documents (where each element should be processed with $root = true)
  2. An array that represents a nested/embedded document (where it should be processed with $root = false)

  The current code assumes all nested arrays are embedded documents, which is incorrect for the insert operation.

● Search(pattern: "is_array.*value.*aliasIdForQuery", path: "server/src/vendor/mongodb/laravel-mongodb/src/Query/Builder.php", output_mode: "content")
  ⎿  Found 0 lines 

● Let me check how the insert method handles the values:

● Read(server/src/vendor/mongodb/laravel-mongodb/src/Query/Builder.php)
  ⎿  Read 35 lines (ctrl+r to expand)

● OK, so when inserting a single document:
  1. $values comes in as ['id' => 'xxx', 'email' => '...', ...]
  2. The code detects it's not a batch (line 744) and wraps it: $values = [['id' => 'xxx', ...]]
  3. Then calls aliasIdForQuery($values) with this wrapped array

  Now in aliasIdForQuery:

● Read(server/src/vendor/mongodb/laravel-mongodb/src/Query/Builder.php)
  ⎿  Read 20 lines (ctrl+r to expand)

● When aliasIdForQuery is called with [['id' => 'xxx', ...]]:
  1. First it checks array_key_exists('id', $values) - this is FALSE because $values is [0 => ['id' => 'xxx']], not ['id' => 'xxx']
  2. So it skips the ID renaming at the top level
  3. Then in the foreach loop at line 1809, it finds that $value (the document) is an array
  4. It recursively calls aliasIdForQuery($value, false) with $root = false
  5. In this recursive call, when rename_embedded_id_field = false, the condition (false || false) = false
  6. So the id is NOT renamed to _id!

  That's the bug! The issue is that when a single document is wrapped in an array for batch insert, the recursive call incorrectly treats it as an embedded document ($root = false) instead of a root document.

[ctadlock]

^ that cost me $16 ;)

> /cost 
  ⎿  Total cost:            $16.36
     Total duration (API):  19m 41.5s
     Total duration (wall): 23h 52m 24.7s
     Total code changes:    84 lines added, 63 lines removed
     Usage by model:
         claude-3-5-haiku:  15.6k input, 1.7k output, 0 cache read, 0 cache write
              claude-opus:  744 input, 29.6k output, 3.3m cache read, 490.7k cache write, 1 web search

[alcaeus]

Hi @ctadlock thank you so much for the in-depth research and information. I'm taking a look and will post an update once I have one.

[alcaeus]

@ctadlock I've created a PR to fix the bug in question, which was exactly where you suggested it was. I was a bit confused at first, as I was able to hit this code when calling DB::table()->insert, but not when calling $model->save. A few debugging sessions later I realised that this was because our models use $incrementing=true (inherited from the default Eloquent model). Once I added a model with $incrementing=false, $model->save() would indeed hit the code that called aliasIdForQuery wrong.

Again, thank you so much for the in-depth investigation and write-up. Feel free to give the code from the PR a try, which should then yield the result we expect: your custom id value in _id, no id field regardless of rename_embedded_id_field config.

[ctadlock]

@alcaeus That fixed it!

[alcaeus]

Thank you for confirming. I've tagged 5.4.2 containing the fix.