Relaciones de modelos en Eloquent

Ejemplo uno a uno

La siguiente clase de ejemplo muestra cómo definir una relación uno-a-uno HasOne entre un modelo Planet y Orbit usando el método hasOne():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\HasOne;
class Planet extends Model
{
    protected $connection = 'mongodb';
    public function orbit(): HasOne
    {
        return $this->hasOne(Orbit::class);
    }
}

La siguiente clase de ejemplo muestra cómo definir la relación inversa BelongsTo entre Orbit y Planet mediante el método belongsTo():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\BelongsTo;
class Orbit extends Model
{
    protected $connection = 'mongodb';
    public function planet(): BelongsTo
    {
        return $this->belongsTo(Planet::class);
    }
}

El siguiente código de ejemplo muestra cómo instanciar un modelo para cada clase y agregar la relación entre ellas. Haz clic en el botón VIEW OUTPUT para ver los datos creados al ejecutar el código:

$planet = new Planet();
$planet->name = 'Earth';
$planet->diameter_km = 12742;
$planet->save();
$orbit = new Orbit();
$orbit->period = 365.26;
$orbit->direction = 'counterclockwise';
$planet->orbit()->save($orbit);

// Document in the "planets" collection
{
  _id: ObjectId('65de67fb2e59d63e6d07f8b8'),
  name: 'Earth',
  diameter_km: 12742,
  // ...
}
// Document in the "orbits" collection
{
  _id: ObjectId('65de67fb2e59d63e6d07f8b9'),
  period: 365.26,
  direction: 'counterclockwise',
  planet_id: '65de67fb2e59d63e6d07f8b8',
  // ...
}

El siguiente código de ejemplo muestra cómo acceder a los modelos relacionados utilizando las propiedades dinámicas según se definen en las clases de ejemplo:

$planet = Planet::first();
$relatedOrbit = $planet->orbit;
$orbit = Orbit::first();
$relatedPlanet = $orbit->planet;

Ejemplo de uno a muchos

La siguiente clase de ejemplo muestra cómo definir una relación HasMany de uno a muchos entre un Planet modelo padre y Moon modelo hijo mediante el método hasMany():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\HasMany;
class Planet extends Model
{
    protected $connection = 'mongodb';
    public function moons(): HasMany
    {
        return $this->hasMany(Moon::class);
    }
}

La siguiente clase de ejemplo muestra cómo definir la relación inversa BelongsTo entre un modelo hijo Moon y el modelo padre Planet utilizando el método belongsTo():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\BelongsTo;
class Moon extends Model
{
    protected $connection = 'mongodb';
    public function planet(): BelongsTo
    {
        return $this->belongsTo(Planet::class);
    }
}

El siguiente código de ejemplo muestra cómo instanciar un modelo para cada clase y agregar la relación entre ellas. Haz clic en el botón VIEW OUTPUT para ver los datos creados al ejecutar el código:

$planet = new Planet();
$planet->name = 'Jupiter';
$planet->diameter_km = 142984;
$planet->save();
$moon1 = new Moon();
$moon1->name = 'Ganymede';
$moon1->orbital_period = 7.15;
$moon2 = new Moon();
$moon2->name = 'Europa';
$moon2->orbital_period = 3.55;
$planet->moons()->save($moon1);
$planet->moons()->save($moon2);

// Parent document in the "planets" collection
{
  _id: ObjectId('65dfb0050e323bbef800f7b2'),
  name: 'Jupiter',
  diameter_km: 142984,
  // ...
}
// Child documents in the "moons" collection
[
  {
    _id: ObjectId('65dfb0050e323bbef800f7b3'),
    name: 'Ganymede',
    orbital_period: 7.15,
    planet_id: '65dfb0050e323bbef800f7b2',
    // ...
  },
  {
    _id: ObjectId('65dfb0050e323bbef800f7b4'),
    name: 'Europa',
    orbital_period: 3.55,
    planet_id: '65dfb0050e323bbef800f7b2',
    // ...
  }
]

El siguiente código de ejemplo muestra cómo acceder a los modelos relacionados utilizando las propiedades dinámicas tal como se define en las clases de ejemplo.

