PHPLIB-221: Document GridFS exceptions

docs/includes/extracts-error.yaml

@@ -31,4 +31,14 @@ content: |
   :phpclass:`MongoDB\\Exception\\UnsupportedException` if options are used and
   not supported by the selected server (e.g. ``collation``, ``readConcern``,
   ``writeConcern``).
+---
+ref: error-gridfs-filenotfoundexception
+content: |
+  :phpclass:`MongoDB\\GridFS\\Exception\\FileNotFoundException` if no file was
+  found for the selection criteria.
+---
+ref: error-gridfs-corruptfileexception
+content: |
+  :phpclass:`MongoDB\\GridFS\\Exception\\CorruptFileException` if the file's
+  metadata or chunk documents contain unexpected or invalid data.
 ...

docs/reference/exception-classes.txt

@@ -89,6 +89,37 @@ MongoDB\\Exception\\UnsupportedException
 
 ----
 
+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
 -----------------------------
 

docs/reference/method/MongoDBGridFSBucket-delete.txt

@@ -25,6 +25,12 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBGridFSBucket-method-delete-param.rst
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 Behavior
 --------
 

docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt

@@ -28,6 +28,13 @@ Definition
 
 .. todo: add examples
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 See Also
 --------
 

docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt

@@ -32,6 +32,13 @@ Definition
 
 .. todo: add examples
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 See Also
 --------
 

docs/reference/method/MongoDBGridFSBucket-drop.txt

@@ -21,4 +21,9 @@ Definition
 
       function drop(): void
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples

docs/reference/method/MongoDBGridFSBucket-find.txt

@@ -34,6 +34,13 @@ Return Values
 
 A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` object.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-findOne.txt

@@ -37,6 +37,13 @@ An array or object for the :term:`first document <natural order>` that matched
 the query, or ``null`` if no document matched the query. The return type will
 depend on the ``typeMap`` option.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-unsupportedexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt

@@ -31,6 +31,12 @@ Return Values
 The metadata document associated with the GridFS stream. The return type will
 depend on the bucket's ``typeMap`` option.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt

@@ -31,6 +31,13 @@ Return Values
 The ``_id`` field of the metadata document associated with the GridFS stream.
 The return type will depend on the bucket's ``typeMap`` option.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-corruptfileexception.rst
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt

@@ -30,6 +30,12 @@ Return Values
 
 A readable stream resource.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt

@@ -34,6 +34,12 @@ Return Values
 
 A readable stream resource.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket-rename.txt

@@ -25,4 +25,10 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBGridFSBucket-method-rename-param.rst
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples

docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt

@@ -37,6 +37,12 @@ GridFS file. If the ``_id`` option is not specified, a new
 :php:`MongoDB\\BSON\\ObjectID <class.mongodb-bson-objectid>` object will be used
 by default.
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+.. include:: /includes/extracts/error-driver-runtimeexception.rst
+
 .. todo: add examples
 
 See Also

docs/reference/method/MongoDBGridFSBucket__construct.txt

@@ -29,6 +29,11 @@ Definition
 
    .. include:: /includes/apiargs/MongoDBGridFSBucket-method-construct-option.rst
 
+Errors/Exceptions
+-----------------
+
+.. include:: /includes/extracts/error-invalidargumentexception.rst
+
 Behavior
 --------
 

src/GridFS/Bucket.php

@@ -7,7 +7,9 @@ use MongoDB\Driver\Manager;
 use MongoDB\Driver\ReadConcern;
 use MongoDB\Driver\ReadPreference;
 use MongoDB\Driver\WriteConcern;
+use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
 use MongoDB\Exception\InvalidArgumentException;
+use MongoDB\Exception\UnexpectedValueException;
 use MongoDB\GridFS\Exception\CorruptFileException;
 use MongoDB\GridFS\Exception\FileNotFoundException;
 use MongoDB\Operation\Find;
@@ -62,7 +64,7 @@ class Bucket
      * @param Manager $manager      Manager instance from the driver
      * @param string  $databaseName Database name
      * @param array   $options      Bucket options
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException for parameter/option parsing errors
      */
     public function __construct(Manager $manager, $databaseName, array $options = [])
     {
@@ -137,7 +139,8 @@ class Bucket
      * attempt to delete orphaned chunks.
      *
      * @param mixed $id File ID
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if no file could be selected
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function delete($id)
     {
@@ -154,8 +157,9 @@ class Bucket
      *
      * @param mixed    $id          File ID
      * @param resource $destination Writable Stream
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if no file could be selected
      * @throws InvalidArgumentException if $destination is not a stream
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function downloadToStream($id, $destination)
     {
@@ -188,8 +192,9 @@ class Bucket
      * @param string   $filename    Filename
      * @param resource $destination Writable Stream
      * @param array    $options     Download options
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if no file could be selected
      * @throws InvalidArgumentException if $destination is not a stream
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function downloadToStreamByName($filename, $destination, array $options = [])
     {
@@ -203,6 +208,8 @@ class Bucket
     /**
      * Drops the files and chunks collections associated with this GridFS
      * bucket.
+     *
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function drop()
     {
@@ -217,6 +224,9 @@ class Bucket
      * @param array|object $filter  Query by which to filter documents
      * @param array        $options Additional options
      * @return Cursor
+     * @throws UnsupportedException if options are not supported by the selected server
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function find($filter = [], array $options = [])
     {
@@ -231,6 +241,9 @@ class Bucket
      * @param array|object $filter  Query by which to filter documents
      * @param array        $options Additional options
      * @return array|object|null
+     * @throws UnsupportedException if options are not supported by the selected server
+     * @throws InvalidArgumentException for parameter/option parsing errors
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function findOne($filter = [], array $options = [])
     {
@@ -262,7 +275,8 @@ class Bucket
      *
      * @param resource $stream GridFS stream
      * @return array|object
-     * @throws InvalidArgumentException
+     * @throws InvalidArgumentException if $stream is not a GridFS stream
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function getFileDocumentForStream($stream)
     {
@@ -277,8 +291,9 @@ class Bucket
      *
      * @param resource $stream GridFS stream
      * @return mixed
-     * @throws CorruptFileException
-     * @throws InvalidArgumentException
+     * @throws CorruptFileException if the file "_id" field does not exist
+     * @throws InvalidArgumentException if $stream is not a GridFS stream
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function getFileIdForStream($stream)
     {
@@ -302,7 +317,8 @@ class Bucket
      *
      * @param mixed $id File ID
      * @return resource
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if no file could be selected
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function openDownloadStream($id)
     {
@@ -337,7 +353,8 @@ class Bucket
      * @param string $filename Filename
      * @param array  $options  Download options
      * @return resource
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if no file could be selected
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function openDownloadStreamByName($filename, array $options = [])
     {
@@ -390,7 +407,8 @@ class Bucket
      *
      * @param mixed  $id          File ID
      * @param string $newFilename New filename
-     * @throws FileNotFoundException
+     * @throws FileNotFoundException if no file could be selected
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function rename($id, $newFilename)
     {
@@ -431,7 +449,8 @@ class Bucket
      * @param resource $source   Readable stream
      * @param array    $options  Stream options
      * @return mixed ID of the newly created GridFS file
-     * @throws InvalidArgumentException if $source is not a stream
+     * @throws InvalidArgumentException if $source is not a GridFS stream
+     * @throws DriverRuntimeException for other driver errors (e.g. connection errors)
      */
     public function uploadFromStream($filename, $source, array $options = [])
     {