Documentation

Bucket
in package

Bucket provides a public API for interacting with the GridFS files and chunks collections.

Table of Contents

$bucketName  : string
$chunkSizeBytes  : int
$collectionWrapper  : CollectionWrapper
$databaseName  : string
$defaultBucketName  : string
$defaultChunkSizeBytes  : int
$defaultTypeMap  : array<string|int, mixed>
$disableMD5  : bool
$manager  : Manager
$readConcern  : ReadConcern
$readPreference  : ReadPreference
$streamWrapperProtocol  : string
$typeMap  : array<string|int, mixed>
$writeConcern  : WriteConcern
__construct()  : mixed
Constructs a GridFS bucket.
__debugInfo()  : array<string|int, mixed>
Return internal properties for debugging purposes.
delete()  : mixed
Delete a file from the GridFS bucket.
downloadToStream()  : mixed
Writes the contents of a GridFS file to a writable stream.
downloadToStreamByName()  : mixed
Writes the contents of a GridFS file, which is selected by name and revision, to a writable stream.
drop()  : mixed
Drops the files and chunks collections associated with this GridFS bucket.
find()  : Cursor
Finds documents from the GridFS bucket's files collection matching the query.
findOne()  : array<string|int, mixed>|object|null
Finds a single document from the GridFS bucket's files collection matching the query.
getBucketName()  : string
Return the bucket name.
getChunksCollection()  : Collection
Return the chunks collection.
getChunkSizeBytes()  : int
Return the chunk size in bytes.
getDatabaseName()  : string
Return the database name.
getFileDocumentForStream()  : array<string|int, mixed>|object
Gets the file document of the GridFS file associated with a stream.
getFileIdForStream()  : mixed
Gets the file document's ID of the GridFS file associated with a stream.
getFilesCollection()  : Collection
Return the files collection.
getReadConcern()  : ReadConcern
Return the read concern for this GridFS bucket.
getReadPreference()  : ReadPreference
Return the read preference for this GridFS bucket.
getTypeMap()  : array<string|int, mixed>
Return the type map for this GridFS bucket.
getWriteConcern()  : WriteConcern
Return the write concern for this GridFS bucket.
openDownloadStream()  : resource
Opens a readable stream for reading a GridFS file.
openDownloadStreamByName()  : resource
Opens a readable stream stream to read a GridFS file, which is selected by name and revision.
openUploadStream()  : resource
Opens a writable stream for writing a GridFS file.
rename()  : mixed
Renames the GridFS file with the specified ID.
uploadFromStream()  : mixed
Writes the contents of a readable stream to a GridFS file.
createPathForFile()  : string
Creates a path for an existing GridFS file.
createPathForUpload()  : string
Creates a path for a new GridFS file, which does not yet have an ID.
getFilesNamespace()  : string
Returns the names of the files collection.
getRawFileDocumentForStream()  : stdClass
Gets the file document of the GridFS file associated with a stream.
openDownloadStreamByFile()  : resource
Opens a readable stream for the GridFS file.
registerStreamWrapper()  : mixed
Registers the GridFS stream wrapper if it is not already registered.

Properties

$bucketName

private string $bucketName

$chunkSizeBytes

private int $chunkSizeBytes

$collectionWrapper

private CollectionWrapper $collectionWrapper

$databaseName

private string $databaseName

$defaultBucketName

private static string $defaultBucketName = 'fs'

$defaultChunkSizeBytes

private static int $defaultChunkSizeBytes = 261120

$defaultTypeMap

private static array<string|int, mixed> $defaultTypeMap = ['array' => \MongoDB\Model\BSONArray::class, 'document' => \MongoDB\Model\BSONDocument::class, 'root' => \MongoDB\Model\BSONDocument::class]

$disableMD5

private bool $disableMD5

$manager

private Manager $manager

$readConcern

private ReadConcern $readConcern

$readPreference

private ReadPreference $readPreference

$streamWrapperProtocol

private static string $streamWrapperProtocol = 'gridfs'

$typeMap

private array<string|int, mixed> $typeMap

$writeConcern

private WriteConcern $writeConcern

Methods

__construct()

Constructs a GridFS bucket.

