MongoDB::GridFSBucket - phpMan

NAME
    MongoDB::GridFSBucket - A file storage abstraction

VERSION
    version v2.2.2

SYNOPSIS
        $bucket = $database->gfs;

        # upload a file
        $stream  = $bucket->open_upload_stream("foo.txt");
        $stream->print( $data );
        $stream->close;

        # find and download a file
        $result  = $bucket->find({filename => "foo.txt"});
        $file_id = $result->next->{_id};
        $stream  = $bucket->open_download_stream($file_id)
        $data    = do { local $/; $stream->readline() };

DESCRIPTION
    This class models a GridFS file store in a MongoDB database and provides
    an API for interacting with it.

    Generally, you never construct one of these directly with "new".
    Instead, you call "gfs" (short for "get_gridfsbucket") on a
    MongoDB::Database object.

USAGE
  Data model
    A GridFS file is represented in MongoDB as a "file document" with
    information like the file's name, length, and any user-supplied
    metadata. The actual contents are stored as a number of "chunks" of
    binary data. (Think of the file document as a directory entry and the
    chunks like blocks on disk.)

    Valid file documents typically include the following fields:

    *   _id – a unique ID for this document, typically a BSON ObjectId.

    *   length – the length of this stored file, in bytes

    *   chunkSize – the size, in bytes, of each full data chunk of this
        file. This value is configurable per file.

    *   uploadDate – the date and time this file was added to GridFS, stored
        as a BSON datetime value.

    *   filename – the name of this stored file; the combination of filename
        and uploadDate (millisecond resolution) must be unique

    *   metadata – any additional application data the user wishes to store
        (optional)

    *   md5 – DEPRECATED a hash of the contents of the stored file (store
        this in "metadata" if you need it) (optional)

    *   contentType – DEPRECATED (store this in "metadata" if you need it)
        (optional)

    *   aliases – DEPRECATED (store this in "metadata" if you need it)
        (optional)

    The "find" method searches file documents using these fields. Given the
    "_id" from a document, a file can be downloaded using the download
    methods.

  API Overview
    In addition to general methods like "find", "delete" and "drop", there
    are two ways to go about uploading and downloading:

    *   filehandle-like: you get an object that you can read/write from
        similar to a filehandle. You can even get a tied filehandle that you
        can hand off to other code that requires an actual Perl handle.

    *   streaming: you provide a file handle to read from (upload) or print
        to (download) and data is streamed to (upload) or from (download)
        GridFS until EOF.

  Error handling
    Unless otherwise explicitly documented, all methods throw exceptions if
    an error occurs. The error types are documented in MongoDB::Error.

ATTRIBUTES
  database
    The MongoDB::Database containing the GridFS bucket collections.

  bucket_name
    The name of the GridFS bucket. Defaults to 'fs'. The underlying
    collections that are used to implement a GridFS bucket get this string
    as a prefix (e.g "fs.chunks").

  chunk_size_bytes
    The number of bytes per chunk. Defaults to 261120 (255kb).

  write_concern
    A MongoDB::WriteConcern object. It may be initialized with a hash
    reference that will be coerced into a new MongoDB::WriteConcern object.
    By default it will be inherited from a MongoDB::Database object.

  read_concern
    A MongoDB::ReadConcern object. May be initialized with a hash reference
    or a string that will be coerced into the level of read concern.

    By default it will be inherited from a MongoDB::Database object.

  read_preference
    A MongoDB::ReadPreference object. It may be initialized with a string
    corresponding to one of the valid read preference modes or a hash
    reference that will be coerced into a new MongoDB::ReadPreference
    object. By default it will be inherited from a MongoDB::Database object.

    Note: Because many GridFS operations require multiple independent reads
    from separate collections, use with secondaries is strongly discouraged
    because reads could go to different secondaries, resulting in
    inconsistent data if all file and chunk documents have not replicated to
    all secondaries.

  bson_codec
    An object that provides the "encode_one" and "decode_one" methods, such
    as from BSON. It may be initialized with a hash reference that will be
    coerced into a new BSON object. By default it will be inherited from a
    MongoDB::Database object.

  max_time_ms
    Specifies the maximum amount of time in milliseconds that the server
    should use for working on a query. By default it will be inherited from
    a MongoDB::Database object.

    Note: this will only be used for server versions 2.6 or greater, as that
    was when the $maxTimeMS meta-operator was introduced.

  disable_md5
    When true, files will not include the deprecated "md5" field in the file
    document. Defaults to false.

