Clase de modelo Eloquent

Cambiar el nombre de la colección de modelos

De forma predeterminada, el modelo usa el plural de la clase del modelo (con mayúscula inicial y minúscula). Para cambiar el nombre de la colección que el modelo usa para recuperar y guardar datos en MongoDB, anule la propiedad $table de la clase del modelo.

El siguiente ejemplo especifica el nombre de la colección MongoDB personalizada, celestial_body, para la clase Planet:

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

Sin sobreescribir la propiedad $table, este modelo se asigna a la colección planets. Con la propiedad anulada, la clase de ejemplo almacena el modelo en la colección celestial_body.

Cambiar el campo de clave principal

Para personalizar el campo de clave principal del modelo que identifica de forma única un documento MongoDB, anule la propiedad $primaryKey de la clase del modelo.

De forma predeterminada, el modelo utiliza el controlador PHP MongoDB para generar ObjectID únicos para cada documento que inserta su aplicación Laravel.

El siguiente ejemplo especifica el campo name como clave principal para la clase Planet:

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

Para obtener más información sobre el comportamiento de la clave principal y las opciones de personalización, consulte Claves primarias de Eloquent en la documentación de Laravel.

Para obtener más información sobre el _id campo, los ObjectID y la estructura del documento MongoDB,consulte Documentos en el manual del servidor.

Habilitar eliminaciones suaves

Eloquent incluye una función de eliminación temporal que modifica el comportamiento del método delete() en un modelo. Cuando se habilita la eliminación temporal en un modelo, el método delete() marca un documento como eliminado en lugar de eliminarlo de la base de datos. Establece una marca de tiempo en el campo deleted_at para excluirlo automáticamente de las operaciones de recuperación.

Para habilitar eliminaciones suaves en una clase, agregue el rasgo Illuminate\Database\Eloquent\SoftDeletes como se muestra en el siguiente ejemplo de código:

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

Para obtener más información sobre los métodos que puede ejecutar en modelos con eliminaciones suaves habilitadas, consulte Eliminación suave de Eloquent en la documentación de Laravel.

Tipos de datos de conversión

Eloquent permite convertir los tipos de datos de los atributos del modelo antes de almacenarlos o recuperarlos mediante un asistente de conversión. Este asistente es una alternativa práctica para definir métodos de acceso y mutación equivalentes en el modelo.

En el siguiente ejemplo, el asistente de conversión convierte el discovery_dt atributo de modelo, almacenado en MongoDB como un tipo MongoDB\\BSON\\UTCDateTime, al tipo Laravel.datetime

<?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 conversión permite usar la clase DateTime de PHP para trabajar con fechas en este campo. El siguiente ejemplo muestra una consulta de Laravel que utiliza el ayudante de conversión del modelo para consultar planetas con un discovery_dt valor de de hace menos de tres años:

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

Para obtener más información sobre los tipos de datos de MongoDB, consulte Tipos BSON en el manual del servidor.

Para obtener más información sobre el asistente de conversión de Laravel y los tipos admitidos, consulte Conversión de atributos en la documentación de Laravel.

Personalizar la asignación masiva

Eloquent permite crear varios modelos y sus datos de atributos pasando una matriz de datos al método de modelo create(). Este proceso de inserción de múltiples modelos se denomina asignación masiva.

La asignación masiva puede ser una forma eficiente de crear múltiples modelos. Sin embargo, puede exponer una vulnerabilidad de seguridad explotable. Los datos de los campos podrían contener actualizaciones que otorguen permisos o accesos no autorizados.

Eloquent proporciona las siguientes características para proteger sus datos de vulnerabilidades de asignación masiva:

• $fillable Contiene los campos que se pueden escribir en una asignación masiva

• $guarded Contiene los campos que se ignoran en una asignación masiva

En el siguiente ejemplo, el modelo permite la asignación masiva de los campos mediante el atributo $fillable:

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

El siguiente ejemplo de código muestra la asignación masiva del 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);

Los modelos guardados en la base de datos contienen solo los campos name y gravity ya que day_length se omite del atributo $fillable.

Para aprender cómo cambiar el comportamiento al intentar completar un campo omitido de la $fillable matriz, consulte Excepciones de asignación masiva en la documentación de Laravel.

Ejemplo de clase extendida

Este ejemplo crea una clase de modelo Planet que extiende la clase CelestialBody de un paquete llamado ThirdPartyPackage. La clase Post incluye el atributo DocumentModel y define propiedades como $primaryKey y $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';
}

Después de definir su clase, puede realizar operaciones de MongoDB como de costumbre.

Ejemplo de podabilidad

La siguiente clase podable incluye un método prunable() que coincide con los modelos que la acción de poda elimina y un método pruning() que se ejecuta antes de eliminar un modelo coincidente:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use Illuminate\Database\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
    }
}

Ejemplo "Mass Prunable"

La siguiente clase podable en masa incluye un método prunable() que coincide con los modelos que la acción de poda elimina:

<?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);
    }
}

Ejemplo de control de versiones del esquema

En esta situación de ejemplo, estás trabajando con una colección que primero fue modelada por la siguiente clase:

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

Ahora, desea implementar una nueva versión del esquema en la colección. Puede definir la nueva clase de modelo con el siguiente comportamiento:

• Implementa el rasgo HasSchemaVersion y establece el SCHEMA_VERSION actual en 2

• Define el método migrateSchema() para migrar modelos en los que la versión del esquema es menor que 2 para tener un campo galaxy que tenga un 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';
        }
    }
}

En el documento "WASP-39 b" del siguiente código, el valor del campo schema_version es menor que 2. Al recuperar el documento, la integración de Laravel agrega el campo galaxy y actualiza la versión del esquema a la versión actual, 2.

El documento "Saturn" no contiene el campo schema_version, por lo que la integración de Laravel le asigna la versión del esquema actual al guardarlo.

Finalmente, el código recupera los modelos de la colección para demostrar los cambios:

// 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,
  }
]