Skip to content

Revise Collection API section in upgrade guide #686

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 7, 2019
Merged

Revise Collection API section in upgrade guide #686

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed docs/images/save-flowchart.png
View file
Open in desktop
Binary file not shown.
135 changes: 63 additions & 72 deletions docs/upgrade.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Upgrade Guide
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:depth: 2
:class: singlecol

Overview
Expand Down Expand Up @@ -119,14 +119,23 @@ new specifications, the new class provides the same functionality as the legacy
driver's :php:`MongoCollection <mongocollection>` class with some notable
exceptions.

Old and New Methods
~~~~~~~~~~~~~~~~~~~
A guiding principle in designing the new APIs was that explicit method names are
preferable to overloaded terms found in the old API. For instance,
:php:`MongoCollection::save() <mongocollection.save>` and
:php:`MongoCollection::findAndModify() <mongocollection.findandmodify>`
have different modes of operation, depending on their arguments. Methods were
also split to distinguish between :manual:`updating specific fields
</tutorial/modify-documents>` and :manual:`full-document replacement
</tutorial/modify-documents/#replace-the-document>`.

The following table lists all legacy methods alongside the
equivalent method(s) in the new driver.

.. list-table::
:header-rows: 1

* - :php:`MongoCollection <mongocollection>`
- :phpclass:`MongoDB\\Collection`
* - :php:`MongoCollection <mongocollection>` method
- :phpclass:`MongoDB\\Collection` method(s)

* - :php:`MongoCollection::aggregate() <mongocollection.aggregate>`
- :phpmethod:`MongoDB\\Collection::aggregate()`
Expand All @@ -141,7 +150,7 @@ Old and New Methods
- :phpmethod:`MongoDB\\Collection::count()`

* - :php:`MongoCollection::createDBRef() <mongocollection.createdbref>`
- Not yet implemented. See :issue:`PHPLIB-24`.
- Not yet implemented. [3]_

* - :php:`MongoCollection::createIndex() <mongocollection.createindex>`
- :phpmethod:`MongoDB\\Collection::createIndex()`
Expand Down Expand Up @@ -173,7 +182,7 @@ Old and New Methods
- :phpmethod:`MongoDB\\Collection::findOne()`

* - :php:`MongoCollection::getDBRef() <mongocollection.getdbref>`
- Not implemented. See :issue:`PHPLIB-24`.
- Not implemented. [3]_

* - :php:`MongoCollection::getIndexInfo() <mongocollection.getindexinfo>`
- :phpmethod:`MongoDB\\Collection::listIndexes()`
Expand All @@ -191,7 +200,8 @@ Old and New Methods
- Not implemented.

* - :php:`MongoCollection::group() <mongocollection.group>`
- Not implemented. Use :phpmethod:`MongoDB\\Database::command()`.
- Not implemented. Use :phpmethod:`MongoDB\\Database::command()`. See
`Group Command Helper`_ for an example.

* - :php:`MongoCollection::insert() <mongocollection.insert>`
- :phpmethod:`MongoDB\\Collection::insertOne()`
Expand All @@ -209,13 +219,13 @@ Old and New Methods
option.

* - :php:`MongoCollection::setReadPreference() <mongocollection.setreadpreference>`
- Not implemented. Use :phpmethod:`MongoDB\\Collection::withOptions()`
- Not implemented. Use :phpmethod:`MongoDB\\Collection::withOptions()`.

* - :php:`MongoCollection::setSlaveOkay() <mongocollection.getslaveokay>`
- Not implemented.

* - :php:`MongoCollection::setWriteConcern() <mongocollection.setwriteconcern>`
- Not implemented. Use :phpmethod:`MongoDB\\Collection::withOptions()`
- Not implemented. Use :phpmethod:`MongoDB\\Collection::withOptions()`.

* - :php:`MongoCollection::update() <mongocollection.update>`
- :phpmethod:`MongoDB\\Collection::replaceOne()`,
Expand All @@ -225,67 +235,6 @@ Old and New Methods
* - :php:`MongoCollection::validate() <mongocollection.validate>`
- Not implemented.

A guiding principle in designing the new APIs was that explicit method names are
preferable to overloaded terms found in the old API. For instance,
:php:`MongoCollection::save() <mongocollection.save>` and
:php:`MongoCollection::findAndModify() <mongocollection.findandmodify>`
have different modes of operation, depending on their arguments. Methods were
also split to distinguish between :manual:`updating specific fields
</tutorial/modify-documents>` and :manual:`full-document replacement
</tutorial/modify-documents/#replace-the-document>`.

Group Command Helper
--------------------

:phpclass:`MongoDB\\Collection` does have a helper method for the
:manual:`group </reference/command/group>` command; The following example
demonstrates how to execute a group command using the
:phpmethod:`MongoDB\\Database::command()` method:

.. code-block:: php

<?php

$database = (new MongoDB\Client)->selectDatabase('db_name');
$cursor = $database->command([
'group' => [
'ns' => 'collection_name',
'key' => ['field_name' => 1],
'initial' => ['total' => 0],
'$reduce' => new MongoDB\BSON\Javascript('...'),
],
]);

$resultDocument = $cursor->toArray()[0];

DBRef Helpers
-------------

:phpclass:`MongoDB\\Collection` does not yet have helper methods for working
with :manual:`DBRef </reference/database-references>` objects; however, that is
planned in :issue:`PHPLIB-24`.

MongoCollection::save() Removed
-------------------------------

:php:`MongoCollection::save() <mongocollection.save>`, which was syntactic sugar
for an insert or upsert operation, has been removed in favor of explicitly using
:phpmethod:`MongoDB\\Collection::insertOne` or
:phpmethod:`MongoDB\\Collection::replaceOne` (with the ``upsert`` option).

.. .. figure:: /images/save-flowchart.png
.. :alt: save() flowchart

While the ``save`` method does have its uses for interactive environments, such
as the mongo shell, it was intentionally excluded from the `CRUD specification
<https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst>`_
for language drivers. Generally, application code should know if the document
has an identifier and be able to explicitly insert or replace the document and
handle the returned :phpclass:`MongoDB\\InsertOneResult` or
:phpclass:`MongoDB\\UpdateResult`, respectively. This also helps avoid
inadvertent and potentially dangerous :manual:`full-document replacements
</tutorial/modify-documents>`.

Accessing IDs of Inserted Documents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -310,10 +259,52 @@ following methods on the write result objects:
:phpmethod:`MongoDB\\Collection::bulkWrite()`

Bulk Write Operations
---------------------
~~~~~~~~~~~~~~~~~~~~~

The legacy driver's :php:`MongoWriteBatch <class.mongowritebatch>` classes have
been replaced with a general-purpose
:phpmethod:`MongoDB\\Collection::bulkWrite()` method. Whereas the legacy driver
only allowed bulk operations of the same type, the new method allows operations
to be mixed (e.g. inserts, updates, and deletes).

MongoCollection::save() Removed
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:php:`MongoCollection::save() <mongocollection.save>`, which was syntactic sugar
for an insert or upsert operation, has been removed in favor of explicitly using
:phpmethod:`MongoDB\\Collection::insertOne` or
:phpmethod:`MongoDB\\Collection::replaceOne` (with the ``upsert`` option).

While the ``save`` method does have its uses for interactive environments, such
as the ``mongo`` shell, it was intentionally excluded from the
`CRUD specification <https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst>`_
for language drivers. Generally, application code should know if the document
has an identifier and be able to explicitly insert or replace the document and
handle the returned :phpclass:`MongoDB\\InsertOneResult` or
:phpclass:`MongoDB\\UpdateResult`, respectively. This also helps avoid
inadvertent and potentially dangerous :manual:`full-document replacements
</tutorial/modify-documents>`.

Group Command Helper
~~~~~~~~~~~~~~~~~~~~

:phpclass:`MongoDB\\Collection` does have a helper method for the
:manual:`group </reference/command/group>` command. The following example
demonstrates how to execute a group command using the
:phpmethod:`MongoDB\\Database::command()` method:

.. code-block:: php

<?php

$database = (new MongoDB\Client)->selectDatabase('db_name');
$cursor = $database->command([
'group' => [
'ns' => 'collection_name',
'key' => ['field_name' => 1],
'initial' => ['total' => 0],
'$reduce' => new MongoDB\BSON\Javascript('...'),
],
]);

$resultDocument = $cursor->toArray()[0];