Operações de Escrita

Modelo de amostra

As operações de gravação neste guia referenciam a seguinte classe de modelo Eloquent :

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

Inserir um Documento Exemplos

Estes exemplos mostram como utilizar o método save() Eloquent para inserir uma instância de um modelo Concert como um documento MongoDB.

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

Se a operação falhar, a instância do modelo receberá null.

Este código de exemplo executa as seguintes ações:

• Cria uma nova instância do modelo Concert

• Atribui valores de string aos campos performer e venue

• Atribui uma array de strings ao campo genre

• Atribui um número ao campo ticketsSold

• Atribui uma data ao campo performanceDate usando o pacote Carbon

• Insere o documento chamando o método save()

$concert = new Concert();
$concert->performer = 'Mitsuko Uchida';
$concert->venue = 'Carnegie Hall';
$concert->genres = ['classical'];
$concert->ticketsSold = 2121;
$concert->performanceDate = Carbon::create(2024, 4, 1, 20, 0, 0, 'EST');
$concert->save();

Você pode recuperar o valor _id do documento inserido acessando o membro id do modelo, como mostrado no seguinte exemplo de código:

$insertedId = $concert->id;

Se você ativar a atribuição em massa definindo os atributos $fillable ou $guarded , poderá usar o método create() do modelo Eloquent para executar a inserção em uma única chamada, conforme mostrado no exemplo a seguir:

$insertResult = Concert::create([
    'performer' => 'The Rolling Stones',
    'venue' => 'Soldier Field',
    'genres' => [ 'rock', 'pop', 'blues' ],
    'ticketsSold' => 59527,
    'performanceDate' => Carbon::create(2024, 6, 30, 20, 0, 0, 'CDT'),
]);

Para saber mais sobre a extensão da do PHP API Cloud , consulte o Charts Github Repositório .

Exemplo de inserção de vários documentos

Este exemplo mostra como utilizar o método insert() Eloquent para inserir múltiplas instâncias de um modelo Concert como documentos MongoDB . Esse método de inserção em massa reduz o número de chamadas que seu aplicação precisa fazer para salvar os documentos.

Quando o método insert() é bem-sucedido, ele retorna o valor 1.

Se falhar, lança uma exceção.

O código de exemplo salva vários modelos em uma única chamada, passando-os como uma array para o método insert() :

$data = [
    [
        'performer' => 'Brad Mehldau',
        'venue' => 'Philharmonie de Paris',
        'genres' => [ 'jazz', 'post-bop' ],
        'ticketsSold' => 5745,
        'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
    ],
    [
        'performer' => 'Billy Joel',
        'venue' => 'Madison Square Garden',
        'genres' => [ 'rock', 'soft rock', 'pop rock' ],
        'ticketsSold' => 12852,
        'performanceDate' => new UTCDateTime(Carbon::create(2025, 2, 12, 20, 0, 0, 'CET')),
    ],
];
Concert::insert($data);

Exemplos de 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

Exemplo de atualização de 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

Método de upsert

O método upsert(array $values, array|string $uniqueBy, array|null $update) aceita os seguintes parâmetros:

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

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

• $update: lista opcional de campos a serem atualizados 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() , defina os parâmetros conforme mostrado no seguinte exemplo de código:

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

Método de atualização

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.

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

Adicionar valores a um exemplo de array

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

Exemplo de remoção de valores de um array

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

Atualizar o valor de um exemplo de elemento de array

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:

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.

Exemplos de exclusão de documento

Você pode excluir um documento das seguintes maneiras:

• Ligue para o método $model->delete() em uma instância do modelo.

• Chame o método Model::destroy($id) no modelo, passando o ID do documento a ser excluído.

• Métodos de cadeia para recuperar e excluir uma instância de um modelo chamando o método delete() .

O exemplo a seguir mostra como excluir um documento chamando $model->delete() em uma instância do modelo:

$concert = Concert::first();
$concert->delete();

Quando o método delete() é bem-sucedido, a operação retorna o número de documentos excluídos.

Se a parte de recuperação da chamada não corresponder a nenhum documento na coleção, a operação retornará 0.

O exemplo a seguir mostra como excluir um documento passando o valor de seu ID para o método Model::destroy($id):

$id = 'MSG-0212252000';
Concert::destroy($id);

Quando o método destroy() é bem-sucedido, ele retorna o número de documentos excluídos.

Se o valor de ID não corresponder a nenhum documento, o método destroy() retornará 0.

O exemplo a seguir mostra como encadear chamadas para recuperar o primeiro documento correspondente e excluí-lo:

Concert::where('venue', 'Carnegie Hall')
    ->limit(1)
    ->delete();

Quando o método delete() é bem-sucedido, ele retorna o número de documentos excluídos.

Se o método where() não corresponder a nenhum documento, o método delete() retornará 0.

Exemplos de exclusão de vários documentos

Você pode excluir vários documentos das seguintes maneiras:

• Chame o método Model::destroy($ids) , passando uma lista das IDs dos documentos ou instâncias de modelo a serem excluídas.

• Métodos de cadeia para recuperar um objeto de coleção do Laravel que faz referência a vários objetos e excluí-los chamando o método delete() .

O exemplo a seguir mostra como excluir um documento passando uma array de valores de ID , representados por $ids, para o método destroy():

$ids = [3, 5, 7, 9];
Concert::destroy($ids);

Quando o método destroy() é bem-sucedido, ele retorna o número de documentos excluídos.

Se os valores de ID não corresponderem a nenhum documento, o método destroy() retornará 0.

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

Concert::where('ticketsSold', '>', 7500)
    ->delete();

Quando o método delete() é bem-sucedido, ele retorna o número de documentos excluídos.

Se o método where() não corresponder a nenhum documento, o método delete() retornará 0.