Merge pull request #1795 from GromNaN/gridfs-docs

Add docs for GridFS adapter

_data/menu_v2.yml

@@ -26,6 +26,7 @@ Official Adapters:
     AsyncAws S3: '/docs/adapter/async-aws-s3/'
     Azure Blob Storage: '/docs/adapter/azure-blob-storage/'
     Google Cloud Storage: '/docs/adapter/google-cloud-storage/'
+    MongoDB GridFS: '/docs/adapter/gridfs/'
     SFTP (V2): '/docs/adapter/sftp-v2/'
     SFTP (V3): '/docs/adapter/sftp-v3/'
     WebDAV: '/docs/adapter/webdav/'

docs/adapter/gridfs.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: MongoDB GridFS Adapter
+permalink: /docs/adapter/gridfs/
+redirect_from: /v2/docs/adapter/gridfs/
+---
+
+## Installation
+
+```bash
+composer require league/flysystem-gridfs:^3.0
+```
+
+## About
+
+Interacting with MongoDB GridFS through Flysystem can be done
+by using the `League\Flysystem\GridFS\GridFSAdapter`.
+
+Read more about the MongoDB PHP Library in the [official documentation](https://www.mongodb.com/docs/php-library/).
+
+## Simple usage:
+
+```php
+$client = new MongoDB\Client('mongodb://localhost:27017/');
+
+// The internal adapter
+$adapter = new League\Flysystem\GridFS\GridFSAdapter(
+    // GridFS Bucket
+    $client->selectDatabase('flysystem')->selectGridFSBucket()
+);
+
+// The FilesystemOperator
+$filesystem = new League\Flysystem\Filesystem($adapter);
+```
+
+## Advanced usage:
+
+```php
+$client = new MongoDB\Client('mongodb://localhost:27017/');
+
+// The internal adapter
+$adapter = new League\Flysystem\GridFS\GridFSAdapter(
+    // GridFS Bucket
+    $client->selectDatabase('flysystem')->selectGridFSBucket([
+        // Bucket name in the MongoDB database
+        'bucketName' => 'project_files'
+    ])
+    // Optional path prefix
+    'path/prefix',
+);
+
+// The FilesystemOperator
+$filesystem = new League\Flysystem\Filesystem($adapter);
+```
+
+## Versioning:
+
+In GridFS, file names are metadata to file objects identified by unique MongoDB `ObjectID`.
+There may be more than one file with the same name, they are called "revisions":
+- Reading a file reads the last revision of this file name
+- Writing to a file name creates a new revision for this file name
+- Renaming a file renames all the revisions of this file name
+- Deleting a file deletes all the revisions of this file name
+
+The GridFS Adapter for Flysystem does not provide access to a specific revision of a filename,
+you must use the [GridFS API](https://www.mongodb.com/docs/php-library/current/tutorial/gridfs/)
+if you need to work with revisions.

docs/index.md

@@ -40,6 +40,7 @@ for which ever storage is right for you.
 * **[AsyncAws S3](/docs/adapter/async-aws-s3/)**
 * **[Google Cloud Storage](/docs/adapter/google-cloud-storage/)**
 * **[Azure Blob Storage](/docs/adapter/azure-blob-storage/)**
+* **[MongoDB GridFS](/docs/adapter/mongodb-gridfs/)**
 * **[WebDAV](/docs/adapter/webdav/)**
 
 ### Third party Adapters