From f4a4f85e323b5a6f972986baa5f0eb128a958f6d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 9 Dec 2024 10:57:56 -0500 Subject: [PATCH 1/3] DOCSP-45100: Delete and rename by name --- source/includes/write/gridfs.php | 18 ++++++++--- source/write/gridfs.txt | 51 +++++++++++++++++++++----------- 2 files changed, 48 insertions(+), 21 deletions(-) diff --git a/source/includes/write/gridfs.php b/source/includes/write/gridfs.php index bb94ce63..104a90cf 100644 --- a/source/includes/write/gridfs.php +++ b/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 diff --git a/source/write/gridfs.txt b/source/write/gridfs.txt index 69ddd798..e801a4fd 100644 --- a/source/write/gridfs.txt +++ b/source/write/gridfs.txt @@ -375,8 +375,11 @@ 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 document 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: @@ -384,15 +387,24 @@ The following example shows how to update the ``filename`` field to .. 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: @@ -401,22 +413,27 @@ Delete Files Use the ``MongoDB\GridFS\Bucket::delete()`` method to remove a 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 file and all its file revisions. Pass the ``filename`` value of the +files 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 ----------------- From da2908427d10eedbba421affcd439b6ef2f08c82 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 9 Dec 2024 11:02:54 -0500 Subject: [PATCH 2/3] edits --- source/write/gridfs.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/write/gridfs.txt b/source/write/gridfs.txt index e801a4fd..ac3bcd62 100644 --- a/source/write/gridfs.txt +++ b/source/write/gridfs.txt @@ -378,11 +378,11 @@ Use the ``MongoDB\GridFS\Bucket::rename()`` method to update the name of a GridFS file in your bucket. Pass the following parameters to the ``rename()`` method: -- ``_id`` value of the document you want to rename +- ``_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 @@ -426,7 +426,7 @@ The following example shows you how to delete a file by referencing its ``_id`` Alternatively, you can use the ``MongoDB\GridFS\Bucket::deleteByName()`` method to delete a file and all its file revisions. Pass the ``filename`` value of the -files you want to delete as a parameter to the ``deleteByName()`` method, as shown +file you want to delete as a parameter to the ``deleteByName()`` method, as shown in the following code: .. literalinclude:: /includes/write/gridfs.php From 3d8bf5e5f953680028b857b72af282bf133c2c55 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 9 Dec 2024 13:23:36 -0500 Subject: [PATCH 3/3] JM feedback --- source/write/gridfs.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/write/gridfs.txt b/source/write/gridfs.txt index ac3bcd62..1cac77cb 100644 --- a/source/write/gridfs.txt +++ b/source/write/gridfs.txt @@ -411,7 +411,7 @@ of ``'my_file'``: 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. Pass the ``_id`` value of the file you want to delete as a parameter to the ``delete()`` method. @@ -425,7 +425,7 @@ The following example shows you how to delete a file by referencing its ``_id`` :end-before: end-delete-files-id Alternatively, you can use the ``MongoDB\GridFS\Bucket::deleteByName()`` method -to delete a file and all its file revisions. Pass the ``filename`` value of the +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: