{"id":23905533,"url":"https://github.com/mts88/mongogrid","last_synced_at":"2025-04-11T03:21:15.181Z","repository":{"id":55113794,"uuid":"135331398","full_name":"mts88/mongogrid","owner":"mts88","description":"Useful package to easly use Mongo GridFS in Laravel","archived":false,"fork":false,"pushed_at":"2021-01-09T09:53:22.000Z","size":190,"stargazers_count":7,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-25T22:40:20.032Z","etag":null,"topics":["bucket","database","document","file","grid","gridfs","gridfs-bucket","laravel","laravel-mongodb","metadata","mongo","mongodb","mongogrid","selected-gridfs","storage"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mts88.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-29T17:36:17.000Z","updated_at":"2023-11-29T18:52:16.000Z","dependencies_parsed_at":"2022-08-14T12:20:55.437Z","dependency_job_id":null,"html_url":"https://github.com/mts88/mongogrid","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mts88%2Fmongogrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mts88%2Fmongogrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mts88%2Fmongogrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mts88%2Fmongogrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mts88","download_url":"https://codeload.github.com/mts88/mongogrid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248334098,"owners_count":21086314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bucket","database","document","file","grid","gridfs","gridfs-bucket","laravel","laravel-mongodb","metadata","mongo","mongodb","mongogrid","selected-gridfs","storage"],"created_at":"2025-01-05T01:14:49.273Z","updated_at":"2025-04-11T03:21:15.102Z","avatar_url":"https://github.com/mts88.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Laravel MongoDB GridFS\n\n[![Latest Stable Version](https://poser.pugx.org/mts88/mongogrid/v/stable)](https://packagist.org/packages/mts88/mongogrid)\n[![Total Downloads](https://poser.pugx.org/mts88/mongogrid/downloads)](https://packagist.org/packages/mts88/mongogrid)\n[![License](https://poser.pugx.org/mts88/mongogrid/license)](https://packagist.org/packages/mts88/mongogrid)\n\nA library wants to help the use of GridFS of MongoDB for Laravel 5. _This library extends the original [MongoDB GridFS Bucket for PHP](https://docs.mongodb.com/php-library/current/reference/class/MongoDBGridFSBucket/), so many methods are exactly the same and others are simplified for the use._\n\n#### Note\nThis 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](https://github.com/jenssegers/laravel-mongodb).\n\n# Table of contents\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Usage](#usage)\n\t* [Bucket Prefix](#bucket-prefix)\n\t* [Storing File](#storing-file)\n\t* [Get File](#get-file)\n\t* [Helpers](#helpers)\n* [Contact](#contact)\n* [License](#license)\n# Installation\n\n### Laravel version Compatibility\n\n| Laravel | Package |\n|--|--|\n| \u003c 5.5.x | 1.1.x (not tested) |\n| \u003e= 5.5.x | 1.1.x |\n\n### Requirements\nMake sure you have the MongoDB PHP driver installed. You can find installation instructions at [http://php.net/manual/en/mongodb.installation.php](http://php.net/manual/en/mongodb.installation.php)\n### Installation\n1. Installation using composer:\n```\ncomposer require mts88/mongogrid\n```\n2. And add the service provider in  `config/app.php`:\n```php\nMts88\\MongoGrid\\Providers\\MongoGridServiceProvider,\n```\n4. You may also register an alias for the MongoGrid library by adding the following to the alias array in  `config/app.php`:\n```php\n'MongoGrid'       =\u003e Mts88\\MongoGrid\\Facades\\MongoGrid,\n```\n## Configuration\n\nRun the command below to publish the package config file  `config/gridfs.php`:\n```php\nphp artisan vendor:publish\n```\n### MongoDB Connection\nYou can use build-in configuration in `config/gridfs.php` or you can use `config/database.php` (compatible with [jenssegers/laravel-mongodb](https://github.com/jenssegers/laravel-mongodb)).\n\n#### Connection with config/gridfs.php\n\nIn config file `config/gridfs.php` set up your configuration in order to connect to MongoDB:\n##### Simple Connection\n```php\n    'db_config' =\u003e [\n        'host'     =\u003e env('DB_HOST', 'localhost'),\n        'port'     =\u003e env('DB_PORT', 27017),\n        'database' =\u003e env('DB_DATABASE'),\n        'username' =\u003e env('DB_USERNAME'),\n        'password' =\u003e env('DB_PASSWORD'),\n        'options'  =\u003e [\n            'database' =\u003e 'admin' // sets the authentication database required by mongo 3\n        ]\n    ],\n```\n##### ReplicaSet Connection\nIn your `.env` file add `DB_REPLICA_SET` property with the name of Replica Set\n```php\n    'db_config' =\u003e [\n        'host'     =\u003e [\n            [\n                'address' =\u003e 'server1',\n                'port'=\u003e 27017\n            ],\n            [\n                'address' =\u003e 'server2',\n                'port' =\u003e 27017\n            ],\n        ],\n        'database' =\u003e env('DB_DATABASE'),\n        'username' =\u003e env('DB_USERNAME'),\n        'password' =\u003e env('DB_PASSWORD'),\n        'options'  =\u003e [\n            'replicaSet' =\u003e env('DB_REPLICA_SET'),\n            'database' =\u003e 'admin' // sets the authentication database required by mongo 3\n        ]\n    ],\n```\n#### Connection with config/database.php\n\nIn config file `config/gridfs.php` set up your configuration name:\n```php\n'db_config' =\u003e env('DB_CONNECTION', 'mongodb'),\n```\n\nIn config file `config/database.php` set up your configuration in order to connect to MongoDB:\nAnd add a new mongodb connection:\n\n##### Simple Connection\n```php\n'mongodb' =\u003e [\n    'driver'   =\u003e 'mongodb',\n    'host'     =\u003e env('DB_HOST', 'localhost'),\n    'port'     =\u003e env('DB_PORT', 27017),\n    'database' =\u003e env('DB_DATABASE'),\n    'username' =\u003e env('DB_USERNAME'),\n    'password' =\u003e env('DB_PASSWORD'),\n    'options'  =\u003e [\n        'database' =\u003e 'admin' // sets the authentication database required by mongo 3\n    ]\n],\n```\n##### ReplicaSet Connection\nYou can connect to multiple servers or replica sets with the following configuration:\n\n```php\n'mongodb' =\u003e [\n    'driver'   =\u003e 'mongodb',\n    'host'     =\u003e ['server1', 'server2'],\n    'port'     =\u003e env('DB_PORT', 27017),\n    'database' =\u003e env('DB_DATABASE'),\n    'username' =\u003e env('DB_USERNAME'),\n    'password' =\u003e env('DB_PASSWORD'),\n    'options'  =\u003e [\n\t\t'replicaSet' =\u003e 'replicaSetName'\n\t]\n],\n```\n##### DSN URL\nAlternatively, you can use MongoDB connection string:\n\n```php\n'mongodb' =\u003e [\n    'driver'   =\u003e 'mongodb',\n    'dsn' =\u003e env('DB_DSN'),\n    'database' =\u003e env('DB_DATABASE'),\n],\n```\n\nPlease refer to MongoDB official docs for its URI format: https://docs.mongodb.com/manual/reference/connection-string/\n\n#### Bucket Configuration\nThis is the config for GridFS Bucket:\n```php\n    'bucket'    =\u003e  [\n        'prefix'            =\u003e  'fs',\n        'chunkSizeBytes'    =\u003e  261120,\n        'readPreference'    =\u003e  'primaryPreferred',\n        'readConcern'       =\u003e  'available',\n    ],\n```\nFor more details see [MongoDB GridFS Bucket](https://docs.mongodb.com/php-library/current/reference/method/MongoDBGridFSBucket__construct/).\n#### Metadata\nBy default the library adds these metadata to each document:\n - uuid;\n - created_at;\n - updated_at;\n - downloads;\n\nset `false` in `config/gridfs.php` file to not include this info.\n```php\n    'add_meta'      =\u003e  false,\n```\n#### Temporary Storage\nBy default the library use `local` driver for storing file into MongoDB. You can change the default driver of the `Storage`:\n```php\n    'storage'       =\u003e  'local',\n```\nTo learn more see [Laravel File Storage](https://laravel.com/docs/5.6/filesystem).\n## Usage\n### Bucket Prefix\nBy default MongoGrid use the prefix in `config/gridfs.php`, but if you want you can use another custom prefix on the fly:\n```php\nMongoGrid::prefix('myNewPrefix')-\u003esomeCoolMethod();\n```\n### Storing File\n#### storeFile( $fileContent, $fileName, [ optional $metadata] )\nStore a file using contents, file name and your metadata (optional). Returns ObjectId\n```php\n$fileName = 'differentName.jpg';\n$fileContent = Storage::disk('local')-\u003eget('star-wars-logo.jpg');\n$objectId = MongoGrid::storeFile($fileContent, $fileName);\n\n// Or with your custom metadata\n\n$fileName = 'differentName.jpg';\n$fileContent = Storage::disk('local')-\u003eget('star-wars-logo.jpg');\n$metadata = array(\n\t'father'\t=\u003e\t'Anakin',\n\t'son'\t\t=\u003e\t'Luke'\n\t);\n$objectId = MongoGrid::storeFile($fileContent, $fileName, $metadata);\n```\n*Or using another prefix*\n```php\n$fileName = 'differentName.jpg';\n$fileContent = Storage::disk('local')-\u003eget('star-wars-logo.jpg');\n$objectId = MongoGrid::prefix('starWars')-\u003estoreFile($fileContent, $fileName);\n\n// Or with your custom metadata\n\n$fileName = 'differentName.jpg';\n$fileContent = Storage::disk('local')-\u003eget('star-wars-logo.jpg');\n$metadata = array(\n\t'father'\t=\u003e\t'Anakin',\n\t'son'\t\t=\u003e\t'Luke'\n\t);\n$objectId = MongoGrid::prefix('starWars')-\u003estoreFile($fileContent, $fileName, $metadata);\n```\n### Get File\nAll method to get files from GridFS. **Revision** numbers are defined as follows:\n-   0 = the original stored file\n-   1 = the first revision\n-   2 = the second revision\n-   etc…\n-   -2 = the second most recent revision\n-   -1 = the most recent revision\n\n\u003e Defaults to -1 (i.e. the most recent revision). Revision works only on method by filename.\n#### getFileContent(  $source, [optional $revision] )\nYou can retrive the content of file by his name or his ObjectId. You can use also the revision of the file.\n```php\n$fileName = 'star-wars-logo.jpg';\n$content = MongoGrid::getFileContent($fileName, '-1');\n\n// Or by ObjectId\n\n$objectId = new \\MongoDB\\BSON\\ObjectId;\n$content = MongoGrid::getFileContent($objectId);\n```\n#### getFile( $source )\nYou can retrive the content of file by his name or his ObjectId. Returns a document of the file collection.\n```php\n$fileName = 'star-wars-logo.jpg';\n$document = MongoGrid::getFile($fileName);\n\n// Or by ObjectId\n\n$objectId = new \\MongoDB\\BSON\\ObjectId;\n$document = MongoGrid::getFile($objectId);\n```\n#### findOne( $query, [ optional $options ] )\nFinds a single document from the selected GridFS bucket matching the query.\n```php\n$objectId = new \\MongoDB\\BSON\\ObjectId;\n$document = MongoGrid::findOne([ '_id' =\u003e $objectId ]);\n```\nTo learn more about `$options` see [MongoDB GridFS findOne](https://docs.mongodb.com/php-library/current/reference/method/MongoDBGridFSBucket-findOne/).\n#### find( $query, [ optional $options ] )\nFinds all documents from the selected GridFS bucket matching the query.\n```php\n$objectId = new \\MongoDB\\BSON\\ObjectId;\n$document = MongoGrid::find([ '_id' =\u003e $objectId ]);\n```\n#### download( $source, string $path, [optional $revision] )\nDownload a file from GridFS to a given path\n```php\n$objectId = new \\MongoDB\\BSON\\ObjectId;\n$path = 'your/awesome/path';\nMongoGrid::download($objectId, $path);\n\n//Or by filename\n\n$fileName = 'star-wars-logo.jpg';\n$path = 'your/awesome/path';\nMongoGrid::download($fileName, $path, '-1');\n```\n**NB:** downloading a file with this method will increments downloads on metadata by itself (only if metadata are active).\n### Helpers\n#### rename( $_id, $newName )\nRename a file.\n```php\n$objectId = new \\MongoDB\\BSON\\ObjectId;\n$newName = 'star-wars-amazing-logo.jpg';\nMongoGrid::rename($objectId, $newName);\n```\n#### delete( $_id )\nDelete a file from the collection.\n```php\n$objectId = new \\MongoDB\\BSON\\ObjectId;\nMongoGrid::delete($objectId);\n```\n#### getBucketName()\n Return the Collection Chunks of the selected GridFS Bucket\n```php\n$bucketName = MongoGrid::getBucketName();\n```\n#### getChunksCollection()\n Returns the name of the selected GridFS Bucket\n```php\n$collection = MongoGrid::getChunksCollection();\n```\n#### getChunkSizeBytes()\n Return the size of Chunks of the selected GridFS Bucket\n```php\n$size = MongoGrid::getChunkSizeBytes();\n```\n#### getDatabaseName()\nReturn the name of the database used for selected GridFS\n```php\n$databaseName = MongoGrid::getDatabaseName();\n```\n#### getFilesCollection()\n Return the Collection File of the selected GridFS Bucket\n```php\n$collection = MongoGrid::getFilesCollection();\n```\n#### drop()\n Drop entire collections of a selected GridFS\n```php\nMongoGrid::drop();\n```\n## Contact\nOpen an issue on GitHub if you have any problems or suggestions.\n## License\nThe contents of this repository is released under the  [MIT license](http://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmts88%2Fmongogrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmts88%2Fmongogrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmts88%2Fmongogrid/lists"}