From 9c65561d9558176f23c09a170a0d6c754ce7a306 Mon Sep 17 00:00:00 2001 From: Katherine Walker Date: Thu, 12 Apr 2018 15:53:51 -0400 Subject: [PATCH] PHPLIB-233: Add examples for each GridFS API method --- .../method/MongoDBGridFSBucket-delete.txt | 17 ++++++- .../MongoDBGridFSBucket-downloadToStream.txt | 27 +++++++++++- ...oDBGridFSBucket-downloadToStreamByName.txt | 27 +++++++++++- .../method/MongoDBGridFSBucket-drop.txt | 19 +++++++- .../method/MongoDBGridFSBucket-find.txt | 44 ++++++++++++++++++- .../method/MongoDBGridFSBucket-findOne.txt | 41 ++++++++++++++++- .../MongoDBGridFSBucket-getBucketName.txt | 15 ++++++- .../MongoDBGridFSBucket-getChunkSizeBytes.txt | 15 ++++++- ...ongoDBGridFSBucket-getChunksCollection.txt | 15 ++++++- .../MongoDBGridFSBucket-getDatabaseName.txt | 16 ++++++- ...BGridFSBucket-getFileDocumentForStream.txt | 34 +++++++++++++- ...MongoDBGridFSBucket-getFileIdForStream.txt | 24 +++++++++- ...MongoDBGridFSBucket-getFilesCollection.txt | 18 +++++++- ...MongoDBGridFSBucket-openDownloadStream.txt | 23 +++++++++- ...BGridFSBucket-openDownloadStreamByName.txt | 21 ++++++++- .../MongoDBGridFSBucket-openUploadStream.txt | 20 ++++++++- .../method/MongoDBGridFSBucket-rename.txt | 23 +++++++++- .../MongoDBGridFSBucket-uploadFromStream.txt | 24 +++++++++- .../method/MongoDBGridFSBucket__construct.txt | 20 ++++++++- 19 files changed, 422 insertions(+), 21 deletions(-) diff --git a/docs/reference/method/MongoDBGridFSBucket-delete.txt b/docs/reference/method/MongoDBGridFSBucket-delete.txt index 6e4eeac55..b063337e7 100644 --- a/docs/reference/method/MongoDBGridFSBucket-delete.txt +++ b/docs/reference/method/MongoDBGridFSBucket-delete.txt @@ -37,4 +37,19 @@ Behavior If the files collection document is not found, this method will still attempt to delete orphaned chunks. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $id = $bucket->uploadFromStream('filename', $stream); + + $bucket->delete($id); diff --git a/docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt b/docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt index 620095010..3d8e6ebcf 100644 --- a/docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt +++ b/docs/reference/method/MongoDBGridFSBucket-downloadToStream.txt @@ -26,8 +26,6 @@ Definition .. include:: /includes/apiargs/MongoDBGridFSBucket-method-downloadToStream-param.rst -.. todo: add examples - Errors/Exceptions ----------------- @@ -35,6 +33,31 @@ Errors/Exceptions .. include:: /includes/extracts/error-invalidargumentexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $id = $bucket->uploadFromStream('filename', $stream); + + $destination = fopen('php://temp', 'w+b'); + + $bucket->downloadToStream($id, $destination); + + var_dump(stream_get_contents($destination, -1, 0)); + +The output would then resemble:: + + string(6) "foobar" + See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt b/docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt index ca294bc32..002bdc654 100644 --- a/docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt +++ b/docs/reference/method/MongoDBGridFSBucket-downloadToStreamByName.txt @@ -30,8 +30,6 @@ Definition .. include:: /includes/apiargs/MongoDBGridFSBucket-method-downloadToStreamByName-option.rst -.. todo: add examples - Errors/Exceptions ----------------- @@ -39,6 +37,31 @@ Errors/Exceptions .. include:: /includes/extracts/error-invalidargumentexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('filename', $stream); + + $destination = fopen('php://temp', 'w+b'); + + $bucket->downloadToStreamByName('filename', $destination); + + var_dump(stream_get_contents($destination, -1, 0)); + +The output would then resemble:: + + string(6) "foobar" + See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-drop.txt b/docs/reference/method/MongoDBGridFSBucket-drop.txt index a6730fc88..53a10091a 100644 --- a/docs/reference/method/MongoDBGridFSBucket-drop.txt +++ b/docs/reference/method/MongoDBGridFSBucket-drop.txt @@ -26,4 +26,21 @@ Errors/Exceptions .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test; + + $bucket = $database->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('filename', $stream); + + $bucket->drop(); diff --git a/docs/reference/method/MongoDBGridFSBucket-find.txt b/docs/reference/method/MongoDBGridFSBucket-find.txt index 8f40253e7..c7418cede 100644 --- a/docs/reference/method/MongoDBGridFSBucket-find.txt +++ b/docs/reference/method/MongoDBGridFSBucket-find.txt @@ -46,7 +46,49 @@ Behavior .. include:: /includes/extracts/note-bson-comparison.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('b', $stream); + + $cursor = $bucket->find( + ['length' => ['$lte' => 6]], + [ + 'projection' => [ + 'filename' => 1, + 'length' => 1, + '_id' => 0, + ], + 'sort' => ['length' => -1], + ] + ); + + var_dump($cursor->toArray()); + +The output would then resemble:: + + array(1) { + [0]=> + object(MongoDB\Model\BSONDocument)#3015 (1) { + ["storage":"ArrayObject":private]=> + array(2) { + ["filename"]=> + string(1) "b" + ["length"]=> + int(6) + } + } + } See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-findOne.txt b/docs/reference/method/MongoDBGridFSBucket-findOne.txt index f07a61349..7b6fcc8fc 100644 --- a/docs/reference/method/MongoDBGridFSBucket-findOne.txt +++ b/docs/reference/method/MongoDBGridFSBucket-findOne.txt @@ -49,7 +49,46 @@ Behavior .. include:: /includes/extracts/note-bson-comparison.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('b', $stream); + + $fileDocument = $bucket->findOne( + ['length' => ['$lte' => 6]], + [ + 'projection' => [ + 'filename' => 1, + 'length' => 1, + '_id' => 0, + ], + 'sort' => ['length' => -1], + ] + ); + + var_dump($fileDocument); + +The output would then resemble:: + + object(MongoDB\Model\BSONDocument)#3004 (1) { + ["storage":"ArrayObject":private]=> + array(2) { + ["filename"]=> + string(1) "b" + ["length"]=> + int(6) + } + } See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-getBucketName.txt b/docs/reference/method/MongoDBGridFSBucket-getBucketName.txt index d8a43a3c6..0452de0a7 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getBucketName.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getBucketName.txt @@ -26,4 +26,17 @@ Return Values The name of this bucket as a string. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + var_dump($bucket->getBucketName()); + +The output would then resemble:: + + string(2) "fs" diff --git a/docs/reference/method/MongoDBGridFSBucket-getChunkSizeBytes.txt b/docs/reference/method/MongoDBGridFSBucket-getChunkSizeBytes.txt index 3a97aba79..f592030a2 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getChunkSizeBytes.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getChunkSizeBytes.txt @@ -28,4 +28,17 @@ Return Values The chunk size of this bucket in bytes. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + var_dump($bucket->getChunkSizeBytes()); + +The output would then resemble:: + + int(261120) diff --git a/docs/reference/method/MongoDBGridFSBucket-getChunksCollection.txt b/docs/reference/method/MongoDBGridFSBucket-getChunksCollection.txt index cc98abede..fa5be8322 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getChunksCollection.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getChunksCollection.txt @@ -28,4 +28,17 @@ Return Values A :phpclass:`MongoDB\\Collection` object for the chunks collection. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + var_dump((string) $bucket->getChunksCollection()); + +The output would then resemble:: + + string(14) "test.fs.chunks" diff --git a/docs/reference/method/MongoDBGridFSBucket-getDatabaseName.txt b/docs/reference/method/MongoDBGridFSBucket-getDatabaseName.txt index dc3ceeaaa..b270b7b57 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getDatabaseName.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getDatabaseName.txt @@ -26,4 +26,18 @@ Return Values The name of the database containing this bucket as a string. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + var_dump($bucket->getDatabaseName()); + +The output would then resemble:: + + string(4) "test" + diff --git a/docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt b/docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt index faa589139..052bc79c9 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getFileDocumentForStream.txt @@ -37,7 +37,39 @@ Errors/Exceptions .. include:: /includes/extracts/error-invalidargumentexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = $bucket->openUploadStream('filename'); + + $fileDocument = $bucket->getFileDocumentForStream($stream); + + var_dump($fileDocument); + + fclose($stream); + +The output would then resemble:: + + object(MongoDB\Model\BSONDocument)#4956 (1) { + ["storage":"ArrayObject":private]=> + array(3) { + ["_id"]=> + object(MongoDB\BSON\ObjectId)#4955 (1) { + ["oid"]=> + string(24) "5acfb05b7e21e83b5a29037c" + } + ["chunkSize"]=> + int(261120) + ["filename"]=> + string(8) "filename" + } + } See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt b/docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt index b7ef99649..976843b4d 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getFileIdForStream.txt @@ -38,7 +38,29 @@ Errors/Exceptions .. include:: /includes/extracts/error-invalidargumentexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = $bucket->openUploadStream('filename'); + + $id = $bucket->getFileIdForStream($stream); + + var_dump($id); + + fclose($stream); + +The output would then resemble:: + + object(MongoDB\BSON\ObjectId)#3005 (1) { + ["oid"]=> + string(24) "5acfb37d7e21e83cdb3e1583" + } See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-getFilesCollection.txt b/docs/reference/method/MongoDBGridFSBucket-getFilesCollection.txt index e989202bd..de4196b2f 100644 --- a/docs/reference/method/MongoDBGridFSBucket-getFilesCollection.txt +++ b/docs/reference/method/MongoDBGridFSBucket-getFilesCollection.txt @@ -28,4 +28,20 @@ Return Values A :phpclass:`MongoDB\\Collection` object for the files collection. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $filesCollection = $bucket->getFilesCollection(); + + var_dump($filesCollection->getCollectionName()); + +The output would then resemble:: + + string(8) "fs.files" + diff --git a/docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt b/docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt index 69f6d54f0..663a69c95 100644 --- a/docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt +++ b/docs/reference/method/MongoDBGridFSBucket-openDownloadStream.txt @@ -36,7 +36,28 @@ Errors/Exceptions .. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $uploadStream = fopen('php://temp', 'w+b'); + fwrite($uploadStream, "foobar"); + rewind($uploadStream); + + $id = $bucket->uploadFromStream('filename', $uploadStream); + + $downloadStream = $bucket->openDownloadStream($id); + + var_dump(stream_get_contents($downloadStream)); + +The output would then resemble:: + + string(6) "foobar" See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt b/docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt index b49768525..d9f7b5b44 100644 --- a/docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt +++ b/docs/reference/method/MongoDBGridFSBucket-openDownloadStreamByName.txt @@ -40,7 +40,26 @@ Errors/Exceptions .. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $bucket->uploadFromStream('filename', $stream); + + var_dump(stream_get_contents($bucket->openDownloadStreamByName('filename'))); + +The output would then resemble:: + + string(6) "foobar" See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt b/docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt index 2ad11c4aa..806ad6b8b 100644 --- a/docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt +++ b/docs/reference/method/MongoDBGridFSBucket-openUploadStream.txt @@ -40,7 +40,25 @@ Behavior Chunk documents will be created as data is written to the writable stream. The metadata document will be created when the writable stream is closed. -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $uploadStream = $bucket->openUploadStream('filename'); + fwrite($uploadStream, 'foobar'); + fclose($uploadStream); + + $downloadStream = $bucket->openDownloadStreamByName('filename'); + var_dump(stream_get_contents($downloadStream)); + +The output would then resemble:: + + string(6) "foobar" See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket-rename.txt b/docs/reference/method/MongoDBGridFSBucket-rename.txt index 77fd899e1..346ffd81f 100644 --- a/docs/reference/method/MongoDBGridFSBucket-rename.txt +++ b/docs/reference/method/MongoDBGridFSBucket-rename.txt @@ -31,4 +31,25 @@ Errors/Exceptions .. include:: /includes/extracts/error-gridfs-filenotfoundexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $id = $bucket->uploadFromStream('a', $stream); + + $bucket->rename($id, 'b'); + + var_dump(stream_get_contents($bucket->openDownloadStreamByName('b'))); + +The output would then resemble:: + + string(6) "foobar" diff --git a/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt b/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt index fa26bacc8..b5d5abefc 100644 --- a/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt +++ b/docs/reference/method/MongoDBGridFSBucket-uploadFromStream.txt @@ -43,7 +43,29 @@ Errors/Exceptions .. include:: /includes/extracts/error-invalidargumentexception.rst .. include:: /includes/extracts/error-driver-runtimeexception.rst -.. todo: add examples +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + $stream = fopen('php://temp', 'w+b'); + fwrite($stream, "foobar"); + rewind($stream); + + $id = $bucket->uploadFromStream('filename', $stream); + + var_dump($id); + +The output would then resemble:: + + object(MongoDB\BSON\ObjectId)#3009 (1) { + ["oid"]=> + string(24) "5acf81017e21e816e538d883" + } See Also -------- diff --git a/docs/reference/method/MongoDBGridFSBucket__construct.txt b/docs/reference/method/MongoDBGridFSBucket__construct.txt index 94e601ef2..49211fba7 100644 --- a/docs/reference/method/MongoDBGridFSBucket__construct.txt +++ b/docs/reference/method/MongoDBGridFSBucket__construct.txt @@ -42,7 +42,25 @@ from the :php:`MongoDB\\Driver\\Manager ` object. If you select the Bucket from a :phpclass:`Database ` object, the Bucket inherits its options from that object. -.. todo: add an example +Examples +-------- + +.. code-block:: php + + test->selectGridFSBucket(); + + var_dump($bucket); + +The output would then resemble:: + + object(MongoDB\GridFS\Bucket)#3053 (2) { + ["bucketName"]=> + string(4) "test" + ["databaseName"]=> + string(11) "phplib_test" + } See Also --------