helmich / gridfs
GridFS implementation for the MongoDB PHP extension
Fund package maintenance!
martin-helmich
donate.helmich.me
Installs: 11 545
Dependents: 0
Suggesters: 0
Security: 0
Stars: 8
Watchers: 4
Forks: 1
Open Issues: 1
Requires
- php: >=7.0.0
- ext-mongodb: *
- mongodb/mongodb: ^1.0
Requires (Dev)
- codeclimate/php-test-reporter: ^0.3.0
- helmich/mongomock: dev-master
- phpunit/phpunit: ^5.2
- psr/http-message: ^1.0
Suggests
- psr/http-message: provides adapter classes for mapping GridFS streams to PSR-7 streams
This package is auto-updated.
Last update: 2024-10-28 04:58:58 UTC
README
This package provides a userspace implementation of the GridFS specification for PHP's new mongodb
extension (not to be confused with the similarly named mongo
extension).
This library requires PHP 7!
Author and license
Martin Helmich
This library is MIT-licensed.
Installation
Use Composer:
$ composer require helmich/gridfs
Usage
Initialization
GridFS is oriented around Buckets. For a bucket named $name
, this library will create two collections $name.files
and $name.chunks
in which file metadata and content blocks will be stored. Create a new bucket by instantiating the Helmich\GridFS\Bucket
class. You will need a MongoDB\Database
instance as dependency and can optionally pass an instance of the Helmich\GridFS\Options\BucketOptions
class to configure your bucket:
$manager = new \MongoDB\Driver\Manager('mongodb://localhost:27017'); $database = new \MongoDB\Database($manager, 'yourdatabase'); $bucketOptions = (new \Helmich\GridFS\Options\BucketOptions) ->withBucketName('yourbucket'); $bucket = new \Helmich\GridFS\Bucket($database, $bucketOptions);
Uploading files into a bucket
Uploading of files is done via streams. You can open a new upload stream using the openUploadStream
function:
$uploadOptions = (new \Helmich\GridFS\Options\UploadOptions) ->withChunkSizeBytes(4 << 10) ->withMetadata(['foo' => 'bar']); $uploadStream = $bucket->openUploadStream("helloworld.txt", $uploadOptions); $uploadStream->write("Hello World!"); $uploadStream->close(); echo "File ID is: " . $uploadStream->fileId();
Alternatively, use the uploadFromStream
method, which takes a PHP stream as a parameter:
$fileStream = fopen('humungousfile.blob', 'r'); $fileId = $bucket->uploadFromStream('humungousfile.blob', $fileStream, $uploadOptions);
Finding uploaded files
Use the find
method to find files in your bucket. The find
method takes a MongoDB query object as first parameter that is applied to the $bucketName.files
collection. The second parameter is an instance of the Helmich\GridFS\Options\FindOptions
class in which you can specify advanced options for the search:
$options = (new \Helmich\GridFS\Options\FindOptions) ->withBatchSize(32) ->withLimit(128) ->withSkip(13) ->withSort(['filename' => 1]) ->withNoCursorTimeout(); $query = [ 'filename' => [ '$in': ['foo.txt', 'bar.txt'] ], 'uploadDate' => [ '$gt' => new \MongoDB\BSON\UTCDatetime(time() - 86400) ] ]; $files = $bucket->find($query, $options);
Downloading files from a bucket
Downloading files is also stream-oriented. Given the ID of an already existing file, open a new download stream using the openDownloadStream
function:
$file = $bucket->find(['filename' => 'foo.txt'], (new \Helmich\GridFS\Options\FindOptions)->withLimit(1))[0]; $downloadStream = $bucket->openDownloadStream($file['_id']); echo $downloadStream->readAll(); // alternatively: while (!$downloadStream->eof()) { echo $downloadStream->read(4096); }
Given an already existing (and writeable) PHP stream, you can also use the downloadToStream
method to pipe the file directly into the stream:
$fileStream = fopen('humungousfile.blob', 'w'); $bucket->downloadToStream($id, $fileStream);
There is also a byName
variant of both openDownloadStream
(openDownloadStreamByName()
) and downloadToStream
(downloadToStreamByName
). Both of these functions take a file name and a Helmich\GridFS\Options\DownloadOptions
instance as parameter. The $options
parameter allows you to specify which revision of the given filename should be downloaded:
$options = (new \Helmich\GridFS\Options\DownloadByNameOptions) ->withRevision(-1); // also the default; will download the latest revision of the file $stream = $bucket->openDownloadStreamByName('yourfile.txt', $options);
Deleting files
Delete files from the bucket using the delete
method:
$bucket->delete($fileId);
Gimmicks
PSR-7 adapters
I've implemented this package for a PSR-7 compliant web application. PSR-7 also heavily relies on streams, so I've found it useful to add an adapter class to map a Helmich\GridFS\Stream\DownloadStreamInterface
to a Psr\Http\Message\StreamInterface
. This is especially useful if you want to return GridFS files as a response body stream. The following example uses the Slim framework, but should be easily adaptable to other PSR-7 compliant frameworks:
$app->get( '/documents/{name}', function(RequestInterface $req, ResponseInterface $res, array $args) use ($bucket): ResponseInterface { $stream = $bucket->openDownloadStreamByName($args['name']); return $res ->withHeader('content-type', $stream->file()['metadata']['contenttype']) ->withBody(new \Helmich\GridFS\Stream\Psr7\DownloadStreamAdapter($stream)); } );