Menu Docs

Modificar documentos

Neste guia, você pode aprender como modificar documentos em sua coleção MongoDB a partir de seu aplicação Laravel usando Laravel MongoDB. Use as operações de atualização para modificar documentos existentes ou inserir um documento se nenhum corresponder aos critérios de pesquisa.

Você pode persistir alterações em uma instância de um modelo Eloquent ou usar a sintaxe fluente do Eloquent para encadear uma operação de atualização em métodos que retornam um objeto de coleção Laravel.

Este guia fornece exemplos das seguintes operações de atualização:

As operações deste guia referenciam a seguinte classe de modelo do Eloquent :

Corrigir.php
<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Concert extends Model
{
protected $connection = 'mongodb';
protected $fillable = ['performer', 'venue', 'genres', 'ticketsSold', 'performanceDate'];
protected $casts = ['performanceDate' => 'datetime'];
}

Dica

O atributo $fillable permite que você use a atribuição em massa do Laravel para operações de inserção. Para saber mais sobre a atribuição em massa, consulte Personalizar Atribuição de Massa na documentação da Classe de Modelo Eloquent.

O atributo $casts instrui o Laravel a converter atributos em tipos de dados comuns. Para saber mais, consulte Fundição de atributos na documentação do Laravel.

Você pode atualizar um documento das seguintes maneiras:

  • Modifique uma instância do modelo e salve as alterações chamando o método save() .

  • Métodos de encadeamento para recuperar uma instância de um modelo e executar atualizações chamando o método update() .

O exemplo a seguir mostra como atualizar um documento modificando uma instância do modelo e chamando seu método save() :

$concert = Concert::first();
$concert->venue = 'Manchester Arena';
$concert->ticketsSold = 9543;
$concert->save();

Quando o método save() for bem-sucedido, a instância do modelo na qual você chamou o método conterá os valores atualizados.

Se a operação falhar, a Integração do Laravel atribuirá à instância do modelo um valor null .

O exemplo a seguir mostra como atualizar um documento encadeando métodos para recuperar e atualizar o primeiro documento correspondente:

$concert = Concert::where(['performer' => 'Brad Mehldau'])
->orderBy('id')
->first()
->update(['venue' => 'Manchester Arena', 'ticketsSold' => 9543]);

Observação

A chamada orderBy() classifica os resultados pelo campo _id para garantir uma ordem de classificação consistente. Para saber mais sobre classificação no MongoDB, consulte a entrada do glossário de ordem natural no manual do servidor MongoDB.

Quando o método update() é bem-sucedido, a operação retorna o número de documentos atualizados.

Se a parte de recuperação da chamada não corresponder a nenhum documento, a integração do Laravel retornará o seguinte erro:

Error: Call to a member function update() on null

Para realizar uma atualização em um ou mais documentos, encadeie o método update() aos resultados de um método que recupera os documentos como um objeto de coleção do Laravel, como where().

O exemplo a seguir mostra como encadear chamadas para recuperar documentos correspondentes e atualizá-los:

Concert::whereIn('venue', ['Philharmonie de Paris', 'Soldier Field'])
->update(['venue' => 'Concertgebouw', 'ticketsSold' => 0]);

Quando o método update() é bem-sucedido, a operação retorna o número de documentos atualizados.

Se a parte de recuperação da chamada não corresponder a nenhum documento na coleção, a integração do Laravel retornará o seguinte erro:

Error: Call to a member function update() on null

Uma operação upsert permite realizar uma atualização ou inserir em uma única operação. Essa operação simplifica a tarefa de atualizar um documento ou inserir um se ele não existir.

A partir de v4.7, você pode realizar uma operação de upsert usando um dos seguintes métodos:

  • upsert(): ao usar esse método, você pode realizar um upsert em lote para alterar ou inserir vários documentos em uma operação.

  • update(): Ao usar esse método, você deve especificar a opção upsert para atualizar todos os documentos que correspondam ao filtro de query ou inserir um documento se nenhum documento for correspondido. Somente este método upsert é suportado nas versões v4.6 e anteriores.

O método upsert() aceita os seguintes parâmetros:

  • $values: Array de campos e valores que especificam documentos para atualizar ou inserir.

  • $uniqueBy: um ou mais campos que identificam exclusivamente documentos em seu primeiro parâmetro de array.

  • $update: array opcional de campos para atualizar se existir um documento correspondente. Se você omitir este parâmetro, a Integração do Laravel atualizará todos os campos.

Para especificar um upsert no método upsert(), passe os parâmetros exigidos conforme mostrado no seguinte exemplo de código:

YourModel::upsert(
[/* documents to update or insert */],
'/* unique field */',
[/* fields to update */],
);

Este exemplo mostra como utilizar o método upsert() para executar uma atualização ou inserir em uma única operação. Clique no botão VIEW OUTPUT para ver as alterações de dados resultantes quando houver um documento no qual o valor de performer já esteja 'Angel Olsen' na coleção:

