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();

$customBucket = $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 $fileDocument) {
    echo toJSON($fileDocument), 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. Passe os seguintes parâmetros para o método rename():

• _id valor do arquivo que você deseja renomear

• Novo nome do arquivo

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

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

Alternativamente, você pode usar o método MongoDB\GridFS\Bucket::renameByName() para renomear um arquivo GridFS e todas as suas revisões de arquivo. Passe os seguintes parâmetros para o método renameByName():

• filename valor que você deseja alterar

• Novo nome do arquivo

O exemplo a seguir renomeia todos os arquivos que têm um filename valor de 'my_file':

$bucket->renameByName('my_file', 'new_file_name');

Excluir arquivos

Use o método MongoDB\GridFS\Bucket::delete() para remover o documento de collection de um arquivo GridFS e os chunks associados do seu bucket. Isso exclui efetivamente o arquivo. Passe o valor _id do arquivo que você deseja excluir como parâmetro para o método delete().

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

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

Alternativamente, você pode usar o método MongoDB\GridFS\Bucket::deleteByName() para excluir um arquivo GridFS e todas as suas revisões de arquivo. Passe o valor filename do arquivo que você deseja excluir como parâmetro para o método deleteByName(), conforme mostrado no código a seguir:

$bucket->deleteByName('my_file');

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::renameByName()

• MongoDB\GridFS\Bucket::delete()

• MongoDB\GridFS\Bucket::deleteByName()