DOCSP-41972: GridFS guide #133

norareidy · 2024-09-10T19:32:46Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-41972
Staging - https://deploy-preview-133--docs-php-library.netlify.app/write/gridfs/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2024-09-10T19:33:04Z

✅ Deploy Preview for docs-php-library ready!

Name	Link
🔨 Latest commit	`706a25f`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-php-library/deploys/66e87f26e9939a0008193fe3
😎 Deploy Preview	https://deploy-preview-133--docs-php-library.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rustagir

lgtm with a few open questions. happy to take another look if needed

rustagir · 2024-09-11T15:49:13Z

source/write/gridfs.txt

+It also creates a document in the ``files`` collection that contains
+a file ID, file name, and other file metadata. You can upload the file from
+memory or from a stream. See the following diagram to see how GridFS splits
+the files when uploaded to a bucket.


Suggested change

the files when uploaded to a bucket.

the files when uploaded to a bucket:

rustagir · 2024-09-11T15:49:33Z

source/write/gridfs.txt

+GridFS indexes, see :manual:`GridFS Indexes </core/gridfs/#gridfs-indexes>`
+in the {+mdb-server+} manual.
+
+When storing files with GridFS, the library splits the files into smaller


Suggested change

When storing files with GridFS, the library splits the files into smaller

When using GridFS to store files, the library splits the files into smaller

rustagir · 2024-09-11T15:51:47Z

source/includes/write/gridfs.php

+
+// Creates or references a GridFS bucket with a custom name
+// start create custom bucket
+$db = $client->db_gridfs;


Q: is it necessary to show this line?

I changed to $custom_bucket = $client->db->selectGridFSBucket(), so it still specifies the database

source/includes/write/gridfs.php

source/write/gridfs.txt

jmikola · 2024-09-12T17:37:04Z

source/write/gridfs.txt

+------------
+
+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.


May be worth clarifying that this is going to delete a revision of a file. If another fs.files document exists for that filename, it can still be read. And if users aren't aware of GridFS' revision behavior and selecting the most recent by default, they could be surprised to discover that they can still query for a filename after calling delete(). The clarification should help avoid that.

Note that this also applies to rename(). Common advice for both may be telling users to collect all IDs for a filename if they intend to rename or delete all of its revisions. I don't think you need example code for that (can be left as an exercise for the reader).

I modified the note below the code examples with this information

I see the new "File Revisions" notes for renames/deletes. Is there a DOCSP ticket to track future work of documenting the revision option for download methods? That seems like it'd be generally relevant to all driver GridFS tutorials.

Not currently, although a few pages have a section on revisions (like Java) or mention it somewhere on the page

source/write/gridfs.txt

jmikola

Revisions look good. Only significant suggestion is the change the downloadToStream() and uploadFromStream() examples to use actual files instead of php://temp streams.

source/includes/write/gridfs.php

jmikola · 2024-09-13T18:15:02Z

source/write/gridfs.txt

+- Calls the ``fopen()`` method to create a temporary memory-based stream
+  that you can write to and read from
+- Calls the ``fwrite()`` method to write data to the stream


If you take my suggestion on the example code, these can be reduced to a single bullet that calls fopen() on a local file. You can also note that we open the file in "binary read" mode (i.e. rb).

For the download example, we would fopen() or destination in "binary write" mode (i.e. wb).

source/write/gridfs.txt

jmikola · 2024-09-13T18:21:17Z

source/write/gridfs.txt

+------------
+
+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.


I see the new "File Revisions" notes for renames/deletes. Is there a DOCSP ticket to track future work of documenting the revision option for download methods? That seems like it'd be generally relevant to all driver GridFS tutorials.

jmikola

Two code suggestions but LGTM after that.

jmikola · 2024-09-16T15:04:28Z

source/includes/write/gridfs.php

+use MongoDB\GridFS\Bucket;
+use MongoDB\Driver\Manager;


Suggested change

use MongoDB\GridFS\Bucket;

use MongoDB\Driver\Manager;

These use statements are no longer needed.

jmikola · 2024-09-16T15:07:05Z

