PHPLIB-235: Document write result classes

Author: jmikola

docs/includes/extracts-error.yaml

@@ -10,6 +10,12 @@ content: |
   <mongodb-driver-exception-runtimeexception>` for other errors at the driver
   level (e.g. connection errors).
 ---
+ref: error-badmethodcallexception-write-result
+content: |
+  :phpclass:`MongoDB\\Exception\\BadMethodCallException` if this method is
+  called and the write operation used an unacknowledged :manual:`write concern
+  </reference/write-concern>`.
+---
 ref: error-invalidargumentexception
 content: |
   :phpclass:`MongoDB\\Exception\\InvalidArgumentException` for errors related to

docs/reference.txt

@@ -12,4 +12,5 @@ Reference
    /reference/class/MongoDBDatabase
    /reference/class/MongoDBCollection
    /reference/class/MongoDBGridFSBucket
+   /reference/write-result-classes
    /reference/exception-classes

docs/reference/method/MongoDBBulkWriteResult-getDeletedCount.txt

@@ -0,0 +1,42 @@
+===========================================
+MongoDB\\BulkWriteResult::getDeletedCount()
+===========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getDeletedCount()
+
+   Return the total number of documents that were deleted by all delete
+   operations in the bulk write.
+
+   .. code-block:: php
+
+      function getDeletedCount(): integer
+
+   This method should only be called if the write was acknowledged.
+
+Return Values
+-------------
+
+The total number of documents that were deleted by all delete operations in the
+bulk write.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-badmethodcallexception-write-result.rst
+
+See Also
+--------
+
+- :php:`MongoDB\\Driver\\WriteResult::getDeletedCount()
+  <manual/en/mongodb-driver-writeresult.getdeletedcount.php>`

docs/reference/method/MongoDBBulkWriteResult-getInsertedCount.txt

@@ -0,0 +1,42 @@
+============================================
+MongoDB\\BulkWriteResult::getInsertedCount()
+============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getInsertedCount()
+
+   Return the total number of documents that were inserted by all insert
+   operations in the bulk write.
+
+   .. code-block:: php
+
+      function getInsertedCount(): integer
+
+   This method should only be called if the write was acknowledged.
+
+Return Values
+-------------
+
+The total number of documents that were inserted by all insert operations in the
+bulk write.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-badmethodcallexception-write-result.rst
+
+See Also
+--------
+
+- :php:`MongoDB\\Driver\\WriteResult::getInsertedCount()
+  <manual/en/mongodb-driver-writeresult.getinsertedcount.php>`

docs/reference/method/MongoDBBulkWriteResult-getInsertedIds.txt

@@ -0,0 +1,38 @@
+==========================================
+MongoDB\\BulkWriteResult::getInsertedIds()
+==========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getInsertedIds()
+
+   Return a map of IDs (i.e. ``_id`` field values) for documents that were
+   inserted by all insert operations in the bulk write.
+
+   .. code-block:: php
+
+      function getInsertedIds(): array
+
+   Since IDs are created by the driver, this method may be called irrespective
+   of whether the write was acknowledged.
+
+Return Values
+-------------
+
+A map of IDs (i.e. ``_id`` field values) for documents that were inserted by all
+insert operations in the bulk write.
+
+The index of each ID in the map corresponds to each document's position in the
+bulk operation. If a document had an ID prior to inserting (i.e. the driver did
+not generate an ID), this will contain its ``_id`` field value. Any
+driver-generated ID will be a :php:`MongoDB\\BSON\\ObjectID
+<class.mongodb-bson-objectid>` instance.

docs/reference/method/MongoDBBulkWriteResult-getMatchedCount.txt

@@ -0,0 +1,51 @@
+===========================================
+MongoDB\\BulkWriteResult::getMatchedCount()
+===========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getMatchedCount()
+
+   Return the total number of documents that were matched by all update and
+   replace operations in the bulk write.
+
+   .. code-block:: php
+
+      function getMatchedCount(): integer
+
+   This method should only be called if the write was acknowledged.
+
+   .. note::
+
+      If an update/replace operation results in no change to the document
+      (e.g. setting the value of a field to its current value), the matched
+      count may be greater than the value returned by
+      :phpmethod:`getModifiedCount()
+      <MongoDB\\BulkWriteResult::getModifiedCount()>`.
+
+Return Values
+-------------
+
+The total number of documents that were matched by all update and replace
+operations in the bulk write.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-badmethodcallexception-write-result.rst
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\BulkWriteResult::getModifiedCount()`
+- :php:`MongoDB\\Driver\\WriteResult::getMatchedCount()
+  <manual/en/mongodb-driver-writeresult.getmatchedcount.php>`

