MongoDB\Collection::findOneAndReplace()

Nesta página

Definição

Parâmetros
Valores de retorno
Erros/exceções
Comportamento
Exemplos
Veja também

Definição

MongoDB\Collection::findOneAndReplace()

Localiza um único documento que corresponda à query e o substitui.

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

Parâmetros

$filter : array|object

Os critérios de filtro que especificam os documentos a serem substituídos.

$replacement : array|object

O documento de substituição.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
bypassDocumentValidation	booleano	Se `true`, permite que a operação de gravação contorne a validação do nível do documento. O padrão é `false`.
Codec	MongoDB\Codec\DocumentCodec	Ocodec a ser usado para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção `typeMap` . O padrão é o codec da coleção. A herança de uma opção `codec` padrão tem precedência sobre a da opção `typeMap`. Novidade na versão 1.17.
agrupamento	array\|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo `locale` é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento. Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão, a operação usará o agrupamento especificado para a coleção. Se nenhum agrupamento for especificado para a coleção nem para a operação, o MongoDB usará a comparação binária simples usada nas versões anteriores para comparações de strings.
comentário	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. Esta opção está disponível desde o MongoDB 4.4 e resultará em uma exceção no momento da execução se for especificada para uma versão mais antiga do servidor. Novidade na versão 1.13.
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. Esta opção está disponível desde o MongoDB 4.4 e resultará em uma exceção no momento da execução se for especificada para uma versão mais antiga do servidor. Novidade na versão 1.7.
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. Novidade na versão 1.13.
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.
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.
documento de devolução	inteiro	Especifica se deseja devolver o documento antes que a substituição seja aplicada ou depois. O `returnDocument` suporta os seguintes valores: `MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_BEFORE` (padrão) `MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER`
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidade na versão 1.3.
espécie	array\|object	A especificação de classificação para a ordenação dos resultados.
typeMap	array	O mapa de tipos para aplicar aos cursores, que determina como os documentos BSON são convertidos para valores PHP. O padrão é o mapa de tipos da coleção. Isso será usado para o documento de resultado retornado.
upsert	booleano	Se definido como `true`, é criado um novo documento quando nenhum documento corresponde aos critérios da consulta. O valor padrão é `false`, que não insere um novo documento quando nenhuma correspondência é encontrada.
Escreva preocupação	MongoDB\Driver\WriteConcern	Preocupação de gravação a ser usada na operação. O padrão é a preocupação de gravação da coleção. Não é possível especificar uma preocupação de gravação para operações individuais como parte de uma transação. Em vez disso, defina a opção `writeConcern` ao iniciar a transação.

Valores de retorno

Um objeto de array para o documento original ou substituído, dependendo do valor especificado da opção returnDocument . Por padrão, o documento original é devolvido. Se nenhum documento corresponder à query, null será retornado. O tipo de retorno depende da opção typeMap .

Erros/exceções

MongoDB\Exception\UnexpectedValueException se a resposta do comando do servidor estiver malformada.

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 da comparação do PHP e digite malabarismo regras. 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

Considere o seguinte documento na collection restaurants no banco de dados test:

{
  "_id" : ObjectId("576023c7b02fa9281da4139e"),
  "address" : {
    "building" : "977",
    "coord" : [
      -74.06940569999999,
      40.6188443
    ],
    "street" : "Bay Street",
    "zipcode" : "10305"
  },
  "borough" : "Staten Island",
  "cuisine" : "French",
  "grades" : [
    {
      "date" : ISODate("2014-08-15T00:00:00Z"),
      "grade" : "A",
      "score" : 7
    },
    {
      "date" : ISODate("2014-02-13T00:00:00Z"),
      "grade" : "A",
      "score" : 5
    },
    {
      "date" : ISODate("2013-06-07T00:00:00Z"),
      "grade" : "A",
      "score" : 11
    }
  ],
  "name" : "Zest",
  "restaurant_id" : "41220906"
}

A operação a seguir substitui o documento por restaurant_id de "41220906" por um novo documento:

<?php
$collection = (new MongoDB\Client)->teset->restaurants;
$replacedRestaurant = $collection->findOneAndReplace(
    [ 'restaurant_id' => '41220906' ],
    [
        'Borough' => 'Staten Island',
        'cuisine' => 'Italian',
        'grades' => [],
        'name' => 'Staten Island Pastaria',
        'restaurant_id' => '999999999',
    ],
    [ 'returnDocument' => MongoDB\Operation\FindOneAndReplace::RETURN_DOCUMENT_AFTER ]
);
var_dump($replacedRestaurant);

A saída seria então semelhante a:

object(MongoDB\Model\BSONDocument)#18 (1) {
  ["storage":"ArrayObject":private]=>
  array(6) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#11 (1) {
      ["oid"]=>
      string(24) "594d5ef380a846852a4b5837"
    }
    ["Borough"]=>
    string(13) "Staten Island"
    ["cuisine"]=>
    string(7) "Italian"
    ["grades"]=>
    object(MongoDB\Model\BSONArray)#17 (1) {
      ["storage":"ArrayObject":private]=>
      array(0) {
      }
    }
    ["name"]=>
    string(22) "Staten Island Pastaria"
    ["restaurant_id"]=>
    string(9) "999999999"
  }
}

Veja também

MongoDB\Collection::findOneAndDelete()
MongoDB\Collection::findOneAndUpdate()
referência do comando findAndModify no manual MongoDB

Voltar

findOneAndDelete()

findOneAndUpdate()