Context

Automatic encryption (Queryable Encryption) relies on a server-side registered encryptedFields document to encipher mapped fields at write time. When a collection is mapped in the driver encryptedFieldsMap but is not created as an encrypted collection, writes silently store the mapped fields in plaintext. This was originally documented in DRIVERS-3647.

A previous draft of the laravel-mongodb Queryable Encryption work implemented a fail-fast guard on writes to such collections. The guard was removed from the PR because it added a server round trip to every write and cached collection state for the lifetime of the connection. This ticket tracks reintroducing the guard as a first-class, opt-in feature.

https://github.com/mongodb/laravel-mongodb/commit/a7aef8f8e2a0a14e3f63dd494a6656339702fd0f 

Goal

Offer an opt-in way to fail fast when a write targets a collection mapped for automatic encryption that is not created as an encrypted collection, so plaintext is never stored silently.

Design constraints

• Opt-in, so it does not add a round trip or break existing behavior by default.
• The collection encryption state must be refreshed, not cached for the connection lifetime, so collection creation and recreation stay correct.
• Applies to the mapped write paths: insert, insertGetId, upsert and update.
• The check must be skipped for unmapped collections and collections where automatic encryption is disabled.

Follow-up

Link the design to DRIVERS-3647 and to the PHPLARA Queryable Encryption epic.