docs/reference/method/MongoDBBulkWriteResult-getModifiedCount.txt

@@ -0,0 +1,54 @@
+============================================
+MongoDB\\BulkWriteResult::getModifiedCount()
+============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getModifiedCount()
+
+   Return the total number of documents that were modified by all update and
+   replace operations in the bulk write.
+
+   .. code-block:: php
+
+      function getModifiedCount(): integer|null
+
+   This method should only be called if the write was acknowledged.
+
+   .. note::
+
+      If an update/replace operation results in no change to the document
+      (e.g. setting the value of a field to its current value), the modified
+      count may be less than the value returned by :phpmethod:`getMatchedCount()
+      <MongoDB\\BulkWriteResult::getMatchedCount()>`.
+
+Return Values
+-------------
+
+The total number of documents that were modified by all update and replace
+operations in the bulk write.
+
+The modified count is not available on versions of MongoDB before 2.6, which
+used the legacy wire protocol version (i.e. ``OP_UPDATE``). If this is the case,
+the modified count will be ``null``.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-badmethodcallexception-write-result.rst
+
+See Also
+--------
+
+- :phpmethod:`MongoDB\\BulkWriteResult::getMatchedCount()`
+- :php:`MongoDB\\Driver\\WriteResult::getModifiedCount()
+  <manual/en/mongodb-driver-writeresult.getmodifiedcount.php>`

docs/reference/method/MongoDBBulkWriteResult-getUpsertedCount.txt

@@ -0,0 +1,42 @@
+============================================
+MongoDB\\BulkWriteResult::getUpsertedCount()
+============================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getUpsertedCount()
+
+   Return the total number of documents that were upserted by all update and
+   replace operations in the bulk write.
+
+   .. code-block:: php
+
+      function getUpsertedCount(): integer
+
+   This method should only be called if the write was acknowledged.
+
+Return Values
+-------------
+
+The total number of documents that were upserted by all update and replace
+operations in the bulk write.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-badmethodcallexception-write-result.rst
+
+See Also
+--------
+
+- :php:`MongoDB\\Driver\\WriteResult::getUpsertedCount()
+  <manual/en/mongodb-driver-writeresult.getupsertedcount.php>`

docs/reference/method/MongoDBBulkWriteResult-getUpsertedIds.txt

@@ -0,0 +1,46 @@
+==========================================
+MongoDB\\BulkWriteResult::getUpsertedIds()
+==========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::getUpsertedIds()
+
+   Return a map of IDs (i.e. ``_id`` field values) for documents that were
+   upserted by all update and replace operations in the bulk write.
+
+   .. code-block:: php
+
+      function getUpsertedIds(): array
+
+Return Values
+-------------
+
+A map of IDs (i.e. ``_id`` field values) for documents that were upserted by all
+update and replace operations in the bulk write.
+
+The index of each ID in the map corresponds to each document's position in the
+bulk operation. If a document had an ID prior to upserting (i.e. the server did
+not generate an ID), this will contain its ``_id`` field value. Any
+server-generated ID will be a :php:`MongoDB\\BSON\\ObjectID
+<class.mongodb-bson-objectid>` instance.
+
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-badmethodcallexception-write-result.rst
+
+See Also
+--------
+
+- :php:`MongoDB\\Driver\\WriteResult::getUpsertedIds()
+  <manual/en/mongodb-driver-writeresult.getupsertedids.php>`

docs/reference/method/MongoDBBulkWriteResult-isAcknowledged.txt

@@ -0,0 +1,34 @@
+==========================================
+MongoDB\\BulkWriteResult::isAcknowledged()
+==========================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\BulkWriteResult::isAcknowledged()
+
+   Return whether the write was acknowledged.
+
+   .. code-block:: php
+
+      function isAcknowledged(): boolean
+
+Return Values
+-------------
+
+Return whether the write was acknowledged.
+
+See Also
+--------
+
+- :php:`MongoDB\\Driver\\WriteResult::isAcknowledged()
+  <manual/en/mongodb-driver-writeresult.isacknowledged.php>`
+- :manual:`Write Concern </reference/write-concern>` in the MongoDB manual