$planet = Planet::first();
$relatedMoons = $planet->moons;
$moon = Moon::first();
$relatedPlanet = $moon->planet;

Ejemplo de muchos a muchos

La siguiente clase de ejemplo muestra cómo definir una relación de BelongsToMany muchos a muchos entre un modelo Planet y SpaceExplorer mediante el método belongsToMany():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\BelongsToMany;
class Planet extends Model
{
    protected $connection = 'mongodb';
    public function visitors(): BelongsToMany
    {
        return $this->belongsToMany(SpaceExplorer::class);
    }
}

La siguiente clase de ejemplo muestra cómo definir la relación inversa BelongsToMany de varios a varios entre los modelos SpaceExplorer y Planet usando el método belongsToMany():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\BelongsToMany;
class SpaceExplorer extends Model
{
    protected $connection = 'mongodb';
    public function planetsVisited(): BelongsToMany
    {
        return $this->belongsToMany(Planet::class);
    }
}

El siguiente código de ejemplo muestra cómo instanciar un modelo para cada clase y agregar la relación entre ellas. Haz clic en el botón VIEW OUTPUT para ver los datos creados al ejecutar el código:

$planetEarth = new Planet();
$planetEarth->name = 'Earth';
$planetEarth->save();
$planetMars = new Planet();
$planetMars->name = 'Mars';
$planetMars->save();
$planetJupiter = new Planet();
$planetJupiter->name = 'Jupiter';
$planetJupiter->save();
$explorerTanya = new SpaceExplorer();
$explorerTanya->name = 'Tanya Kirbuk';
$explorerTanya->save();
$explorerMark = new SpaceExplorer();
$explorerMark->name = 'Mark Watney';
$explorerMark->save();
$explorerJeanluc = new SpaceExplorer();
$explorerJeanluc->name = 'Jean-Luc Picard';
$explorerJeanluc->save();
$explorerTanya->planetsVisited()->attach($planetEarth);
$explorerTanya->planetsVisited()->attach($planetJupiter);
$explorerMark->planetsVisited()->attach($planetEarth);
$explorerMark->planetsVisited()->attach($planetMars);
$explorerJeanluc->planetsVisited()->attach($planetEarth);
$explorerJeanluc->planetsVisited()->attach($planetMars);
$explorerJeanluc->planetsVisited()->attach($planetJupiter);

// Documents in the "planets" collection
[
  {
    _id: ObjectId('65e1043a5265269a03078ad0'),
    name: 'Earth',
    // ...
    space_explorer_ids: [
      '65e1043b5265269a03078ad3',
      '65e1043b5265269a03078ad4',
      '65e1043b5265269a03078ad5'
    ],
  },
  {
    _id: ObjectId('65e1043a5265269a03078ad1'),
    name: 'Mars',
    // ...
    space_explorer_ids: [ '65e1043b5265269a03078ad4', '65e1043b5265269a03078ad5' ]
  },
  {
    _id: ObjectId('65e1043b5265269a03078ad2'),
    name: 'Jupiter',
    // ...
    space_explorer_ids: [ '65e1043b5265269a03078ad3', '65e1043b5265269a03078ad5' ]
  }
]
// Documents in the "space_explorers" collection
[
  {
    _id: ObjectId('65e1043b5265269a03078ad3'),
    name: 'Tanya Kirbuk',
    // ...
    planet_ids: [ '65e1043a5265269a03078ad0', '65e1043b5265269a03078ad2' ]
  },
  {
    _id: ObjectId('65e1043b5265269a03078ad4'),
    name: 'Mark Watney',
    // ...
    planet_ids: [ '65e1043a5265269a03078ad0', '65e1043a5265269a03078ad1' ]
  },
  {
    _id: ObjectId('65e1043b5265269a03078ad5'),
    name: 'Jean-Luc Picard',
    // ...
    planet_ids: [
      '65e1043a5265269a03078ad0',
      '65e1043a5265269a03078ad1',
      '65e1043b5265269a03078ad2'
    ]
  }
]

El siguiente código de ejemplo muestra cómo acceder a los modelos relacionados utilizando las propiedades dinámicas tal como se define en las clases de ejemplo.

$planet = Planet::first();
$explorers = $planet->visitors;
$spaceExplorer = SpaceExplorer::first();
$explored = $spaceExplorer->planetsVisited;

