Merge pull request #296

jmikola · jmikola · commit d259a5ff3c33 · 2016-12-01T17:33:35.000+01:00
diff --git a/docs/includes/extracts-error.yaml b/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.
 ...
diff --git a/docs/reference/exception-classes.txt b/docs/reference/exception-classes.txt
@@ -77,8 +77,7 @@ MongoDB\\Exception\\UnsupportedException
    unintended document being deleted.
 
    This class extends the library's :phpclass:`RuntimeException
-   <MongoDB\\Exception\\RuntimeException>` class and implements the
-   library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.
+   <MongoDB\\Exception\\RuntimeException>` class.
 
    .. note::
 
@@ -89,6 +88,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
 -----------------------------
 
diff --git a/docs/reference/method/MongoDBGridFSBucket-delete.txt b/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
 --------
 
diff --git a/docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt b/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
 --------
 
diff --git a/docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt b/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
 --------
 
diff --git a/docs/reference/method/MongoDBGridFSBucket-drop.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-find.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-findOne.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-rename.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt b/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
diff --git a/docs/reference/method/MongoDBGridFSBucket__construct.txt b/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
 --------
 
diff --git a/src/Exception/UnsupportedException.php b/src/Exception/UnsupportedException.php
@@ -2,7 +2,7 @@
 
 namespace MongoDB\Exception;
 
-class UnsupportedException extends RuntimeException implements Exception
+class UnsupportedException extends RuntimeException
 {
     /**
      * Thrown when collations are not supported by a server.
diff --git a/src/GridFS/Bucket.php b/src/GridFS/Bucket.php
@@ -7,7 +7,9 @@
 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 @@ public function __debugInfo()
      * 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 @@ public function delete($id)
      *
      * @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 @@ public function downloadToStream($id, $destination)
      * @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 @@ public function downloadToStreamByName($filename, $destination, array $options =
     /**
      * 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 @@ public function drop()
      * @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 @@ public function find($filter = [], array $options = [])
      * @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 @@ public function getDatabaseName()
      *
      * @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 @@ public function getFileDocumentForStream($stream)
      *
      * @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 @@ public function getFileIdForStream($stream)
      *
      * @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 @@ public function openDownloadStream($id)
      * @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 @@ public function openUploadStream($filename, array $options = [])
      *
      * @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 @@ public function rename($id, $newFilename)
      * @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 = [])
     {
diff --git a/src/GridFS/WritableStream.php b/src/GridFS/WritableStream.php
