Modificar documentos

Visão geral

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:

• Atualizar um documento

• Atualizar vários documentos

• Atualizar ou inserir em uma única operação

• Atualizar Matrizes em um Documento

<?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'];
}

Atualizar um documento

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

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

Atualizar vários documentos

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

Atualizar ou inserir em uma única operação

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.

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

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": ...
}

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

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": ...
}

Atualizar Matrizes em um Documento

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

• Adicionar valores a uma array

• Remover valores de uma array

• Atualizar o valor de um elemento de array

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

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

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

Concert::where('performer', 'Mitsuko Uchida')
    ->push(
        'genres',
        ['baroque'],
    );

{
  "_id": "660eb...",
  "performer": "Mitsuko Uchida",
  "genres": [
      "classical",
      "dance-pop",
  ],
  "updated_at": ...,
  "created_at": ...
}

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

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

{
  "_id": "660e...",
  "performer": "Mitsuko Uchida",
  "genres": [],
  "updated_at": ...,
  "created_at": ...
}

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

$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": ...
}

Informações adicionais

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:

• Atualizar um documento

• Atualizar vários documentos

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