save() method missing from Collection about mongo-php-library

[csga5000]

I agree that the save method was useful. It feels out of character for mongo to require that you explicitly define whether you wish to update or insert and that you cannot do both at once. And your guys' decision to change costs me lots of dev time on a project that is not really being developed anymore.

[jmikola]

The library implements our CRUD specification, which doesn't include the save() method found in our older APIs. save() is more sensible for interactive environments such as the shell (AFAIK there are no plans to remove it), but the target audience for the spec is our language drivers, where we felt users were better off explicitly calling insert or upsert. Much like the decision to split update() into updateOne(), updateMany(), and upsertOne(), this leads to more self-documenting code and less overloaded methods.

[armetiz]

That's too bad. The save() method is really useful.

Regards;

[manuelcanga]

Has someone thought backward compatibility?
Not only with 'save' method. Also with 'sort', 'count', 'limit', ... methods in cursors ?.

[Gorbov]

Same.
Plus «MongoDB\Database::getDBRef()» and «\MongoDate()».

[jmikola]

Has someone thought backward compatibility?

@alcaeus (one of the Doctrine developers) is actually working on such a project: https://github.com/alcaeus/mongo-php-adapter

Not only with 'save' method. Also with 'sort', 'count', 'limit', ... methods in cursors ?

count(), sort(), and limit() cursor methods are an entirely different can of worms. See mongodb/mongo-php-driver#195 (comment) for some background on why the new driver/library no longer has these. In short, cursors in the new driver are no longer dual-nature (pre- and post-executed states); rather, they always represent an execute query/command. This means we had to remove the query-builder-like methods from them, along with count(), which actually invokes a count command (making it possible to return a different count than the number of results you might find by iterating through the Cursor object).

MongoDB\Database::getDBRef() and MongoDate

UTCDateTime is MongoDate for the new driver (we're using a more descriptive name for it).

There are plans to add some utility functions to work with DBRef (PHPLIB-24). I hope to get those into 1.1.0 along with GridFS.

[Gorbov]

Collection.php add:

public function save(&$data, $options)
{
    $result = $this->insertOne($data, $options);
    $data['_id'] = $result->getInsertedId();

    return $result;
}

public function update($query, $data, $options)
{
    return $this->updateOne($query, $data, $options);
}

Database.php add:

public function getDBRef($ref)
{
    return $this->selectCollection($ref->{'$ref'})->findOne(array('_id' => $ref->{'$id'}));
}

[alcaeus]

Note that the save method in the example above doesn't do what it did in the legacy driver. When an _id was present it sent an upsert to the database which is missing from your method.

Similar for the update method, this completely disregards the fact that update in the legacy driver was able to update multiple documents (using the multi option). With the code you provided one might as well just replace update with updateOne throughout the project and achieve the same effect.

[jmikola]

@Gorbov: save(&$data, $options) is not sufficient for the method prototype, as the legacy driver never took the document argument (i.e. $data) by reference, despite the fact that it would modify the zval in memory to inject the _id field if necessary. Denoting a by-reference parameter would disallow the use of literals (e.g. save(['x' => 1])).

A more accurate definition of save() can be taken from the MongoDB JavaScript shell (I've removed some error-checking to keep the example consise):

function ( obj , opts ){
    if ( typeof( obj._id ) == "undefined" ){
        obj._id = new ObjectId();
        return this.insert( obj , opts );
    }
    else {
        return this.update( { _id : obj._id } , obj , Object.merge({ upsert:true }, opts));
    }
}

If the document doesn't have an _id field, we set one and do insertOne(). If the document does have an _id, we create query criteria from it and use the entire document in a replaceOne() with the upsert option. This is a replace operation instead of update, as we're using the full document as our update object and not atomic modifiers.

From an API standpoint, this is tricky because the new driver/library return very specific WriteResult classes depending on the type of operation performed (excluding BulkWriteResult). But beyond that, in what scenario are you writing code that wouldn't already know whether a document had an _id field so that you could explicitly call insertOne() or replaceOne() (and appropriately handle the result)?