Skip to content

Commit d259a5f

Browse files
jmikolajmikola
committed
Merge pull request #296 
2 parents 34ae987 + 470fcca commit d259a5f

18 files changed

+154
-27
lines changed

‎docs/includes/extracts-error.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,14 @@ content: |
3131
:phpclass:`MongoDB\\Exception\\UnsupportedException` if options are used and
3232
not supported by the selected server (e.g. ``collation``, ``readConcern``,
3333
``writeConcern``).
34+
---
35+
ref: error-gridfs-filenotfoundexception
36+
content: |
37+
:phpclass:`MongoDB\\GridFS\\Exception\\FileNotFoundException` if no file was
38+
found for the selection criteria.
39+
---
40+
ref: error-gridfs-corruptfileexception
41+
content: |
42+
:phpclass:`MongoDB\\GridFS\\Exception\\CorruptFileException` if the file's
43+
metadata or chunk documents contain unexpected or invalid data.
3444
...

‎docs/reference/exception-classes.txt

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,7 @@ MongoDB\\Exception\\UnsupportedException
7777
unintended document being deleted.
7878

7979
This class extends the library's :phpclass:`RuntimeException
80-
<MongoDB\\Exception\\RuntimeException>` class and implements the
81-
library's :phpclass:`Exception <MongoDB\\Exception\\Exception>` interface.
80+
<MongoDB\\Exception\\RuntimeException>` class.
8281

8382
.. note::
8483

@@ -89,6 +88,37 @@ MongoDB\\Exception\\UnsupportedException
8988

9089
----
9190

91+
MongoDB\\GridFS\\Exception\\CorruptFileException
92+
----------------------------------------
93+
94+
.. phpclass:: MongoDB\\GridFS\\Exception\\CorruptFileException
95+
96+
This exception is thrown if a GridFS file's metadata or chunk documents
97+
contain unexpected or invalid data.
98+
99+
When selecting a GridFS file, this may be thrown if a metadata field has an
100+
incorrect type or its value is out of range (e.g. negative ``length``). When
101+
reading a GridFS file, this may be thrown if a chunk's index is out of
102+
sequence or its binary data's length out of range.
103+
104+
This class extends the library's :phpclass:`RuntimeException
105+
<MongoDB\\Exception\\RuntimeException>` class.
106+
107+
----
108+
109+
MongoDB\\GridFS\\Exception\\FileNotFoundException
110+
----------------------------------------
111+
112+
.. phpclass:: MongoDB\\GridFS\\Exception\\FileNotFoundException
113+
114+
This exception is thrown if no GridFS file was found for the selection
115+
criteria (e.g. ``id``, ``filename``).
116+
117+
This class extends the library's :phpclass:`RuntimeException
118+
<MongoDB\\Exception\\RuntimeException>` class.
119+
120+
----
121+
92122
MongoDB\\Exception\\Exception
93123
-----------------------------
94124

‎docs/reference/method/MongoDBGridFSBucket-delete.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,12 @@ Definition
2525

2626
.. include:: /includes/apiargs/MongoDBGridFSBucket-method-delete-param.rst
2727

28+
Errors/Exceptions
29+
-----------------
30+
31+
.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
32+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
33+
2834
Behavior
2935
--------
3036

‎docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,13 @@ Definition
2828

2929
.. todo: add examples
3030

31+
Errors/Exceptions
32+
-----------------
33+
34+
.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
35+
.. include:: /includes/extracts/error-invalidargumentexception.rst
36+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
37+
3138
See Also
3239
--------
3340

‎docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,13 @@ Definition
3232

3333
.. todo: add examples
3434

35+
Errors/Exceptions
36+
-----------------
37+
38+
.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
39+
.. include:: /includes/extracts/error-invalidargumentexception.rst
40+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
41+
3542
See Also
3643
--------
3744

‎docs/reference/method/MongoDBGridFSBucket-drop.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,9 @@ Definition
2121

2222
function drop(): void
2323

24+
Errors/Exceptions
25+
-----------------
26+
27+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
28+
2429
.. todo: add examples

‎docs/reference/method/MongoDBGridFSBucket-find.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,13 @@ Return Values
3434

3535
A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` object.
3636

37+
Errors/Exceptions
38+
-----------------
39+
40+
.. include:: /includes/extracts/error-unsupportedexception.rst
41+
.. include:: /includes/extracts/error-invalidargumentexception.rst
42+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
43+
3744
.. todo: add examples
3845

3946
See Also