Concert::upsert([
['performer' => 'Angel Olsen', 'venue' => 'Academy of Music', 'ticketsSold' => 275],
['performer' => 'Darondo', 'venue' => 'Cafe du Nord', 'ticketsSold' => 300],
], 'performer', ['ticketsSold']);
{
"_id": "...",
"performer": "Angel Olsen",
"venue": "State Theatre",
"genres": [
"indie",
"rock"
],
"ticketsSold": 275,
"updated_at": ...
},
{
"_id": "...",
"performer": "Darondo",
"venue": "Cafe du Nord",
"ticketsSold": 300,
"updated_at": ...
}

No documento em que o valor de performer é 'Angel Olsen', o valor do campo venue não é atualizado, pois o upsert especifica que a atualização se aplica somente ao campo ticketsSold .

Para especificar um upsert em um update() método , defina a upsert opção true como , conforme mostrado no exemplo de código a seguir:

YourModel::where(/* match criteria */)
->update(
[/* update data */],
['upsert' => true]);

Quando o método update() está encadeado a uma query, ele executa uma das seguintes ações:

  • Se a query corresponder aos documentos, o método update() modificará os documentos correspondentes.

  • Se a query corresponder a zero documentos, o método update() inserirá um documento que conterá os dados de atualização e os dados dos critérios de correspondência de igualdade.

Este exemplo mostra como passar a opção upsert para o método update() para executar uma atualização ou inserir em uma única operação. Clique no botão VIEW OUTPUT para ver o documento de exemplo inserido quando não existem documentos correspondentes:

Concert::where(['performer' => 'Jon Batiste', 'venue' => 'Radio City Music Hall'])
->update(
['genres' => ['R&B', 'soul'], 'ticketsSold' => 4000],
['upsert' => true],
);
{
"_id": "660c...",
"performer": "Jon Batiste",
"venue": "Radio City Music Hall",
"genres": [
"R&B",
"soul"
],
"ticketsSold": 4000,
"updated_at": ...
}

Nesta seção, você pode ver exemplos das seguintes operações que atualizam valores de array em um documento MongoDB:

Estes exemplos modificam o documento de amostra criado pela seguinte operação de inserção:

Concert::create([
'performer' => 'Mitsuko Uchida',
'genres' => ['classical', 'dance-pop'],
]);

Esta seção mostra como usar o método push() para adicionar valores a uma array em um documento MongoDB. Você pode passar um ou mais valores para adicionar e definir o parâmetro opcional unique como true para ignorar a adição de valores duplicados na array. O seguinte exemplo de código mostra a estrutura de uma chamada de método do push() :

YourModel::where(<match criteria>)
->push(
<field name>,
[<values>], // array or single value to add
unique: true); // whether to skip existing values

O exemplo a seguir mostra como adicionar o valor "baroque" ao campo de array genres de um documento correspondente. Clique no botão VIEW OUTPUT para ver o documento atualizado:

Concert::where('performer', 'Mitsuko Uchida')
->push(
'genres',
['baroque'],
);
{
"_id": "660eb...",
"performer": "Mitsuko Uchida",
"genres": [
"classical",
"dance-pop",
],
"updated_at": ...,
"created_at": ...
}

Esta seção mostra como usar o método pull() para remover valores de uma array em um documento MongoDB. Você pode passar um ou mais valores para remover da array. O seguinte exemplo de código mostra a estrutura de uma chamada de método do pull() :

YourModel::where(<match criteria>)
->pull(
<field name>,
[<values>]); // array or single value to remove

O exemplo seguinte mostra como remover os valores de array "classical" e "dance-pop" do campo de array genres . Clique no botão VIEW OUTPUT para ver o documento atualizado:

Concert::where('performer', 'Mitsuko Uchida')
->pull(
'genres',
['dance-pop', 'classical'],
);
{
"_id": "660e...",
"performer": "Mitsuko Uchida",
"genres": [],
"updated_at": ...,
"created_at": ...
}

Esta seção mostra como usar o operador posicional $ para atualizar elementos de array específicos em um documento do MongoDB. O operador $ representa o primeiro elemento de array que corresponde à query. O seguinte exemplo de código mostra a estrutura de uma chamada de atualização do operador posicional em um único documento correspondente:

Observação

Atualmente, a Integração do Laravel oferece esta operação apenas na Fachada DB e não no ORM Eloquent.

DB::connection('mongodb')
->getCollection(<collection name>)
->updateOne(
<match criteria>,
['$set' => ['<array field>.$' => <replacement value>]]);

O exemplo seguinte mostra como substituir o valor de array "dance-pop" por "contemporary" no campo de array genres . Clique no botão VIEW OUTPUT para ver o documento atualizado:

$match = ['performer' => 'Mitsuko Uchida', 'genres' => 'dance-pop'];
$update = ['$set' => ['genres.$' => 'contemporary']];
DB::connection('mongodb')
->getCollection('concerts')
->updateOne($match, $update);
{
"_id": "660e...",
"performer": "Mitsuko Uchida",
"genres": [
"classical",
"contemporary"
],
"updated_at": ...,
"created_at": ...
}

Para saber mais sobre operadores de atualização de array, consulte Operadores de atualização de array no manual do servidor MongoDB.

Para visualizar exemplos de código executáveis que demonstram como atualizar documentos usando a integração com o Laravel, consulte os seguintes exemplos de uso:

Para saber como inserir documentos em uma coleção MongoDB , consulte o guia Inserir Documentos.