MongoDB\GridFS\Bucket::findOne()

Definição

MongoDB\GridFS\Bucket::findOne()

Localiza um único documento da collection de arquivos do GridFS que corresponda à query.

function findOne(
    array|object $filter = [],
    array $options = []
): array|object|null

Parâmetros

$filter : array|object

Os critérios de filtro que especificam os documentos para consulta.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
allowDiskUse	booleano	Permite gravar em arquivos temporários. Ao definir como `true`, as consultas podem gravar dados no subdiretório `_tmp` no diretório `dbPath`.
allowPartialResults	booleano	Para consultas em relação a uma coleção fragmentada, retorna resultados parciais do se alguns fragmentos não estiverem disponíveis em vez de lançar um `mongos` erro.
Codec	MongoDB\Codec\DocumentCodec	Os dados de codificação com codecs de tipo a serem usados para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção `typeMap`. O padrão é o codec do bucket. A herança de uma opção `codec` padrão tem precedência sobre a da opção `typeMap` . Novidades na versão 1.17.
agrupamento	array\|object	Acolocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o `locale` campo é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. O comentário pode ser qualquer tipo de BSON válido a partir de MongoDB 4.4. As versões anteriores do servidor suportam apenas valores de string.
dica	string\|array\|objeto	O índice a ser utilizado. Especifique o nome do índice como uma string ou o padrão da chave do índice como um documento. Se especificado, o sistema de query considerará apenas os planos usando o índice sugerido. Novidades na versão 1.2.
let	array\|object	Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento. Os parâmetros podem ser acessados como variáveis em um contexto de expressão agregada (como `$$var`). Isto não é suportado para versões de servidor anteriores à 5.0 e resultará em uma exceção no tempo de execução se utilizado. Novidades na versão 1.13.
max	array\|object	O limite superior exclusivo para um índice específico. Novidades na versão 1.2.
maxTimeMS	inteiro	O limite de tempo cumulativo em milésimos de segundo para operações de processamento no cursor. O MongoDB aborta a operação o mais cedo possível após o ponto de interrupção.
min	array\|object	O limite inferior inclusivo para um índice específico. Novidades na versão 1.2.
projeção	array\|object	A especificação da projeção para determinar quais campos incluir nos documentos devolvidos. Consulte Campos do projeto para retornar da consulta e Operadores de projeção no manual do MongoDB.
readConcern	MongoDB\Driver\ReadConcern	Read concern a ser usada para a operação. O padrão é a read concern do bucket. Não é possível especificar uma read concern para operações individuais como parte de uma transação. Em vez disso, defina a opção `readConcern` ao iniciar a transação.
readPreference	MongoDB\Driver\ReadPreference	Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura do bucket.
returnKey	booleano	Se verdadeiro, retorna apenas as chaves de índice nos documentos resultantes. Novidades na versão 1.2.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidades na versão 1.3.
showRecordId	booleano	Determina se o identificador de registro de cada documento deve ser retornado. Se for verdadeiro, adiciona um campo `$recordId` aos documentos retornados. Novidades na versão 1.2.
ignorar	inteiro	Número de documentos a ignorar. O padrão é `0`.
sort	array\|object	A especificação de classificação para a ordenação dos resultados.
typeMap	array	O mapa de tipo a aplicar aos cursores, que determina como os documentos BSON são convertidos em valores PHP. O padrão é o mapa de tipos do bucket. Isso será usado para o documento de resultado retornado.

Return Values

Um array ou objeto para o primeiro documento que correspondeu à query ou null se nenhum documento correspondeu à query. O tipo de retorno depende da typeMap opção.

Erros/exceções

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Comportamento

Ao avaliar critérios de query, o MongoDB compara tipos e valores de acordo com suas próprias regras de comparação para tipos BSON, o que difere das regras de comparação e malabarismo de tipos do PHP. Ao corresponder a um tipo BSON especial, os critérios de query devem usar a respectiva classe BSON na extensão (por exemplo use MongoDB\BSON\ObjectId para corresponder a um ObjectId).

Exemplos

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = fopen('php://temp', 'w+b');
fwrite($stream, "foobar");
rewind($stream);
$bucket->uploadFromStream('b', $stream);
$fileDocument = $bucket->findOne(
    ['length' => ['$lte' => 6]],
    [
        'projection' => [
            'filename' => 1,
            'length' => 1,
            '_id' => 0,
        ],
        'sort' => ['length' => -1],
    ]
);
var_dump($fileDocument);

A saída seria então semelhante a:

object(MongoDB\Model\BSONDocument)#3004 (1) {
  ["storage":"ArrayObject":private]=>
  array(2) {
    ["filename"]=>
    string(1) "b"
    ["length"]=>
    int(6)
  }
}

Veja também

Voltar

find()

getBucketName()