exception-classes.txt

=================
Exception Classes
=================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

MongoDB\\Exception\\BadMethodCallException
------------------------------------------

.. phpclass:: MongoDB\\Exception\\BadMethodCallException

   This exception is thrown when an unsupported method is invoked on an object.

   For example, using an unacknowledged write concern with
   :phpmethod:`MongoDB\\Collection::insertMany()` will return a
   :phpclass:`MongoDB\\InsertManyResult` object. It is a logical error to call
   :phpmethod:`MongoDB\\InsertManyResult::getInsertedCount()`, since the number
   of inserted documents can only be determined from the response of an
   acknowledged write operation.

   This class extends PHP's :php:`BadMethodCallException
   <badmethodcallexception>` class and implements the library's
   :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.

----

MongoDB\\Exception\\InvalidArgumentException
--------------------------------------------

.. phpclass:: MongoDB\\Exception\\InvalidArgumentException

   Thrown for errors related to the parsing of parameters or options within the
   library.

   This class extends the driver's :php:`InvalidArgumentException
   <mongodb-driver-exception-invalidargumentexception>` class and implements the
   library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.

----

MongoDB\\Exception\\UnexpectedValueException
--------------------------------------------

.. phpclass:: MongoDB\\Exception\\UnexpectedValueException

   This exception is thrown when a command response from the server is
   malformed or not what the library expected. This exception means that an
   assertion in some operation, which abstracts a database command, has failed.
   It may indicate a corrupted BSON response or bug in the server, driver, or
   library.

   This class extends the driver's :php:`UnexpectedValueException
   <mongodb-driver-exception-unexpectedvalueexception>` class and implements the
   library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.

----

MongoDB\\Exception\\UnsupportedException
----------------------------------------

.. phpclass:: MongoDB\\Exception\\UnsupportedException

   This exception is thrown if an option is used and not supported by the
   selected server. It is used sparingly in cases where silently ignoring the
   unsupported option might otherwise lead to unexpected behavior.

   For example, the ``collation`` option for
   :phpmethod:`MongoDB\\Collection::deleteOne()` is only supported by
   MongoDB 3.4+. Since collation determines how a document is matched, silently
   ignoring the option for an older server version could result in an
   unintended document being deleted.

   This class extends the library's :phpclass:`RuntimeException
   <MongoDB\\Exception\\RuntimeException>` class.

   .. note::

      Unlike :phpclass:`InvalidArgumentException
      <MongoDB\\Exception\\InvalidArgumentException>`, which may be thrown when
      an operation's parameters and options are parsed during construction, the
      selected server is not known until an operation is executed.

----

MongoDB\\GridFS\\Exception\\CorruptFileException
------------------------------------------------

.. phpclass:: MongoDB\\GridFS\\Exception\\CorruptFileException

   This exception is thrown if a GridFS file's metadata or chunk documents
   contain unexpected or invalid data.

   When selecting a GridFS file, this may be thrown if a metadata field has an
   incorrect type or its value is out of range (e.g. negative ``length``). When
   reading a GridFS file, this may be thrown if a chunk's index is out of
   sequence or its binary data's length out of range.

   This class extends the library's :phpclass:`RuntimeException
   <MongoDB\\Exception\\RuntimeException>` class.

----

MongoDB\\GridFS\\Exception\\FileNotFoundException
-------------------------------------------------

.. phpclass:: MongoDB\\GridFS\\Exception\\FileNotFoundException

   This exception is thrown if no GridFS file was found for the selection
   criteria (e.g. ``id``, ``filename``).

   This class extends the library's :phpclass:`RuntimeException
   <MongoDB\\Exception\\RuntimeException>` class.

----

MongoDB\\Exception\\Exception
-----------------------------

.. phpclass:: MongoDB\\Exception\\Exception

   This interface extends the driver's :php:`Exception
   <mongodb-driver-exception-exception>` interface and is implemented by all
   exception classes within the library.

----

MongoDB\\Exception\\RuntimeException
------------------------------------

.. phpclass:: MongoDB\\Exception\\RuntimeException

   This class extends the driver's :php:`RuntimeException
   <mongodb-driver-exception-runtimeexception>` class, which in turn extends
   PHP's :php:`RuntimeException <runtimeexception>` class.