Hidratación automática

Cuando accedes a una relación incrustada, la Integración de Laravel devuelve los datos incrustados como objetos sin procesar en lugar de instancias de modelo hidratadas por defecto. Cuando los documentos incrustados se devuelven como objetos sin procesar, se aplican los siguientes comportamientos:

• El campo id es de tipo ObjectId, no una string.

• Los campos de fecha son objetos UTCDateTime, no cadenas formateadas.

• No se aplican conversiones de atributos de modelos, métodos ni la serialización de toArray().

Para recuperar documentos incrustados como instancias hidratadas del modelo, añade el nombre de la relación a la propiedad $with en el modelo principal. Esta propiedad carga automáticamente la relación en cada query para que la Integración de Laravel hidrate los documentos incrustados como instancias de modelos.

El siguiente ejemplo define un modelo User que utiliza $with para cargar su relación incrustada addresses:

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\EmbedsMany;
class User extends Model
{
    protected $with = ['addresses'];
    public function addresses()
    {
        return $this->embedsMany(Address::class);
    }
}

Debido a que el modelo incluye $with = ['addresses'], la integración de Laravel devuelve las direcciones incrustadas como instancias del modelo Address. El método toArray() serializa el campo id como una string y los campos de fecha como strings formateadas. Todos los elencos y métodos de modelos Address también están disponibles.

Para obtener más información sobre el patrón de documentos incrustados de MongoDB, consulta los siguientes tutoriales de MongoDB Server:

• Modelar relaciones uno a uno con documentos incrustados

• Modela relaciones uno a muchos con documentos incrustados

La siguiente sección muestra un ejemplo de cómo utilizar el patrón de documento incrustado.

Ejemplo de documento incrustado

La siguiente clase de ejemplo muestra cómo definir un EmbedsMany de uno a muchos entre un modelo SpaceShip y Cargo utilizando el método embedsMany():

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use MongoDB\Laravel\Relations\EmbedsMany;
class SpaceShip extends Model
{
    protected $connection = 'mongodb';
    protected $with = ['cargo'];
    public function cargo(): EmbedsMany
    {
        return $this->embedsMany(Cargo::class);
    }
}

La clase de modelo incrustado omite la definición de relación como se muestra en la siguiente clase de modelo Cargo:

<?php
declare(strict_types=1);
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
class Cargo extends Model
{
    protected $connection = 'mongodb';
}

El siguiente código de ejemplo muestra cómo crear un modelo de SpaceShip e integrar varios modelos de Cargo, y también incluye el documento de MongoDB creado al ejecutar el código. Haz clic en el botón VIEW OUTPUT para ver los datos generados al ejecutar el código:

$spaceship = new SpaceShip();
$spaceship->name = 'The Millenium Falcon';
$spaceship->save();
$cargoSpice = new Cargo();
$cargoSpice->name = 'spice';
$cargoSpice->weight = 50;
$cargoHyperdrive = new Cargo();
$cargoHyperdrive->name = 'hyperdrive';
$cargoHyperdrive->weight = 25;
$spaceship->cargo()->attach($cargoSpice);
$spaceship->cargo()->attach($cargoHyperdrive);

// Document in the "space_ships" collection
{
   _id: ObjectId('65e207b9aa167d29a3048853'),
   name: 'The Millenium Falcon',
   // ...
   cargo: [
     {
       name: 'spice',
       weight: 50,
       // ...
       _id: ObjectId('65e207b9aa167d29a3048854')
     },
     {
       name: 'hyperdrive',
       weight: 25,
       // ...
       _id: ObjectId('65e207b9aa167d29a3048855')
     }
   ]
}

Ejemplo de relación entre bases de datos

La siguiente clase de ejemplo muestra cómo definir una relación HasMany entre un modelo SpaceShip almacenado en una base de datos relacional y un modelo Passenger almacenado en una base de datos MongoDB:

<?php
declare(strict_types=1);
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use MongoDB\Laravel\Eloquent\HybridRelations;
class SpaceShip extends Model
{
    use HybridRelations;
    protected $connection = 'sqlite';
    public function passengers(): HasMany
    {
        return $this->hasMany(Passenger::class);
    }
}

