Clase de modelo Eloquent

Cambiar el nombre de la Colección de modelos

Por defecto, el modelo utiliza el nombre de la clase de tu modelo en forma plural con snake case. Para cambiar el nombre de la colección que utiliza el modelo para recuperar y guardar datos en MongoDB, sobreescribe la propiedad $table de la clase del modelo.

El siguiente ejemplo especifica el nombre personalizado de la colección de MongoDB, 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.

Habilitar eliminaciones lógicas

Eloquent incluye una funcionalidad de borrado lógico que cambia el comportamiento del método delete() en un modelo. Cuando la eliminación suave está habilitada en un modelo, el método delete() marca un documento como borrado en lugar de removerlo de la base de datos. Establece una marca temporal en el campo deleted_at para excluirlo automáticamente de las operaciones de recuperación.

Para habilitar borrados suaves en una clase, agrega el trait 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 aprender sobre los métodos que puedes realizar en modelos con eliminados suaves habilitados, consulta Eliminación suave en Eloquent en los Docs de Laravel.

Cast Tipos de datos

Eloquent permite convertir los tipos de datos de los atributos del modelo antes de almacenar o recuperar datos mediante el uso de un asistente de conversión. Este asistente es una alternativa conveniente a definir métodos equivalentes de acceso y mutación en tu modelo.

En el siguiente ejemplo, el asistente de conversión convierte el atributo del modelo discovery_dt, almacenado en MongoDB como un tipo MongoDB\\BSON\\UTCDateTime, al tipo datetime de 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 conversión te permite usar la clase PHP DateTime para trabajar con fechas en este campo. El siguiente ejemplo muestra una query de Laravel que utiliza el asistente de conversión en el modelo para consultar planetas con un discovery_dt de menos de tres años atrás:

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

Para aprender más sobre los tipos de datos de MongoDB, consulta BSON Types 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 los siguientes traits para proteger tus 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 una asignación masiva de los campos mediante el uso del 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 únicamente los campos name y gravity ya que day_length está omitido del atributo $fillable.

Para aprender cómo cambiar el comportamiento al intentar llenar un campo omitido del arreglo de $fillable, consulta Excepciones de Asignación Masiva en la Laravel docs.

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 tu clase, puedes realizar operaciones de MongoDB como de costumbre.

Ejemplo PRUNABLE

La siguiente clase prunable incluye un método prunable() que coincide con los modelos que borra la acción de poda y un método pruning() que se ejecuta antes de borrar 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 muestra, estás trabajando con una colección que fue modelada por primera vez por la siguiente clase:

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

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

• Implementa el HasSchemaVersion rasgo 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, de modo que tengan un campo galaxy con 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" en el siguiente código, el valor del campo schema_version es menor que 2. Cuando se recupera 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,
  }
]