‎docs/reference/method/MongoDBGridFSBucket-findOne.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,13 @@ An array or object for the :term:`first document <natural order>` that matched
3737
the query, or ``null`` if no document matched the query. The return type will
3838
depend on the ``typeMap`` option.
3939

40+
Errors/Exceptions
41+
-----------------
42+
43+
.. include:: /includes/extracts/error-unsupportedexception.rst
44+
.. include:: /includes/extracts/error-invalidargumentexception.rst
45+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
46+
4047
.. todo: add examples
4148

4249
See Also

‎docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ Return Values
3131
The metadata document associated with the GridFS stream. The return type will
3232
depend on the bucket's ``typeMap`` option.
3333

34+
Errors/Exceptions
35+
-----------------
36+
37+
.. include:: /includes/extracts/error-invalidargumentexception.rst
38+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
39+
3440
.. todo: add examples
3541

3642
See Also

‎docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,13 @@ Return Values
3131
The ``_id`` field of the metadata document associated with the GridFS stream.
3232
The return type will depend on the bucket's ``typeMap`` option.
3333

34+
Errors/Exceptions
35+
-----------------
36+
37+
.. include:: /includes/extracts/error-gridfs-corruptfileexception.rst
38+
.. include:: /includes/extracts/error-invalidargumentexception.rst
39+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
40+
3441
.. todo: add examples
3542

3643
See Also

‎docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,12 @@ Return Values
3030

3131
A readable stream resource.
3232

33+
Errors/Exceptions
34+
-----------------
35+
36+
.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
37+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
38+
3339
.. todo: add examples
3440

3541
See Also

‎docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,12 @@ Return Values
3434

3535
A readable stream resource.
3636

37+
Errors/Exceptions
38+
-----------------
39+
40+
.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
41+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
42+
3743
.. todo: add examples
3844

3945
See Also

‎docs/reference/method/MongoDBGridFSBucket-rename.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,10 @@ Definition
2525

2626
.. include:: /includes/apiargs/MongoDBGridFSBucket-method-rename-param.rst
2727

28+
Errors/Exceptions
29+
-----------------
30+
31+
.. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst
32+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
33+
2834
.. todo: add examples

‎docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,12 @@ GridFS file. If the ``_id`` option is not specified, a new
3737
:php:`MongoDB\\BSON\\ObjectID <class.mongodb-bson-objectid>` object will be used
3838
by default.
3939

40+
Errors/Exceptions
41+
-----------------
42+
43+
.. include:: /includes/extracts/error-invalidargumentexception.rst
44+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
45+
4046
.. todo: add examples
4147

4248
See Also

‎docs/reference/method/MongoDBGridFSBucket__construct.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,11 @@ Definition
2929

3030
.. include:: /includes/apiargs/MongoDBGridFSBucket-method-construct-option.rst
3131

32+
Errors/Exceptions
33+
-----------------
34+
35+
.. include:: /includes/extracts/error-invalidargumentexception.rst
36+
3237
Behavior
3338
--------
3439

‎src/Exception/UnsupportedException.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
namespace MongoDB\Exception;
44

