Laravel MongoDB GridFS

A library wants to help the use of GridFS of MongoDB for Laravel 5. This library extends the original MongoDB GridFS Bucket for PHP, so many methods are exactly the same and others are simplified for the use.

Note

This is not a library for Eloquent or somenthing like this. It's a simple helper to easly use GridFS in Laravel. If you are looking for an Eloquent Model for MongoDB I suggest you jenssegers/laravel-mongodb.

Table of contents

• Installation
• Configuration
• Usage
  • Bucket Prefix
  • Storing File
  • Get File
  • Helpers
• Contact
• License

Installation

Laravel version Compatibility

Laravel	Package
< 5.5.x	1.1.x (not tested)
>= 5.5.x	1.1.x

Requirements

Make sure you have the MongoDB PHP driver installed. You can find installation instructions at http://php.net/manual/en/mongodb.installation.php

Installation

1. Installation using composer:

composer require mts88/mongogrid

2. And add the service provider in config/app.php:

Mts88\MongoGrid\Providers\MongoGridServiceProvider,

4. You may also register an alias for the MongoGrid library by adding the following to the alias array in config/app.php:

'MongoGrid'       => Mts88\MongoGrid\Facades\MongoGrid,

Configuration

Run the command below to publish the package config file config/gridfs.php:

php artisan vendor:publish

MongoDB Connection

You can use build-in configuration in config/gridfs.php or you can use config/database.php (compatible with jenssegers/laravel-mongodb).

Connection with config/gridfs.php

In config file config/gridfs.php set up your configuration in order to connect to MongoDB:

Simple Connection

    'db_config' => [
        'host'     => env('DB_HOST', 'localhost'),
        'port'     => env('DB_PORT', 27017),
        'database' => env('DB_DATABASE'),
        'username' => env('DB_USERNAME'),
        'password' => env('DB_PASSWORD'),
        'options'  => [
            'database' => 'admin' // sets the authentication database required by mongo 3
        ]
    ],

ReplicaSet Connection

In your .env file add DB_REPLICA_SET property with the name of Replica Set

    'db_config' => [
        'host'     => [
            [
                'address' => 'server1',
                'port'=> 27017
            ],
            [
                'address' => 'server2',
                'port' => 27017
            ],
        ],
        'database' => env('DB_DATABASE'),
        'username' => env('DB_USERNAME'),
        'password' => env('DB_PASSWORD'),
        'options'  => [
            'replicaSet' => env('DB_REPLICA_SET'),
            'database' => 'admin' // sets the authentication database required by mongo 3
        ]
    ],

Connection with config/database.php

In config file config/gridfs.php set up your configuration name:

'db_config' => env('DB_CONNECTION', 'mongodb'),

In config file config/database.php set up your configuration in order to connect to MongoDB: And add a new mongodb connection:

Simple Connection

'mongodb' => [
    'driver'   => 'mongodb',
    'host'     => env('DB_HOST', 'localhost'),
    'port'     => env('DB_PORT', 27017),
    'database' => env('DB_DATABASE'),
    'username' => env('DB_USERNAME'),
    'password' => env('DB_PASSWORD'),
    'options'  => [
        'database' => 'admin' // sets the authentication database required by mongo 3
    ]
],

ReplicaSet Connection

You can connect to multiple servers or replica sets with the following configuration:

'mongodb' => [
    'driver'   => 'mongodb',
    'host'     => ['server1', 'server2'],
    'port'     => env('DB_PORT', 27017),
    'database' => env('DB_DATABASE'),
    'username' => env('DB_USERNAME'),
    'password' => env('DB_PASSWORD'),
    'options'  => [
		'replicaSet' => 'replicaSetName'
	]
],

DSN URL

Alternatively, you can use MongoDB connection string:

'mongodb' => [
    'driver'   => 'mongodb',
    'dsn' => env('DB_DSN'),
    'database' => env('DB_DATABASE'),
],

Please refer to MongoDB official docs for its URI format: https://docs.mongodb.com/manual/reference/connection-string/

Bucket Configuration

This is the config for GridFS Bucket:

    'bucket'    =>  [
        'prefix'            =>  'fs',
        'chunkSizeBytes'    =>  261120,
        'readPreference'    =>  'primaryPreferred',
        'readConcern'       =>  'available',
    ],

For more details see MongoDB GridFS Bucket.

Metadata

By default the library adds these metadata to each document:

• uuid;
• created_at;
• updated_at;
• downloads;

set false in config/gridfs.php file to not include this info.

    'add_meta'      =>  false,

Temporary Storage

By default the library use local driver for storing file into MongoDB. You can change the default driver of the Storage:

    'storage'       =>  'local',

