How can I hydrate a document class used with setTypeMap ?

[AsyncWizard]

Hi,

I'm working on a lightweight "Entity" system that simplifies access to data between, for example, two collections.
In the code below, I would like my User class to allow me to retrieve informations from the user's group.

First, data in DB:

// One document in "group" collection:
{
  _id: 1234,
  name: 'My group'
}

// One document in "user" collection:
{
  _id: 1230,
  firstName: 'Joe',
  lastName: 'Robert',
  group: 1234
}

Now, PHP (pseudo)code:

use MongoDB\Model\BSONDocument;

class User extends BSONDocument
{
    /**
     * @return Database
     */
    protected function getDB(){
        /**
         * NEED TO IMPLEMENT THIS
         */
    }

    public function getGroup(){
        $groupId = $this[ 'group' ];
        return $this
            ->getDB()
            ->selectCollection('group')
            ->findOne([
                '_id' => $groupId
            ])
        ;
    }
}

// Usage example:
$usersCursor = $collection->find();

$usersCursor->setTypeMap([
    'root' => User::class,
    'document' => 'array',
    'array' => 'array',
]);

foreach($usersCursor as $user){
    $groupInformations = $user->getGroup();
    $username = $user['firstName'];
    
    // ...
}

In this example I need the Database, but in reality it relates to any data that can be used in the document.

For now, I investigated 2 methods:

1 - Static references

Something like:

class User extends BSONDocument
{
    private static $db;

    public static function setDB(Database $db){
        self::$db = $db;
    }

    /**
     * @return Database
     */
    protected function getDB(){
        return self::$db;
    }

    //...
}

I find that this implementation is not clean.
And above all, in this example, if I request users on two different databases, I will have conflicts, it seems chaotic.

2 - Extends / wrap EVERYTHING

Extending MongoDB\Collection, override all methods that return BSONDocument, intercept the return of a document to hydrate it.
When a method (for example ::find) returns a \MongoDB\Driver\Cursor, it will have to be wrapped in a custom cursor, because:

final class Cursor implements \Traversable

This could be a problem if a third-party library requires a \MongoDB\Driver\Cursor and nothing else.

Discussion

Why ::setTypeMap could not use a callback or a factory class that implements BSONDocumentFactory for example ?
The returned result would be just completed with a call to bsonUnserialize.

Maybe I forgot something?
In my example I need a Database, but, again, this might be needed with any kind of data.

For now I'm thinking about the implementation of the second solution, it's a big deal!
Otherwise, if someone has another solution or a library that provides that, I would be grateful.

Thank you for reading so far! :)

[jmikola]

First off, thanks very much for the detailed issue and sharing your feedback!

When a method (for example ::find) returns a \MongoDB\Driver\Cursor, it will have to be wrapped in a custom cursor, because:

final class Cursor implements \Traversable

This could be a problem if a third-party library requires a \MongoDB\Driver\Cursor and nothing else.

As a rule of thumb, we introduced most classes in the mongodb extension as final to prohibit extension, which had historically been a problem for the legacy mongo extension. The limitation of MongoDB\Driver\Cursor being final has been noted and we aimed to address that in PHPC-1123 with the introduction of an interface. That fix should be available in the forthcoming 1.6.0 release (it's already available in the 1.6.0alpha1 release on PECL).

Why ::setTypeMap could not use a callback or a factory class that implements BSONDocumentFactory for example?

Our initial API for BSON conversion was modeled after PHP's existing Serializable and JsonSerializable interfaces, which are admittedly primitive.

The factory idea you're suggesting actually overlaps with some ideas we have for BSON API improvements in the extension (see: PHPC-999, which would allow the extension to delegate to a callable to handle BSON conversion. I've cross-referenced this issue in the ticket so we can be sure to consider your use suggestion when we're able to revisit the ticket.

We've hesitated to implement this sooner because of the possible performance implications of invoking a callable to resolve BSON conversion for each element within a BSON document. Any proposed design will certainly require prototyping and benchmarking before we commit to an API.

Otherwise, if someone has another solution or a library that provides that, I would be grateful.

The functionality you're describing seems related to what Doctrine ODM provides. While the upcoming 2.0 version uses the mongodb extension natively (1.0 was based around the legacy mongo extension), it uses its own services for hydrating PHP objects (from the database) and persisting entities (to the database). The hydrating service is able to inject other services within the entity as needed, which allows it to implement the reference-resolution functionality you're describing. Collections of document references are transparently wrapped with PersistentCollection objects at hydration time, which can then issue a query at access time to resolve those references lazily.

Longterm, I believe Doctrine ODM plans to offload some of the responsibility of its hydrating service to the mongodb extension, so that will also serve as a good use case (and test bed) for any forthcoming BSON API improvements in the extension.

[alcaeus]

I've cross-referenced this issue with PHPC-999, which is our internal ticket to track these ODM improvements. Since there is no work to be done here at this time, I'm closing this issue.

Feel free to subscribe to the linked issue for updates.