5-
class UnsupportedException extends RuntimeException implements Exception
5+
class UnsupportedException extends RuntimeException
66
{
77
/**
88
* Thrown when collations are not supported by a server.

‎src/GridFS/Bucket.php

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@
77
use MongoDB\Driver\ReadConcern;
88
use MongoDB\Driver\ReadPreference;
99
use MongoDB\Driver\WriteConcern;
10+
use MongoDB\Driver\Exception\RuntimeException as DriverRuntimeException;
1011
use MongoDB\Exception\InvalidArgumentException;
12+
use MongoDB\Exception\UnexpectedValueException;
1113
use MongoDB\GridFS\Exception\CorruptFileException;
1214
use MongoDB\GridFS\Exception\FileNotFoundException;
1315
use MongoDB\Operation\Find;
@@ -62,7 +64,7 @@ class Bucket
6264
* @param Manager $manager Manager instance from the driver
6365
* @param string $databaseName Database name
6466
* @param array $options Bucket options
65-
* @throws InvalidArgumentException
67+
* @throws InvalidArgumentException for parameter/option parsing errors
6668
*/
6769
public function __construct(Manager $manager, $databaseName, array $options = [])
6870
{
@@ -137,7 +139,8 @@ public function __debugInfo()
137139
* attempt to delete orphaned chunks.
138140
*
139141
* @param mixed $id File ID
140-
* @throws FileNotFoundException
142+
* @throws FileNotFoundException if no file could be selected
143+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
141144
*/
142145
public function delete($id)
143146
{
@@ -154,8 +157,9 @@ public function delete($id)
154157
*
155158
* @param mixed $id File ID
156159
* @param resource $destination Writable Stream
157-
* @throws FileNotFoundException
160+
* @throws FileNotFoundException if no file could be selected
158161
* @throws InvalidArgumentException if $destination is not a stream
162+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
159163
*/
160164
public function downloadToStream($id, $destination)
161165
{
@@ -188,8 +192,9 @@ public function downloadToStream($id, $destination)
188192
* @param string $filename Filename
189193
* @param resource $destination Writable Stream
190194
* @param array $options Download options
191-
* @throws FileNotFoundException
195+
* @throws FileNotFoundException if no file could be selected
192196
* @throws InvalidArgumentException if $destination is not a stream
197+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
193198
*/
194199
public function downloadToStreamByName($filename, $destination, array $options = [])
195200
{
@@ -203,6 +208,8 @@ public function downloadToStreamByName($filename, $destination, array $options =
203208
/**
204209
* Drops the files and chunks collections associated with this GridFS
205210
* bucket.
211+
*
212+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
206213
*/
207214
public function drop()
208215
{
@@ -217,6 +224,9 @@ public function drop()
217224
* @param array|object $filter Query by which to filter documents
218225
* @param array $options Additional options
219226
* @return Cursor
227+
* @throws UnsupportedException if options are not supported by the selected server
228+
* @throws InvalidArgumentException for parameter/option parsing errors
229+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
220230
*/
221231
public function find($filter = [], array $options = [])
222232
{
@@ -231,6 +241,9 @@ public function find($filter = [], array $options = [])
231241
* @param array|object $filter Query by which to filter documents
232242
* @param array $options Additional options
233243
* @return array|object|null
244+
* @throws UnsupportedException if options are not supported by the selected server
245+
* @throws InvalidArgumentException for parameter/option parsing errors
246+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
234247
*/
235248
public function findOne($filter = [], array $options = [])
236249
{
@@ -262,7 +275,8 @@ public function getDatabaseName()
262275
*
263276
* @param resource $stream GridFS stream
264277
* @return array|object
265-
* @throws InvalidArgumentException
278+
* @throws InvalidArgumentException if $stream is not a GridFS stream
279+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
266280
*/
267281
public function getFileDocumentForStream($stream)
268282
{
@@ -277,8 +291,9 @@ public function getFileDocumentForStream($stream)
277291
*
278292
* @param resource $stream GridFS stream
279293
* @return mixed
280-
* @throws CorruptFileException
281-
* @throws InvalidArgumentException
294+
* @throws CorruptFileException if the file "_id" field does not exist
295+
* @throws InvalidArgumentException if $stream is not a GridFS stream
296+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
282297
*/
283298
public function getFileIdForStream($stream)
284299
{
@@ -302,7 +317,8 @@ public function getFileIdForStream($stream)
302317
*
303318
* @param mixed $id File ID
304319
* @return resource
305-
* @throws FileNotFoundException
320+
* @throws FileNotFoundException if no file could be selected
321+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
306322
*/
307323
public function openDownloadStream($id)
308324
{
@@ -337,7 +353,8 @@ public function openDownloadStream($id)
337353
* @param string $filename Filename
338354
* @param array $options Download options
339355
* @return resource
340-
* @throws FileNotFoundException
356+
* @throws FileNotFoundException if no file could be selected
357+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
341358
*/
342359
public function openDownloadStreamByName($filename, array $options = [])
343360
{
@@ -390,7 +407,8 @@ public function openUploadStream($filename, array $options = [])
390407
*
391408
* @param mixed $id File ID
392409
* @param string $newFilename New filename
393-
* @throws FileNotFoundException
410+
* @throws FileNotFoundException if no file could be selected
411+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
394412
*/
395413
public function rename($id, $newFilename)
396414
{
@@ -431,7 +449,8 @@ public function rename($id, $newFilename)
431449
* @param resource $source Readable stream
432450
* @param array $options Stream options
433451
* @return mixed ID of the newly created GridFS file
434-
* @throws InvalidArgumentException if $source is not a stream
452+
* @throws InvalidArgumentException if $source is not a GridFS stream
453+
* @throws DriverRuntimeException for other driver errors (e.g. connection errors)
435454
*/
436455
public function uploadFromStream($filename, $source, array $options = [])
437456
{

0 commit comments

Comments
 (0)