zval_to_bson() currently removes the PHONGO_BSON_ADD_ID from its flags if it finds an _id field when preparing the BSON document. As such, the following code will never return a pre-existing ID from the document:

if (flags & PHONGO_BSON_ADD_ID) {
	bson_oid_t oid;

	bson_oid_init(&oid, NULL);
	bson_append_oid(bson, "_id", strlen("_id"), &oid);
	mongoc_log(MONGOC_LOG_LEVEL_TRACE, MONGOC_LOG_DOMAIN, "Added new _id");
	if (flags & PHONGO_BSON_RETURN_ID) {
		if (bson_out) {
			*bson_out = bson_new();
			bson_append_oid(*bson_out, "_id", strlen("_id"), &oid);
		}
	}
}

In PHPLIB, the insert result objects always want to provide the inserted document's identifier. This means we have work-arounds to access the document's _id array index or class property if BulkWrite::insert() returns null.

That is actually problematic if the user is inserting a Serializable object, which may not have an _id property, and it would be inefficient to invoke bsonSerialize() from userland (after zval_to_bson() has already done so) just to access this value.

I propose we change zval_to_bson() to always return the ID if requested, irrespective of generation.