La siguiente clase de ejemplo muestra cómo definir la relación inversa BelongsTo entre un modelo Passenger y el modelo Spaceship utilizando el método belongsTo():

<?php
declare(strict_types=1);
namespace App\Models;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use MongoDB\Laravel\Eloquent\Model;
class Passenger extends Model
{
    protected $connection = 'mongodb';
    public function spaceship(): BelongsTo
    {
        return $this->belongsTo(SpaceShip::class);
    }
}

El siguiente código de ejemplo muestra cómo crear un modelo SpaceShip en una base de datos MySQL y modelos Passenger relacionados en una base de datos MongoDB, así como los datos creados al ejecutar el código. Haz clic en el botón VIEW OUTPUT para ver los datos creados al ejecutar el código:

$spaceship = new SpaceShip();
$spaceship->id = 1234;
$spaceship->name = 'Nostromo';
$spaceship->save();
$passengerEllen = new Passenger();
$passengerEllen->name = 'Ellen Ripley';
$passengerDwayne = new Passenger();
$passengerDwayne->name = 'Dwayne Hicks';
$spaceship->passengers()->save($passengerEllen);
$spaceship->passengers()->save($passengerDwayne);

-- Row in the "space_ships" table
+------+----------+
| id   | name     |
+------+----------+
| 1234 | Nostromo |
+------+----------+
// Document in the "passengers" collection
[
  {
    _id: ObjectId('65e625e74903fd63af0a5524'),
    name: 'Ellen Ripley',
    space_ship_id: 1234,
    // ...
  },
  {
    _id: ObjectId('65e625e74903fd63af0a5525'),
    name: 'Dwayne Hicks',
    space_ship_id: 1234,
    // ...
  }
]

Comportamiento y limitaciones de la agregación

Si almacenas modelos relacionados en su propia colección, la integración de Laravel no puede calcular el agregado en la misma consulta que recupera los modelos principales. En su lugar, ejecuta una consulta adicional para cada agregado que solicites y asigna cada resultado al modelo principal al que pertenece. Considera las siguientes alternativas para consultas que deben escalar:

• Almacena el valor agregado en el documento principal. Por ejemplo, almacena un campo moons_count en cada documento de la colección planets y actualízalo cuando añadas o elimines una luna.

• Utilice la etapa de agregación $lookup para combinar las colecciones en una sola consulta. Para obtener más información, consulte la guía de Operaciones de agregación.

La integración de Laravel calcula agregados en relaciones incrustadas, como las definidas por los métodos embedsOne() y embedsMany(), a partir del documento padre sin ejecutar una consulta adicional.

La integración de Laravel no admite los siguientes comportamientos de agregación y genera una excepción si se utilizan:

• Ordenar los resultados de la consulta por un atributo agregado.

• Agregación de una relación entre bases de datos

• Agregando una relación MorphTo

• Aplicar restricciones, incluidos límites, a una relación incrustada.

Ejemplo de agregado

Este ejemplo utiliza los modelos Planet y Moon definidos en la sección Relación de uno a muchos para recuperar la siguiente información para el primer planeta de la colección:

• Si el planeta tiene lunas

• Número de lunas en órbita

• El período orbital más largo de sus lunas

$planet = Planet::withExists('moons')
    ->withCount('moons')
    ->withMax('moons', 'orbital_period')
    ->first();
echo 'Has moons: ' . ($planet->moons_exists ? 'yes' : 'no') . PHP_EOL;
echo 'Number of moons: ' . $planet->moons_count . PHP_EOL;
echo 'Longest orbital period: ' . $planet->moons_max_orbital_period . PHP_EOL;

Has moons: yes
Number of moons: 2
Longest orbital period: 7.15

El siguiente ejemplo utiliza un alias para almacenar el recuento en un atributo total_moons en lugar del atributo predeterminado moons_count:

$planet = Planet::withCount('moons as total_moons')->first();

El siguiente ejemplo utiliza el método loadCount() para calcular el recuento de una instancia de modelo que el código ya ha recuperado:

$planet = Planet::first();
$planet->loadCount('moons');
echo 'Number of moons: ' . $planet->moons_count . PHP_EOL;

Number of moons: 2