Classe de modelo Eloquent

Alterar o nome da coleção de modelos

Por padrão, o modelo usa a forma plural de snake case do seu nome de classe de modelo. Para alterar o nome da collection que o modelo utiliza para recuperar e salvar dados no MongoDB, substitua a propriedade $table da classe de modelo.

O exemplo a seguir especifica o nome da collection MongoDB customizada, celestial_body, para a classe Planet :

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $table = 'celestial_body';
}

Sem substituir a propriedade $table , este modelo mapeia para a coleção planets . Com a propriedade substituída , a classe de exemplo armazena o modelo na coleção celestial_body .

Alterar o campo de chave primária

Para personalizar o campo de chave primária do modelo que identifica exclusivamente um documento MongoDB, substitua a propriedade $primaryKey da classe de modelo.

Por padrão, o modelo usa o driver PHP MongoDB para gerar ObjectIDs exclusivos para cada documento que seu aplicação Laravel insere.

O exemplo seguinte especifica o campo name como a chave primária para a classe Planet :

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $primaryKey = 'name';
}

Para saber mais sobre o comportamento da chave primária e as opções de personalização, consulte Chaves primárias do Eloquent nos do Docs Laravel.

Para saber mais sobre o campo _id , ObjectIDs e a estrutura do documento MongoDB , consulte Documentos no manual do servidor.

Habilitar exclusões suaves

O Eloquent inclui um recurso de exclusão suave que altera o comportamento do método delete() em um modelo. Quando a exclusão reversível está ativada em um modelo, o método delete() marca um documento como excluído em vez de removê-lo do banco de dados. Ele define um carimbo de data/hora no campo deleted_at para excluí-lo automaticamente das operações de recuperação.

Para habilitar exclusões suaves em uma classe, adicione o traço MongoDB\Laravel\Eloquent\SoftDeletes como mostrado no seguinte exemplo de código :

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Eloquent\SoftDeletes;
class Planet extends Model
{
    use SoftDeletes;
}

Para saber mais sobre os métodos que você pode executar em modelos com as exclusões suaves ativadas, consulte Exclusão suave do Eloquent nos do Docs Laravel.

Converter tipos de dados

O Eloquent permite converter tipos de dados de atributo do modelo antes de armazenar ou recuperar dados usando um auxiliar de conversão. Esse auxiliar é uma alternativa conveniente para definir métodos acessadores e mutadores equivalentes em seu modelo.

No exemplo a seguir, o assistente de conversão converte o discovery_dt atributo de modelo, armazenado no MongoDB como um tipo MongoDB\\BSON\\UTCDateTime, para o datetime tipo do Laravel.

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $casts = [
        'discovery_dt' => 'datetime',
    ];
}

protected function casts(): array
{
   return [
      'discovery_dt' => 'datetime',
   ];
}

Esta conversão permite que você use o PHP DateTime classe para trabalhar com datas neste campo. O exemplo a seguir mostra uma query do Laravel que usa o assistente de fundição no modelo para fazer a query de planetas com um discovery_dt de menos de três anos atrás:

Planet::where( 'discovery_dt', '>', new DateTime('-3 years'))->get();

Para saber mais sobre os tipos de dados do MongoDB, consulte BSON types no manual do servidor.

Para saber mais sobre o auxiliar de conversão do Laravel e os tipos suportados, consulte Fundição de Atributos nos do Docs Laravel.

Personalizar Atribuição em Massa

O Eloquent permite criar vários modelos e seus dados de atributo passando uma array de dados para o método de modelo create() . Este processo de inserção de vários modelos é chamado de atribuição em massa.

A atribuição em massa pode ser uma maneira eficiente de criar vários modelos. No entanto, ele pode expor uma vulnerabilidade de segurança explorável. Os dados nos campos podem conter atualizações que levam a permissões ou acesso não autorizados.

O Eloquent fornece as seguintes características para proteger seus dados de vulnerabilidades de atribuição em massa:

• $fillable contém os campos que são graváveis em uma atribuição em massa

• $guarded contém os campos que são ignorados em uma atribuição em massa

No exemplo seguinte, o modelo permite a atribuição em massa dos campos utilizando o atributo $fillable :

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $fillable = [
        'name',
        'gravitational_force',
        'diameter',
        'moons',
    ];
}