public __construct(Manager $manager, string $databaseName[, array<string|int, mixed> $options = [] ]) : mixed

Supported options:

  • bucketName (string): The bucket name, which will be used as a prefix for the files and chunks collections. Defaults to "fs".

  • chunkSizeBytes (integer): The chunk size in bytes. Defaults to 261120 (i.e. 255 KiB).

  • disableMD5 (boolean): When true, no MD5 sum will be generated for each stored file. Defaults to "false".

  • readConcern (MongoDB\Driver\ReadConcern): Read concern.

  • readPreference (MongoDB\Driver\ReadPreference): Read preference.

  • typeMap (array): Default type map for cursors and BSON documents.

  • writeConcern (MongoDB\Driver\WriteConcern): Write concern.

Parameters
$manager : Manager

Manager instance from the driver

$databaseName : string

Database name

$options : array<string|int, mixed> = []

Bucket options

Tags
throws
InvalidArgumentException

for parameter/option parsing errors

Return values
mixed —

delete()

Delete a file from the GridFS bucket.

public delete(mixed $id) : mixed

If the files collection document is not found, this method will still attempt to delete orphaned chunks.

Parameters
$id : mixed

File ID

Tags
throws
FileNotFoundException

if no file could be selected

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

downloadToStream()

Writes the contents of a GridFS file to a writable stream.

public downloadToStream(mixed $id, resource $destination) : mixed
Parameters
$id : mixed

File ID

$destination : resource

Writable Stream

Tags
throws
FileNotFoundException

if no file could be selected

throws
InvalidArgumentException

if $destination is not a stream

throws
StreamException

if the file could not be uploaded

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

downloadToStreamByName()

Writes the contents of a GridFS file, which is selected by name and revision, to a writable stream.

public downloadToStreamByName(string $filename, resource $destination[, array<string|int, mixed> $options = [] ]) : mixed

Supported options:

  • revision (integer): Which revision (i.e. documents with the same filename and different uploadDate) of the file to retrieve. Defaults to -1 (i.e. the most recent revision).

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
Parameters
$filename : string

Filename

$destination : resource

Writable Stream

$options : array<string|int, mixed> = []

Download options

Tags
throws
FileNotFoundException

if no file could be selected

throws
InvalidArgumentException

if $destination is not a stream

throws
StreamException

if the file could not be uploaded

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

drop()

Drops the files and chunks collections associated with this GridFS bucket.

public drop() : mixed
Tags
throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

find()

Finds documents from the GridFS bucket's files collection matching the query.

public find([array<string|int, mixed>|object $filter = [] ][, array<string|int, mixed> $options = [] ]) : Cursor
Parameters
$filter : array<string|int, mixed>|object = []

Query by which to filter documents

$options : array<string|int, mixed> = []

Additional options

Tags
see
Find::__construct()

for supported options

throws
UnsupportedException

if options are not supported by the selected server

throws
InvalidArgumentException

for parameter/option parsing errors

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
Cursor —

findOne()

Finds a single document from the GridFS bucket's files collection matching the query.