source/includes/write/gridfs.php

+$stream = fopen('/path/to/output_file', 'wb');
+$bucket->downloadToStream(
+    new ObjectID('66e0a5487c880f844c0a32b1'),
+    $stream,


Suggested change

$stream = fopen('/path/to/output_file', 'wb');

$bucket->downloadToStream(

new ObjectID('66e0a5487c880f844c0a32b1'),

$stream,

$file = fopen('/path/to/output_file', 'wb');

$bucket->downloadToStream(

new ObjectId('66e0a5487c880f844c0a32b1'),

$file,

Renaming variable for consistency with the start-upload-from-stream example code. This should require no changes to the RST.

source/write/gridfs.txt

jmikola

Realized some additional fixes here while reviewing #136.

jmikola · 2024-09-16T15:36:15Z

source/includes/write/gridfs.php

+<?php
+require 'vendor/autoload.php'; // include Composer's autoloader
+
+use MongoDB\Client;


I missed this earlier. The code below uses new MongoDB\Client(...) so this use statement has no effect. Consider removing it.

Alternatively, decide if you want to rely on use statements for all class references in the interest of consistency. I see you're doing that for new ObjectId(...).

jmikola · 2024-09-16T15:36:54Z

source/includes/write/gridfs.php

+require 'vendor/autoload.php'; // include Composer's autoloader
+
+use MongoDB\Client;
+use MongoDB\BSON\ObjectID;


Suggested change

use MongoDB\BSON\ObjectID;

use MongoDB\BSON\ObjectId;

PHP allows case-insensitive class names, but the canonical name is ObjectId.

jmikola · 2024-09-16T15:37:06Z

source/includes/write/gridfs.php

+
+// Downloads a file from the GridFS bucket by referencing its ObjectID value
+// start-download-files-id
+$stream = $bucket->openDownloadStream(new ObjectID('66e0a5487c880f844c0a32b1'));


Suggested change

$stream = $bucket->openDownloadStream(new ObjectID('66e0a5487c880f844c0a32b1'));

$stream = $bucket->openDownloadStream(new ObjectId('66e0a5487c880f844c0a32b1'));

jmikola · 2024-09-16T15:37:16Z

source/includes/write/gridfs.php

+// start-download-to-stream
+$stream = fopen('/path/to/output_file', 'wb');
+$bucket->downloadToStream(
+    new ObjectID('66e0a5487c880f844c0a32b1'),


Suggested change

new ObjectID('66e0a5487c880f844c0a32b1'),

new ObjectId('66e0a5487c880f844c0a32b1'),

jmikola · 2024-09-16T15:37:30Z

source/includes/write/gridfs.php

+
+// Renames a file from the GridFS bucket with the specified ObjectID
+// start-rename-files
+$bucket->rename(new ObjectID('66e0a5487c880f844c0a32b1'), 'new_file_name');


Suggested change

$bucket->rename(new ObjectID('66e0a5487c880f844c0a32b1'), 'new_file_name');

$bucket->rename(new ObjectId('66e0a5487c880f844c0a32b1'), 'new_file_name');

jmikola · 2024-09-16T15:37:38Z

source/includes/write/gridfs.php

+
+// Deletes a file from the GridFS bucket with the specified ObjectID
+// start-delete-files
+$bucket->delete(new ObjectID('66e0a5487c880f844c0a32b1'));


Suggested change

$bucket->delete(new ObjectID('66e0a5487c880f844c0a32b1'));

$bucket->delete(new ObjectId('66e0a5487c880f844c0a32b1'));

jmikola · 2024-09-16T15:38:13Z

source/includes/write/gridfs.php

+);
+// end-download-to-stream
+
+// Renames a file from the GridFS bucket with the specified ObjectID


Suggested change

// Renames a file from the GridFS bucket with the specified ObjectID

// Renames a file from the GridFS bucket with the specified ObjectId

Consistency with the server manual.

jmikola · 2024-09-16T15:38:19Z

source/includes/write/gridfs.php

+$bucket->rename(new ObjectID('66e0a5487c880f844c0a32b1'), 'new_file_name');
+// end-rename-files
+
+// Deletes a file from the GridFS bucket with the specified ObjectID


Suggested change

// Deletes a file from the GridFS bucket with the specified ObjectID

// Deletes a file from the GridFS bucket with the specified ObjectId

jmikola · 2024-09-16T15:38:58Z

source/write/gridfs.txt

+
+- Calls the ``fopen()`` method to open a file located at ``/path/to/output_file``
+  as a stream in binary write (``wb``) mode
+- Downloads a GridFS file that has an ``_id`` value of ``ObjectID('66e0a5487c880f844c0a32b1')``


Suggested change

- Downloads a GridFS file that has an ``_id`` value of ``ObjectID('66e0a5487c880f844c0a32b1')``

- Downloads a GridFS file that has an ``_id`` value of ``ObjectId('66e0a5487c880f844c0a32b1')``

…P-41972-gridfs

* Add PR template * Scaffolding * DOCSP-41953: Create a deployment (#93) * DOCSP-41953: Create a deployment * toc * add troubleshoot file * DOCSP-41954: Create a connection string (#99) * DOCSP-41954: Create a connection string * edits * spacing * DOCSP-42388: Next steps (#101) * DOCSP-41975: Retrieve data (#102) * DOCSP-41975: Retrieve data * fixes * quotes * code fix * JS feedback * JT feedback * code format * fix * JT feedback 2 * edit * DOCSP-41952: Download and Install (#92) * DOCSP-41952: Download and Install * edits * toc, fixes * AS feedback * AS feedback 2 * typo * JT feedback * DOCSP-41976: Projection guide (#104) * DOCSP-41976: Projection guide * edits * fixes * code edits, output * JS feedback * JT feedback * DOCSP-41955: Connect to MongoDB (#100) * DOCSP-41955: Connect to MongoDB * edits * edit * RR feedback * typo * code edit * DOCSP-41974: Specify a query (#103) * DOCSP-41974: Specify a query * edits * output * fix * snooty.toml * RR feedback * code edits * DOCSP-41977: Specify documents to return (#105) * DOCSP-41977: Specify documents to return * edits * code output * toc * MM feedback, code edits * edit * JT feedback * edit * test * MM feedback 2 * DOCSP-41957 - Mongo Client (#106) Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> * DOCSP-41960 - TLS (#114) * DOCSP-41978: Count documents (#108) * DOCSP-41978: Count documents * edits * code ex format * link * RR feedback * DOCSP-41979: Distinct values (#109) Adds a Distinct Values guide. * DOCSP-41981: Change streams (#113) Adds a Change Streams guide. * DOCSP-41993 Compatibility Table * test webhook * toc and sharedincludes * lang table * edits * headings * retry on shared include * shared includes * callout * help links * DOCSP-41958 - Connection Targets (#107) Co-authored-by: Nora Reidy <nora.reidy@mongodb.com> Co-authored-by: Andreas Braun <git@alcaeus.org> * tech review * DOCSP-41968: Update documents (#118) * DOCSP-41968: Update documents * snooty fix * edits * DOCSP-41967: Insert documents (#116) * DOCSP-41967: Insert documents * build * snooty * edit * JS feedback * JT feedback * JT feedback 2 * DOCSP-41980: Cursor guide (#110) * DOCSP-41980: Cursor guide * edits * code edits * output * vale fix * MM feedback * edit * fix code ex * edit * JT feedback * DOCSP-41988: Aggregation (#115) * DOCSP-41988: Aggregation * toc * edits * code edit * JS feedback * dev center * JM feedback * explain api link * JM feedback 2 * DOCSP-41983: indexes landing pg * wip * wip * MM PR fixes 1 * JM tech review 1 * JM tech review 1 * wip * wip * DOCSP-41969: Replace documents (#125) * DOCSP-41969: Replace documents * edits * wording * SA * JT feedback * JM tech review 2 * Add files via upload * DOCSP-41970: Delete documents (#128) Adds a guide that shows how to delete documents. * DOCSP-41984: single field index * wip * JS PR fixes 1 * wip * DOCSP-41986: multikey indexes * links * bullet pts * JS suggestion * fix whitespace per JM comment * uncomment * DOCSP-41985: compound idx * small fix * DOCSP-41966: Write operations landing (#135) * DOCSP-41966: Write operations landing * edits * RR feedback * JT feedback * JT feedback 2 * gridfs examples * DOCSP-42026: In use encryption (#142) * DOCSP-42026: In use encryption * edit * DOCSP-41972: GridFS guide (#133) * DOCSP-41972: GridFS guide * fixes * code edits * fix * RR feedback * phpmethod * fix * JM most feedback * alternate upload/download methods * file revisions * code fix * tojson * edits * JM feedback 2 * edits * JM last feedback * DOCSP-41971: Bulk write (#130) * DOCSP-41971: Bulk write * edits * JS feedback * api links * DOCSP-41987: atlas search idx * resolve todos * toc * DOCSP-41963: Databases and collections (#136) * DOCSP-41963: Databases and collections * edits * phpmethod * code fix * MW feedback * fix * MW feedback 2 * JM feedback * JM feedback 2 * JS fix * internal review * DOCSP-41982: cluster monitoring * small fixes * MW PR fixes 1 * test netlify * spacing * try using out of repo ref and add back legend * ou of repo ref * legend glitch * JM tech review 1 * single quotes * links * vale * remove older driver version past 1.15 * DOCSP-41991 What's New * add rest of versions * fix links * fix links * JM tech review 2 * DOCSP-41964: Time series collections (#138) * DOCSP-41964: Time series collections * toc * edits * keywords * SA feedback * JT feedback * JM final fixes * review comments * typo * DOCSP-41973 Read Landing Page * review comments * vale errors * small thing * full page with ex * add page * meta * DOCSP-41965: Read and write settings (#146) * DOCSP-41965: Read and write settings * more info * edits * edits * headers * fix link * fix * RR feedback * api docs * fix * fix * DOCSP-41950: Landing page (#150) * DOCSP-41950: Landing page * fix build errors * fixes, data formats * toc * fix * data formats folder * RR feedback * fix * remove file * edit sample app intro * change links in count sections * update sample app intro * DOCSP-41990: Authentication mechanisms (#139) * DOCSP-41990: Authentication mechanisms * client tabs * edits * edits * add info * reduce repetition * add section * fix link * MW feedback * fix * JM most feedback * move to code file * more JM edits * JM feedback 2 * DOCSP-41989: Security landing page (#149) * DOCSP-41989: Security landing page * more info * edits * snooty.toml * edits * RR feedback * JM feedback * DOCSP-41962 - Stable API (#117) Co-authored-by: Jeremy Mikola <jmikola@gmail.com> * DOCSP-41992 Upgrade versions * toc * edits * how to upgrade sections * style * edit * edit * review comments * ref * Revise descriptions for server opening/closed events * DOCSP-43204: Connection landing page (#147) * DOCSP-43204: Connection landing page * toc edit * edits * remove compression * fix * sample app * snooty * JM feedback * replica set * JM feedback 2 * JM last feedback * DOCSP-43819: php 1.20 release * fix * DOCSP-41956: run a command * wip * formatting fix * JS PR fixes 1 * link fix * style fixes * JT tech review 1 * wip * JM tech review * tree * api links * links * JM tech review 2 * small fixes * add ext upgrade command * DOCSP-41995: transaction * wip * update code * NR PR fixes 1 * wip * add emphasis * add with_txn() method to api links * cxn string env * edit * JM tech review 1 * remove dupe sc * tech review * wrap fix * edit copy * DOCSP-41959 - Connection Options (#112) Co-authored-by: Nora Reidy <nora.reidy@mongodb.com> Co-authored-by: Jeremy Mikola <jmikola@gmail.com> * DOCSP-43396: Cleanup (#151) * DOCSP-43396: Cleanup * quickstart fix * code fixes * edit * snooty * edit * code output * build log errors * another build fix * add info * upgrade guide to landing * fix * driver mentions * RR feedback * build fix * build fix * php directives --------- Co-authored-by: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Co-authored-by: Rea Rustagi <85902999+rustagir@users.noreply.github.com> Co-authored-by: Lindsey Moore <lindsey.moore@mongodb.com> Co-authored-by: Andreas Braun <git@alcaeus.org> Co-authored-by: rustagir <rea.rustagi@mongodb.com> Co-authored-by: Brandon Ly <brandonly@lostcoding.com> Co-authored-by: lindseymoore <71525840+lindseymoore@users.noreply.github.com> Co-authored-by: Jeremy Mikola <jmikola@gmail.com>

DOCSP-41972: GridFS guide

f2a1dff

norareidy added 3 commits September 10, 2024 15:38

fixes

65e67fb

code edits

f709846

fix

fb135d1

rustagir self-requested a review September 10, 2024 20:49

rustagir approved these changes Sep 11, 2024

View reviewed changes

norareidy added 2 commits September 11, 2024 13:55

RR feedback

1389902

phpmethod

5a40fcb

norareidy requested review from a team and jmikola and removed request for a team September 11, 2024 18:01

fix

8ed2975

jmikola reviewed Sep 12, 2024

View reviewed changes

norareidy added 5 commits September 13, 2024 11:47

JM most feedback

c590514

alternate upload/download methods

5a8cd80

file revisions

7ccbe17

code fix

279a5a5

tojson

3e7d5e0

jmikola reviewed Sep 13, 2024

View reviewed changes

norareidy added 3 commits September 13, 2024 14:28

edits

6d401a0

JM feedback 2

34a6abf

edits

af8020c

norareidy requested a review from jmikola September 13, 2024 19:25

jmikola approved these changes Sep 16, 2024

View reviewed changes

jmikola reviewed Sep 16, 2024

View reviewed changes

norareidy added 2 commits September 16, 2024 14:52

JM last feedback

e1f1190

Merge remote-tracking branch 'upstream/php-standardization' into DOCS…

706a25f

…P-41972-gridfs

norareidy merged commit df79843 into mongodb:php-standardization Sep 16, 2024
5 of 6 checks passed

norareidy deleted the DOCSP-41972-gridfs branch September 16, 2024 19:01

	the files when uploaded to a bucket.
	the files when uploaded to a bucket:

	When storing files with GridFS, the library splits the files into smaller
	When using GridFS to store files, the library splits the files into smaller

	$stream = $bucket->openDownloadStream(new ObjectID('66e0a5487c880f844c0a32b1'));
	$stream = $bucket->openDownloadStream(new ObjectId('66e0a5487c880f844c0a32b1'));

	new ObjectID('66e0a5487c880f844c0a32b1'),
	new ObjectId('66e0a5487c880f844c0a32b1'),

	$bucket->rename(new ObjectID('66e0a5487c880f844c0a32b1'), 'new_file_name');
	$bucket->rename(new ObjectId('66e0a5487c880f844c0a32b1'), 'new_file_name');

	$bucket->delete(new ObjectID('66e0a5487c880f844c0a32b1'));
	$bucket->delete(new ObjectId('66e0a5487c880f844c0a32b1'));

	// Renames a file from the GridFS bucket with the specified ObjectID
	// Renames a file from the GridFS bucket with the specified ObjectId

	// Deletes a file from the GridFS bucket with the specified ObjectID
	// Deletes a file from the GridFS bucket with the specified ObjectId

	- Downloads a GridFS file that has an ``_id`` value of ``ObjectID('66e0a5487c880f844c0a32b1')``
	- Downloads a GridFS file that has an ``_id`` value of ``ObjectId('66e0a5487c880f844c0a32b1')``

DOCSP-41972: GridFS guide #133

DOCSP-41972: GridFS guide #133

Uh oh!

Conversation

norareidy commented Sep 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

netlify bot commented Sep 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-php-library ready!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmikola left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmikola left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jmikola Sep 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jmikola left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

norareidy commented Sep 10, 2024 •

edited

Loading

netlify bot commented Sep 10, 2024 •

edited

Loading

jmikola Sep 16, 2024 •

edited

Loading