To learn more see Laravel File Storage.

Usage

Bucket Prefix

By default MongoGrid use the prefix in config/gridfs.php, but if you want you can use another custom prefix on the fly:

MongoGrid::prefix('myNewPrefix')->someCoolMethod();

Storing File

storeFile( $fileContent, $fileName, [ optional $metadata] )

Store a file using contents, file name and your metadata (optional). Returns ObjectId

$fileName = 'differentName.jpg';
$fileContent = Storage::disk('local')->get('star-wars-logo.jpg');
$objectId = MongoGrid::storeFile($fileContent, $fileName);

// Or with your custom metadata

$fileName = 'differentName.jpg';
$fileContent = Storage::disk('local')->get('star-wars-logo.jpg');
$metadata = array(
	'father'	=>	'Anakin',
	'son'		=>	'Luke'
	);
$objectId = MongoGrid::storeFile($fileContent, $fileName, $metadata);

Or using another prefix

$fileName = 'differentName.jpg';
$fileContent = Storage::disk('local')->get('star-wars-logo.jpg');
$objectId = MongoGrid::prefix('starWars')->storeFile($fileContent, $fileName);

// Or with your custom metadata

$fileName = 'differentName.jpg';
$fileContent = Storage::disk('local')->get('star-wars-logo.jpg');
$metadata = array(
	'father'	=>	'Anakin',
	'son'		=>	'Luke'
	);
$objectId = MongoGrid::prefix('starWars')->storeFile($fileContent, $fileName, $metadata);

Get File

All method to get files from GridFS. Revision numbers are defined as follows:

• 0 = the original stored file
• 1 = the first revision
• 2 = the second revision
• etc…
• -2 = the second most recent revision
• -1 = the most recent revision

Defaults to -1 (i.e. the most recent revision). Revision works only on method by filename.

getFileContent( $source, [optional $revision] )

You can retrive the content of file by his name or his ObjectId. You can use also the revision of the file.

$fileName = 'star-wars-logo.jpg';
$content = MongoGrid::getFileContent($fileName, '-1');

// Or by ObjectId

$objectId = new \MongoDB\BSON\ObjectId;
$content = MongoGrid::getFileContent($objectId);

getFile( $source )

You can retrive the content of file by his name or his ObjectId. Returns a document of the file collection.

$fileName = 'star-wars-logo.jpg';
$document = MongoGrid::getFile($fileName);

// Or by ObjectId

$objectId = new \MongoDB\BSON\ObjectId;
$document = MongoGrid::getFile($objectId);

findOne( $query, [ optional $options ] )

Finds a single document from the selected GridFS bucket matching the query.

$objectId = new \MongoDB\BSON\ObjectId;
$document = MongoGrid::findOne([ '_id' => $objectId ]);

To learn more about $options see MongoDB GridFS findOne.

find( $query, [ optional $options ] )

Finds all documents from the selected GridFS bucket matching the query.

$objectId = new \MongoDB\BSON\ObjectId;
$document = MongoGrid::find([ '_id' => $objectId ]);

download( $source, string $path, [optional $revision] )

Download a file from GridFS to a given path

$objectId = new \MongoDB\BSON\ObjectId;
$path = 'your/awesome/path';
MongoGrid::download($objectId, $path);

//Or by filename

$fileName = 'star-wars-logo.jpg';
$path = 'your/awesome/path';
MongoGrid::download($fileName, $path, '-1');

NB: downloading a file with this method will increments downloads on metadata by itself (only if metadata are active).

Helpers

rename( $_id, $newName )

Rename a file.

$objectId = new \MongoDB\BSON\ObjectId;
$newName = 'star-wars-amazing-logo.jpg';
MongoGrid::rename($objectId, $newName);

delete( $_id )

Delete a file from the collection.

$objectId = new \MongoDB\BSON\ObjectId;
MongoGrid::delete($objectId);

getBucketName()

Return the Collection Chunks of the selected GridFS Bucket

$bucketName = MongoGrid::getBucketName();

getChunksCollection()

Returns the name of the selected GridFS Bucket

$collection = MongoGrid::getChunksCollection();

getChunkSizeBytes()

Return the size of Chunks of the selected GridFS Bucket

$size = MongoGrid::getChunkSizeBytes();

getDatabaseName()

Return the name of the database used for selected GridFS

$databaseName = MongoGrid::getDatabaseName();

getFilesCollection()

Return the Collection File of the selected GridFS Bucket

$collection = MongoGrid::getFilesCollection();

drop()

Drop entire collections of a selected GridFS

MongoGrid::drop();

Contact

Open an issue on GitHub if you have any problems or suggestions.

License

The contents of this repository is released under the MIT license.