Armazenar arquivos grandes

Visão geral

Neste guia, você pode aprender como armazenar e recuperar arquivos grandes no MongoDB usando GridFS. O GridFS é uma especificação implementada pela Biblioteca PHP do MongoDB que descreve como divisão os arquivos em blocos ao armazená-los e remontá-los ao recuperá-los. A implementação do GridFS da biblioteca é uma abstração que gerencia as operações e a organização do armazenamento de arquivos.

Use o GridFS se o tamanho dos seus arquivos exceder o limite de tamanho de documento BSON de 16MB. Para obter informações mais detalhadas sobre se o GridFS é adequado para seu caso de uso, consulte GridFS no manual do MongoDB Server .

Como funciona o GridFS

O GridFS organiza os arquivos em um bucket, um grupo de coleções do MongoDB que contém os blocos de arquivos e as informações que os descrevem. O bloco contém as seguintes coleções, nomeadas usando a convenção definida na especificação do GridFS:

• A coleção chunks armazena os blocos de arquivo binário.

• A coleção files armazena os metadados do arquivo.

Quando você cria um novo bloco GridFS , a biblioteca cria as coleções anteriores, prefixadas com o nome de bloco padrão fs, a menos que você especifique um nome diferente. A biblioteca também cria um índice em cada coleção para garantir a recuperação eficiente dos arquivos e metadados relacionados. A biblioteca cria o GridFS , se ele não existir, somente quando a primeira operação de gravação é executada. A biblioteca cria índices somente se eles não existirem e quando o bloco estiver vazio. Para obter mais informações sobre os índices do GridFS , consulte Índices do GridFS no manual do MongoDB Server .

Ao usar o GridFS para armazenar arquivos, a biblioteca divide os arquivos em partes menores, cada um representado por um documento separado na coleção chunks . Ele também cria um documento na coleção files que contém um ID de arquivo, nome de arquivo e outros metadados de arquivo. Você pode fazer upload do arquivo passando um stream para a Biblioteca PHP do MongoDB para consumir ou criar um novo stream e escrever diretamente nele. Para saber mais sobre fluxos,consulte Fluxos no manual do PHP.

Visualize o diagrama a seguir para ver como o GridFS divide os arquivos quando carregados em um bucket:

Ao recuperar arquivos, o GridFS obtém os metadados da coleção files no bloco especificado e utiliza as informações para reconstruir o arquivo a partir de documentos na coleção chunks . Você pode ler o arquivo gravando seu conteúdo em um fluxo existente ou criando um novo fluxo que aponte para o arquivo.

Crie um intervalo GridFS

Para armazenar ou recuperar arquivos do GridFS, chame o método MongoDB\Database::selectGridFSBucket() no seu banco de dados de dados. Este método acessa um bucket existente ou cria um novo bucket se não existir.

O exemplo seguinte chama o método selectGridFSBucket() no banco de dados de dados do db :

$bucket = $client->db->selectGridFSBucket();

$custom_bucket = $client->db->selectGridFSBucket(
    ['bucketName' => 'myCustomBucket']
);

Fazer upload de arquivos

Você pode fazer upload de arquivos para um bucket GridFS usando os seguintes métodos:

• MongoDB\GridFS\Bucket::openUploadStream(): abre um novo fluxo de upload para o qual você pode escrever conteúdo de arquivo

• MongoDB\GridFS\Bucket::uploadFromStream(): carrega o conteúdo de um fluxo existente em um arquivo GridFS

$stream = $bucket->openUploadStream('my_file', [
    'metadata' => ['contentType' => 'text/plain']
]);
fwrite($stream, 'Data to store');
fclose($stream);

$file = fopen('/path/to/input_file', 'rb');
$bucket->uploadFromStream('new_file', $file);

Recuperar informações do arquivo

Nesta seção, você pode aprender como recuperar metadados de arquivo armazenados na coleção files do contêiner GridFS. Os metadados contêm informações sobre o arquivo a que se refere, incluindo:

• O _id do arquivo

• O nome do arquivo

