DOCSP-45100: Delete and rename by name (#187)

* DOCSP-45100: Delete and rename by name

* edits

* JM feedback

(cherry picked from commit 343f339)

Author: norareidy

source/includes/write/gridfs.php

@@ -81,11 +81,21 @@ function toJSON(object $document): string
 // end-download-to-stream
 
 // Renames a file from the GridFS bucket with the specified ObjectId
-// start-rename-files
+// start-rename-files-id
 $bucket->rename(new ObjectId('66e0a5487c880f844c0a32b1'), 'new_file_name');
-// end-rename-files
+// end-rename-files-id
+
+// Renames files from the GridFS bucket with the specified filename
+// start-rename-files-name
+$bucket->renameByName('my_file', 'new_file_name');
+// end-rename-files-name
 
 // Deletes a file from the GridFS bucket with the specified ObjectId
-// start-delete-files
+// start-delete-files-id
 $bucket->delete(new ObjectId('66e0a5487c880f844c0a32b1'));
-// end-delete-files
+// end-delete-files-id
+
+// Deletes a file and its revisions from the GridFS bucket by name
+// start-delete-files-name
+$bucket->deleteByName('my_file');
+// end-delete-files-name

source/write/gridfs.txt

@@ -375,48 +375,65 @@ Rename Files
 ------------
 
 Use the ``MongoDB\GridFS\Bucket::rename()`` method to update the name of
-a GridFS file in your bucket. You must specify the file to rename by its
-``_id`` field rather than its file name. 
+a GridFS file in your bucket. Pass the following parameters to the ``rename()``
+method:
+
+-  ``_id`` value of the file you want to rename
+- New file name
 
 The following example shows how to update the ``filename`` field to
-``'new_file_name'`` by referencing a document's ``_id`` field:
+``'new_file_name'`` by referencing a file's ``_id`` value:
 
 .. literalinclude:: /includes/write/gridfs.php
    :language: php
    :dedent:
-   :start-after: start-rename-files
-   :end-before: end-rename-files
+   :start-after: start-rename-files-id
+   :end-before: end-rename-files-id
+
+Alternatively, you can use the ``MongoDB\GridFS\Bucket::renameByName()``
+method to rename a GridFS file and all its file revisions. Pass the 
+following parameters to the ``renameByName()`` method:
 
-.. note:: File Revisions
+- ``filename`` value you want to change
+- New file name
 
-   The ``rename()`` method supports updating the name of only one file at
-   a time. If you want to rename each file revision, or files with different upload
-   times that share the same file name, collect the ``_id`` values of each revision.
-   Then, pass each value in separate calls to the ``rename()`` method.
+The following example renames all files that have a ``filename`` value
+of ``'my_file'``:
+
+.. literalinclude:: /includes/write/gridfs.php
+   :language: php
+   :dedent:
+   :start-after: start-rename-files-name
+   :end-before: end-rename-files-name
 
 .. _gridfs-delete-files:
 
 Delete Files
 ------------
 
-Use the ``MongoDB\GridFS\Bucket::delete()`` method to remove a file's collection
+Use the ``MongoDB\GridFS\Bucket::delete()`` method to remove a GridFS file's collection
 document and associated chunks from your bucket. This effectively deletes the file.
-You must specify the file by its ``_id`` field rather than its file name.
+Pass the ``_id`` value of the file you want to delete as a parameter to the
+``delete()`` method.
 
 The following example shows you how to delete a file by referencing its ``_id`` field:
 
 .. literalinclude:: /includes/write/gridfs.php
    :language: php
    :dedent:
-   :start-after: start-delete-files
-   :end-before: end-delete-files
+   :start-after: start-delete-files-id
+   :end-before: end-delete-files-id
 
-.. note:: File Revisions
+Alternatively, you can use the ``MongoDB\GridFS\Bucket::deleteByName()`` method
+to delete a GridFS file and all its file revisions. Pass the ``filename`` value of the
+file you want to delete as a parameter to the ``deleteByName()`` method, as shown
+in the following code:
 
-   The ``delete()`` method supports deleting only one file at a time. If
-   you want to delete each file revision, or files with different upload
-   times that share the same file name, collect the ``_id`` values of each revision.
-   Then, pass each value in separate calls to the ``delete()`` method.
+.. literalinclude:: /includes/write/gridfs.php
+   :language: php
+   :dedent:
+   :start-after: start-delete-files-name
+   :end-before: end-delete-files-name
 
 API Documentation
 -----------------