Command Monitoring Deserialization Issue with Nested Documents

[BesedinSasha]

When using MongoDB command monitoring (CommandSubscriber) with nested documents that implement Persistable interface, calling CommandStartedEvent::getCommand() after document insertion causes a fatal error due to deserialization issues.

Uncaught Error: Cannot use object of type stdClass as array

The issue occurs when:

1. A document with nested objects is inserted into MongoDB
2. The command monitoring subscriber attempts to access the command via CommandStartedEvent::getCommand()
3. The MongoDB driver tries to deserialize the command data, but fails because nested documents are stored as stdClass objects instead of arrays

Environment

• PHP 8.3.23
• Library 2.1.0
• Server 7.0.12 (standalone docker image, linux/arm64 platform)

mongodb
libbson bundled version => 1.30.5
libmongoc bundled version => 1.30.5
libmongoc SSL => enabled
libmongoc SSL library => OpenSSL
libmongoc crypto => enabled
libmongoc crypto library => libcrypto
libmongoc crypto system profile => disabled
libmongoc SASL => enabled
libmongoc SRV => enabled
libmongoc compression => enabled
libmongoc compression snappy => disabled
libmongoc compression zlib => enabled
libmongoc compression zstd => disabled
libmongocrypt bundled version => 1.12.0
libmongocrypt crypto => enabled
libmongocrypt crypto library => libcrypto
mongodb.debug => no value => no value

Installed modules

[PHP Modules]
amqp
apcu
bz2
Core
ctype
curl
date
dom
exif
fileinfo
filter
gd
gettext
hash
iconv
intl
json
libxml
mbstring
memcached
mongodb
mysqli
mysqlnd
openssl
opentelemetry
pcntl
pcre
PDO
pdo_mysql
pdo_sqlite
Phar
posix
random
rdkafka
readline
redis
Reflection
session
SimpleXML
sockets
sodium
SPL
sqlite3
standard
tokenizer
xdebug
xml
xmlreader
xmlwriter
zip
zlib

[Zend Modules]
Xdebug

Test Script

<?php

declare(strict_types=1);

use MongoDB\Driver\Monitoring\CommandFailedEvent;
use MongoDB\Driver\Monitoring\CommandStartedEvent;
use MongoDB\Driver\Monitoring\CommandSubscriber;
use MongoDB\Driver\Monitoring\CommandSucceededEvent;
use MongoDB\BSON\Persistable;
use MongoDB\Client;
use MongoDB\BSON\Unserializable;

require_once __DIR__ . '/vendor/autoload.php';

class NestedDocument
{
    public function __construct(public string $name)
    {
    }
}

class Document implements Persistable
{
    public function __construct(
        public int $id,
        public NestedDocument $nested,
    ) {
    }

    public function bsonSerialize(): array
    {
        return [
            'id' => $this->id,
            'nested' => ['name' => $this->nested->name],
        ];
    }

    public function bsonUnserialize(array $data): void
    {
        $this->id = $data['id'];
        $this->nested = new NestedDocument($data['nested']['name']);
    }
}

class CommandLogger implements CommandSubscriber
{
    private array $commands;

    public function __construct()
    {
        $this->commands = [];
    }

    public function commandStarted(CommandStartedEvent $event): void
    {
        $this->commands[$event->getRequestId()] = [
            'dbname' => $event->getDatabaseName(),
            'commandName' => $event->getCommandName(),
            'command' => $event->getCommand(), // This line causes the error
        ];
    }

    public function commandSucceeded(CommandSucceededEvent $event): void
    {
        unset($this->commands[$event->getRequestId()]);
    }

    public function commandFailed(CommandFailedEvent $event): void
    {
        unset($this->commands[$event->getRequestId()]);
    }
}

$client = new Client('mongodb://localhost:27017');
$client->addSubscriber(new CommandLogger());

$collection = $client->getDatabase('test')->getCollection('test');

// This works fine - no deserialization issues with queries
var_dump($collection->findOne([])); 

// This causes the error when CommandLogger tries to access getCommand()
var_dump($collection->insertOne(new Document(1, new NestedDocument('test name')))->getInsertedId());

Expected Behavior

The CommandStartedEvent::getCommand() method should return the command data without causing deserialization errors, even when the command involves documents with nested objects (Do not use bsonUnserialize() ?).

Actual Behavior

A fatal error occurs: Cannot use object of type stdClass as array when trying to access the command data for insert operations involving nested documents.

[alcaeus]

Hi @BesedinSasha, thank you for the report. The issue here stems from a mixture of using functionality that leverages type maps with functionality that doesn't, paired with logic that shouldn't leverage a type map but does. Since that sentence probably isn't too helpful, let me explain:

Running the above code produces the exact result you suggested it would. Interestingly enough, if we try the same without a command subscriber, successfully insert a document, then find that document, we get no error whatsoever. I know that because when I first tried it in the extension (as all of the deserialisation logic is in the extension), I got the error in the command subscriber and when reading the document from the database, which is what I expected.

By default, the PHP library applies a default type map with the following values:

private const DEFAULT_TYPE_MAP = [
    'array' => BSONArray::class,
    'document' => BSONDocument::class,
    'root' => BSONDocument::class,
];

In your use case, the root key is irrelevant because it will be overridden by the __pclass property injected due to the document class implementing Persistable. When calling bsonUnserialize, the root document is converted to an array (equivalent to a type map of ['root' => 'array'], but when deserialising nested data (which always happens before bsonUnserialize is called), the type map is applied, causing the embedded document to be converted to a BSONDocument class. This works fine whenever you're reading from code that takes a type map, but command subscribers don't. Instead, deserialisation for that case only takes into account the __pclass property, meaning that the embedded document is passed as an stdClass instance.

To work around this problem above, I would recommend implementing Persistable for NestedDocument - that makes the entire logic independent of the type map:

class NestedDocument implements Persistable
{
    public function __construct(public string $name)
    {
    }

    public function bsonSerialize(): array
    {
        return ['name' => $this->name];
    }

    public function bsonUnserialize(array $data): void
    {
        $this->name = $data['name'];
    }
}

This also requires you to slightly update the Persistable implementation for Document:

public function bsonSerialize(): array
{
    return [
        '_id' => $this->id,
        'nested' => $this->nested,
    ];
}

public function bsonUnserialize(array $data): void
{
    $this->id = $data['_id'];
    $this->nested = $data['nested'];
}

The upside of this approach is that all of the encoding/decoding logic is now contained in the individual class, instead of your Document class containing the deserialisation logic for all nested documents contained therein (and possibly elsewhere).

If you don't want to implement Persistable in your embedded document classes, you should assume that objects are objects (even though the signature of bsonUnserialize suggests otherwise) and always access properties using the object operator, not array offsets. Since the default PHPLIB type map returns a BSONDocument instance which is just a fancy wrapper class for ArrayObject, $data['nested']->name will work just fine, and it has the benefit of working in code that does not apply a type map.

---

The behaviour you encountered does present a bit of an issue though. There are multiple ways this could be fixed, both of which entail a BC break:

• getCommand() doesn't apply any type map, nor does it respect ODM properties
• bsonUnserialize should no longer respect the type map set by the user

I'm not sure what the best course of action is here, and we'll discuss this internally. I've created PHPC-2603 to track this internally, so feel free to follow that issue for updates. As indicated in the ticket, there may be no possible fix except to improve documentation. I believe that it's best to only rely on one mechanism for deserialisation; either Persistable implementations or type maps.