METHODS
  find
        $result = $bucket->find($filter);
        $result = $bucket->find($filter, $options);

        $file_doc = $result->next;

    Executes a query on the file documents collection with a filter
    expression and returns a MongoDB::QueryResult object. It takes an
    optional hashref of options identical to "find" in MongoDB::Collection.

  find_one
        $file_doc = $bucket->find_one($filter, $projection);
        $file_doc = $bucket->find_one($filter, $projection, $options);

    Executes a query on the file documents collection with a filter
    expression and returns the first document found, or "undef" if no
    document is found.

    See "find_one" in MongoDB::Collection for details about the $projection
    and optional $options fields.

  find_id
        $file_doc = $bucket->find_id( $id );
        $file_doc = $bucket->find_id( $id, $projection );
        $file_doc = $bucket->find_id( $id, $projection, $options );

    Executes a query with a filter expression of "{ _id => $id }" and
    returns a single document or "undef" if no document is found.

    See "find_one" in MongoDB::Collection for details about the $projection
    and optional $options fields.

  open_download_stream
        $stream = $bucket->open_download_stream($id);
        $line = $stream->readline;

    Returns a new MongoDB::GridFSBucket::DownloadStream that can be used to
    download the file with the file document "_id" matching $id. This throws
    a MongoDB::GridFSError if no such file exists.

  open_upload_stream
        $stream = $bucket->open_upload_stream($filename);
        $stream = $bucket->open_upload_stream($filename, $options);

        $stream->print('data');
        $stream->close;
        $file_id = $stream->id

    Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
    upload a new file to a GridFS bucket.

    This method requires a filename to store in the "filename" field of the
    file document. Note: the filename is an arbitrary string; the method
    does not read from this filename locally.

    You can provide an optional hash reference of options that are passed to
    the MongoDB::GridFSBucket::UploadStream constructor:

    *   "chunk_size_bytes" – the number of bytes per chunk. Defaults to the
        "chunk_size_bytes" of the bucket object.

    *   "metadata" – a hash reference for storing arbitrary metadata about
        the file.

  open_upload_stream_with_id
        $stream = $bucket->open_upload_stream_with_id($id, $filename);
        $stream = $bucket->open_upload_stream_with_id($id, $filename, $options);

        $stream->print('data');
        $stream->close;

    Returns a new MongoDB::GridFSBucket::UploadStream that can be used to
    upload a new file to a GridFS bucket.

    This method uses $id as the _id of the file being created, which must be
    unique.

    This method requires a filename to store in the "filename" field of the
    file document. Note: the filename is an arbitrary string; the method
    does not read from this filename locally.

    You can provide an optional hash reference of options, just like
    "open_upload_stream".

  download_to_stream
        $bucket->download_to_stream($id, $out_fh);

    Downloads the file matching $id and writes it to the file handle
    $out_fh. This throws a MongoDB::GridFSError if no such file exists.

  upload_from_stream
        $file_id = $bucket->upload_from_stream($filename, $in_fh);
        $file_id = $bucket->upload_from_stream($filename, $in_fh, $options);

    Reads from a filehandle and uploads its contents to GridFS. It returns
    the "_id" field stored in the file document.

    This method requires a filename to store in the "filename" field of the
    file document. Note: the filename is an arbitrary string; the method
    does not read from this filename locally.

    You can provide an optional hash reference of options, just like
    "open_upload_stream".

  upload_from_stream_with_id
        $bucket->upload_from_stream_with_id($id, $filename, $in_fh);
        $bucket->upload_from_stream_with_id($id, $filename, $in_fh, $options);

    Reads from a filehandle and uploads its contents to GridFS.

    This method uses $id as the _id of the file being created, which must be
    unique.

    This method requires a filename to store in the "filename" field of the
    file document. Note: the filename is an arbitrary string; the method
    does not read from this filename locally.

    You can provide an optional hash reference of options, just like
    "open_upload_stream".

    Unlike "open_upload_stream", this method returns nothing.

  delete
        $bucket->delete($id);

    Deletes the file matching $id from the bucket. This throws a
    MongoDB::GridFSError if no such file exists.

  drop
        $bucket->drop;

    Drops the underlying files documents and chunks collections for this
    bucket.

SEE ALSO
    Core documentation on GridFS: <http://dochub.mongodb.org/core/gridfs>.

AUTHORS
    *   David Golden <david AT mongodb.com>

    *   Rassi <rassi AT mongodb.com>

    *   Mike Friedman <friedo AT friedo.com>

    *   Kristina Chodorow <k.chodorow AT gmail.com>

    *   Florian Ragwitz <rafl AT debian.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2020 by MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004