O seguinte exemplo de código mostra a atribuição em massa do modelo Planet :

$planets = [
    [ 'name' => 'Earth', 'gravitational_force' => 9.8, 'day_length' => '24 hours' ],
    [ 'name' => 'Mars', 'gravitational_force' => 3.7, 'day_length' => '25 hours' ],
];
Planet::create($planets);

Os modelos salvos no banco de dados contêm somente os campos name e gravity , pois day_length é omitido do atributo $fillable .

Para saber como alterar o comportamento ao tentar preencher um campo omitido da $fillable array , consulte Exceções de atribuição de massa nos do Docs Laravel.

Exemplo de classe estendida

Este exemplo cria uma classe de modelo Planet que estende a classe CelestialBody de um pacote chamado ThirdPartyPackage. A classe Post inclui a traço DocumentModel e define propriedades, incluindo $primaryKey e $keyType:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\DocumentModel;
use ThirdPartyPackage\CelestialBody;
class Planet extends CelestialBody
{
    use DocumentModel;
    protected $fillable = ['name', 'diameter'];
    protected $keyType = 'string';
}

Depois de definir sua classe, você pode realizar as operações do MongoDB como de costume.

Exemplo executável

A classe de podação a seguir inclui um método prunable() que corresponde aos modelos que a ação de podar exclui e um método pruning() que é executado antes de excluir um modelo correspondente:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Eloquent\Prunable;
class Planet extends Model
{
    use Prunable;
    public function prunable()
    {
        // matches models in which the solar_system field contains a null value
        return static::whereNull('solar_system');
    }
    protected function pruning()
    {
        // Add cleanup actions, such as logging the Planet 'name' attribute
    }
}

Exemplo executável em massa

A seguinte classe prunable em massa inclui um método prunable() que corresponde a modelos que a ação de podar exclui:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\MassPrunable;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use MassPrunable;
    public function prunable()
    {
        // matches models in which the gravitational_force field contains
        // a value greater than 0.5
        return static::where('gravitational_force', '>', 0.5);
    }
}

Exemplo de versionamento de esquema

Nesta situação de exemplo, você está trabalhando com uma coleção que foi modelada pela seguinte classe:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    protected $fillable = ['name', 'type'];
}

Agora, você deseja implementar uma nova versão do esquema na coleção. Você pode definir a nova classe de modelo com o seguinte comportamento:

• Implementa a traça HasSchemaVersion e define o SCHEMA_VERSION atual como 2

• Define o método migrateSchema() para migrar modelos em que a versão do esquema é menor que 2 para ter um campo galaxy que tenha um valor de 'Milky Way'

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\HasSchemaVersion;
use MongoDB\Laravel\Eloquent\Model;
class Planet extends Model
{
    use HasSchemaVersion;
    public const SCHEMA_VERSION = 2;
    protected $fillable = ['name', 'type', 'galaxy'];
    /**
     * Migrate documents with a lower schema version to the most current
     * schema when inserting new data or retrieving from the database.
     */
    public function migrateSchema(int $fromVersion): void
    {
        if ($fromVersion < 2) {
            $this->galaxy = 'Milky Way';
        }
    }
}

No documento "WASP-39 b" no código a seguir, o valor do campo schema_version é menor que 2. Quando você recupera o documento, a integração do Laravel adiciona o campo galaxy e atualiza a versão do esquema para a versão atual, 2.

O documento "Saturn" não contém o campo schema_version , portanto, a integração do Laravel atribui a ele a versão atual do esquema ao salvar.

Por fim, o código recupera os modelos da coleção para demonstrar as alterações:

// Simulates a document in the collection with schema version 1
Planet::insert([
    [
        'name' => 'WASP-39 b',
        'type' => 'gas',
        'schema_version' => 1,
    ],
]);
// Saves a document with no specified schema version
$saturn = Planet::create([
    'name' => 'Saturn',
    'type' => 'gas',
]);
// Retrieves both models from the collection
$planets = Planet::where('type', 'gas')
    ->get();

[
  {
    "_id": ...,
    "name": "WASP-39 b",
    "type": "gas",
    "galaxy": "Milky Way",
    "schema_version": 2,
  },
  {
    "_id": ...,
    "name": "Saturn",
    "type": "gas",
    "schema_version": 2,
  }
]