public findOne([array<string|int, mixed>|object $filter = [] ][, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>|object|null
Parameters
$filter : array<string|int, mixed>|object = []

Query by which to filter documents

$options : array<string|int, mixed> = []

Additional options

Tags
see
FindOne::__construct()

for supported options

throws
UnsupportedException

if options are not supported by the selected server

throws
InvalidArgumentException

for parameter/option parsing errors

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
array<string|int, mixed>|object|null —

getBucketName()

Return the bucket name.

public getBucketName() : string
Return values
string —

getChunkSizeBytes()

Return the chunk size in bytes.

public getChunkSizeBytes() : int
Return values
int —

getDatabaseName()

Return the database name.

public getDatabaseName() : string
Return values
string —

getFileDocumentForStream()

Gets the file document of the GridFS file associated with a stream.

public getFileDocumentForStream(resource $stream) : array<string|int, mixed>|object
Parameters
$stream : resource

GridFS stream

Tags
throws
InvalidArgumentException

if $stream is not a GridFS stream

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
array<string|int, mixed>|object —

getFileIdForStream()

Gets the file document's ID of the GridFS file associated with a stream.

public getFileIdForStream(resource $stream) : mixed
Parameters
$stream : resource

GridFS stream

Tags
throws
CorruptFileException

if the file "_id" field does not exist

throws
InvalidArgumentException

if $stream is not a GridFS stream

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

getReadPreference()

Return the read preference for this GridFS bucket.

public getReadPreference() : ReadPreference
Return values
ReadPreference —

getTypeMap()

Return the type map for this GridFS bucket.

public getTypeMap() : array<string|int, mixed>
Return values
array<string|int, mixed> —

openDownloadStream()

Opens a readable stream for reading a GridFS file.

public openDownloadStream(mixed $id) : resource
Parameters
$id : mixed

File ID

Tags
throws
FileNotFoundException

if no file could be selected

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
resource —

openDownloadStreamByName()

Opens a readable stream stream to read a GridFS file, which is selected by name and revision.

public openDownloadStreamByName(string $filename[, array<string|int, mixed> $options = [] ]) : resource

Supported options:

  • revision (integer): Which revision (i.e. documents with the same filename and different uploadDate) of the file to retrieve. Defaults to -1 (i.e. the most recent revision).

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
Parameters
$filename : string

Filename

$options : array<string|int, mixed> = []

Download options

Tags
throws
FileNotFoundException

if no file could be selected

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
resource —

openUploadStream()

Opens a writable stream for writing a GridFS file.

public openUploadStream(string $filename[, array<string|int, mixed> $options = [] ]) : resource

Supported options:

  • _id (mixed): File document identifier. Defaults to a new ObjectId.

  • chunkSizeBytes (integer): The chunk size in bytes. Defaults to the bucket's chunk size.

  • disableMD5 (boolean): When true, no MD5 sum will be generated for the stored file. Defaults to "false".

  • metadata (document): User data for the "metadata" field of the files collection document.

Parameters
$filename : string

Filename

$options : array<string|int, mixed> = []

Upload options

Return values
resource —

rename()

Renames the GridFS file with the specified ID.

public rename(mixed $id, string $newFilename) : mixed
Parameters
$id : mixed

File ID

$newFilename : string

New filename

Tags
throws
FileNotFoundException

if no file could be selected

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

uploadFromStream()

Writes the contents of a readable stream to a GridFS file.

public uploadFromStream(string $filename, resource $source[, array<string|int, mixed> $options = [] ]) : mixed

Supported options:

  • _id (mixed): File document identifier. Defaults to a new ObjectId.

  • chunkSizeBytes (integer): The chunk size in bytes. Defaults to the bucket's chunk size.

  • disableMD5 (boolean): When true, no MD5 sum will be generated for the stored file. Defaults to "false".

  • metadata (document): User data for the "metadata" field of the files collection document.

Parameters
$filename : string

Filename

$source : resource

Readable stream

$options : array<string|int, mixed> = []

Stream options

Tags
throws
InvalidArgumentException

if $source is not a GridFS stream

throws
StreamException

if the file could not be uploaded

throws
RuntimeException

for other driver errors (e.g. connection errors)

Return values
mixed —

ID of the newly created GridFS file

createPathForFile()

Creates a path for an existing GridFS file.

private createPathForFile(stdClass $file) : string
Parameters
$file : stdClass

GridFS file document

Return values
string —

createPathForUpload()

Creates a path for a new GridFS file, which does not yet have an ID.

private createPathForUpload() : string
Return values
string —

getFilesNamespace()

Returns the names of the files collection.

private getFilesNamespace() : string
Return values
string —

getRawFileDocumentForStream()

Gets the file document of the GridFS file associated with a stream.

private getRawFileDocumentForStream(resource $stream) : stdClass

This returns the raw document from the StreamWrapper, which does not respect the Bucket's type map.

Parameters
$stream : resource

GridFS stream

Tags
throws
InvalidArgumentException
Return values
stdClass —

openDownloadStreamByFile()

Opens a readable stream for the GridFS file.

private openDownloadStreamByFile(stdClass $file) : resource
Parameters
$file : stdClass

GridFS file document

Return values
resource —

registerStreamWrapper()

Registers the GridFS stream wrapper if it is not already registered.

private registerStreamWrapper() : mixed
Return values
mixed —

Search results