Proxy error when accessing unset fields without 'nullable: true'

[TheVenon]

Proxy error when accessing unset fields without nullable: true

Summary

After upgrading from Doctrine MongoDB ODM 1.2 to 2.10, I'm encountering a runtime error when accessing a field that is defined in the document class but is not present in some documents in the database (e.g., legacy documents created before the field existed).

The field is defined as:

#[Field(type: 'bool')]
protected $show_in_shop;

When accessing this field on a proxied document, I get the following error:

PHP Error: Undefined property: Proxies\__PM__\My\Document\ClassName\Generated123::$show_in_shop

This happens because ODM does not store the field when its value is null and nullable: true is not specified, so the field is $unset in MongoDB — as expected from the documentation:

"By default, ODM will $unset fields in MongoDB if the PHP value is null. Specify true for this option to force ODM to store a null value in the database instead of unsetting the field."

However, even though this behavior is expected, the proxy class still tries to access that property directly, which results in a error.

Expected behavior

I would expect the proxy or hydration system to handle missing (unset) fields gracefully, just like in ODM 1.2. Specifically, if a field is missing from the MongoDB document, it should default to null or a safe default — or at least not crash due to missing property on the proxy class.

Actual behavior

The proxy class throws a PHP error when the property is missing:

PHP Error: Undefined property: Proxies\__PM__\My\Document\ClassName\Generated123::$show_in_shop

Workaround

If I change the field definition to include nullable: true, the error goes away:

#[Field(type: 'bool', nullable: true)]
protected $show_in_shop;

This causes ODM to persist null into the database instead of unsetting the field. However, this seems to defeat the purpose of the default $unset behavior — and contradicts the documentation a bit, since proxies apparently still expect the property to exist.

Questions

• Is this a regression from ODM 1.x or intended behavior in 2.x?

• Should proxy classes be more tolerant to missing fields that were $unset?

• Is nullable: true now required for all optional fields to avoid proxy errors?

Environment

• PHP version: 8.4
• Doctrine MongoDB ODM version: 2.11.2
• MongoDB PHP driver: mongodb/mongodb ^2.0.0
• MongoDB server version: 6.x

[alcaeus]

I'm not sure I understand what the problem is. To make sure, I created this small example document:

#[ODM\Document]
class GH2776Document
{
    #[ODM\Id]
    public $id;

    #[ODM\Field(type: 'string')]
    protected $name;

    public function getName(): void
    {
        $foo = $this->name;
    }
}

Note that I made the $name property protected to match your setup. I then insert a sample document without a name set, confirming that there indeed isn't a name set:

{
    _id: ObjectId('684178b6858f13380b02f5c3')
}

After clearing the document manager, I fetched a proxy object for the document just created:

$proxy = $this->dm->getReference(GH2776Document::class, $document);

I could not reproduce the error when accessing the protected method from within the document. To make sure, I tested this with both ProxyManager and LazyGhostObject proxies, and it worked both times. It also worked just fine with public properties.

If you are able to, please create a functional test for us to investigate this with. You can find examples for such tests in the Functional\Ticket test namespace. Note that these tests need a database to run.

[TheVenon]

Root Cause Identified (Proxy Reference + Hydration Order)

After extensive debugging, I found the actual cause of the issue:

The warning:

PHP Error: Undefined property: Proxies_PM_\My\Document\ClassName\Generated123::$show_in_shop

is triggered not because a field is missing in the PHP class — I have many other missing fields across documents and they don’t cause any issues.

The real issue lies in the hydration order of referenced documents.

My document User contains a reference to Domain via the active_domain field:

#[ReferenceOne(storeAs: 'id', targetDocument: Domain::class)]
protected $active_domain;

If I retrieve the User before the referenced Domain document has been loaded from MongoDB, Doctrine ODM creates a proxy object for active_domain. When this proxy is later accessed (e.g., during serialization or any method access), and if the corresponding MongoDB document contains fields that are not defined in the PHP class (like show_in_shop in my case), Doctrine tries to hydrate them into the proxy — but fails, because the property does not exist.

Fix / Workaround

The key workaround is to load the referenced document first, before loading the referencing one (User). This way, the reference will point to a fully-hydrated object, not a proxy.

This causes the warning:

$user = $userRepository->find($id); // references Domain (as proxy)
$domain = $domainRepository->findByHostname($host); // too late

This works fine:

$domain = $domainRepository->findByHostname($host); // fully hydrated
$user = $userRepository->find($id); // reference now resolves to real object