• O tamanho/comprimento do arquivo

• A data e a hora do carregamento

• Um documento metadata no qual você pode armazenar qualquer outra informação

Para recuperar arquivos de um GridFS , chame o método MongoDB\GridFS\Bucket::find() na instância do MongoDB\GridFS\Bucket . O método retorna uma instância do MongoDB\Driver\Cursor da qual você pode acessar os resultados. Para saber mais sobre Cursor objetos na biblioteca MongoDB PHP, consulte o guia Acessar dados de um cursor .

$files = $bucket->find();
foreach ($files as $file_doc) {
    echo toJSON($file_doc), PHP_EOL;
}

{ "_id" : { "$oid" : "..." }, "chunkSize" : 261120, "filename" : "my_file",
"length" : 13, "uploadDate" : { ... }, "metadata" : { "contentType" : "text/plain" },
"md5" : "6b24249b03ea3dd176c5a04f037a658c" }
{ "_id" : { "$oid" : "..." }, "chunkSize" : 261120, "filename" : "new_file",
"length" : 13, "uploadDate" : { ... }, "md5" : "6b24249b03ea3dd176c5a04f037a658c" }

function toJSON(object $document): string
{
    return MongoDB\BSON\Document::fromPHP($document)->toRelaxedExtendedJSON();
}

Baixar arquivos

Você pode baixar arquivos de um bucket GridFS usando os seguintes métodos:

• MongoDB\GridFS\Bucket::openDownloadStreamByName() ou MongoDB\GridFS\Bucket::openDownloadStream(): abre um novo fluxo de download do qual você pode ler o conteúdo do arquivo

• MongoDB\GridFS\Bucket::downloadToStream(): grava o arquivo inteiro em um fluxo de download existente

$stream = $bucket->openDownloadStreamByName('my_file');
$contents = stream_get_contents($stream);
echo $contents, PHP_EOL;
fclose($stream);

"Data to store"

$stream = $bucket->openDownloadStream(new ObjectId('66e0a5487c880f844c0a32b1'));
$contents = stream_get_contents($stream);
fclose($stream);

$stream = $bucket->openDownloadStreamByName('my_file', ['revision' => 0]);
$contents = stream_get_contents($stream);
fclose($stream);

$file = fopen('/path/to/output_file', 'wb');
$bucket->downloadToStream(
	new ObjectId('66e0a5487c880f844c0a32b1'),
	$file,
);

Renomear arquivos

Utilize o método MongoDB\GridFS\Bucket::rename() para atualizar o nome de um arquivo GridFS em seu bucket. Você deve especificar o arquivo para renomear pelo campo _id em vez do nome do arquivo.

O exemplo a seguir mostra como atualizar o filename campo 'new_file_name' para fazendo referência ao _id campo de um documento:

$bucket->rename(new ObjectId('66e0a5487c880f844c0a32b1'), 'new_file_name');

Excluir arquivos

Use o método MongoDB\GridFS\Bucket::delete() para remover o documento de collection de um arquivo e os chunks associados do seu bucket. Isso exclui efetivamente o arquivo. Você deve especificar o arquivo pelo campo _id em vez do nome do arquivo.

O seguinte exemplo mostra como excluir um arquivo referenciando seu campo _id:

$bucket->delete(new ObjectId('66e0a5487c880f844c0a32b1'));

Documentação da API

Para saber mais sobre como usar a biblioteca PHP do MongoDB para armazenar e recuperar arquivos grandes, consulte a seguinte documentação da API:

• MongoDB\Database::selectGridFSBucket()

• MongoDB\GridFS\Bucket::openUploadStream()

• MongoDB\GridFS\Bucket::uploadFromStream()

• MongoDB\GridFS\Bucket::find()

• MongoDB\GridFS\Bucket::openDownloadStreamByName()

• MongoDB\GridFS\Bucket::openDownloadStream()

• MongoDB\GridFS\Bucket::downloadToStream()

• MongoDB\GridFS\Bucket::rename()

• MongoDB\GridFS\Bucket::delete()