Eloquent Model Relationships

Overview

When you use a relational database, the Eloquent ORM stores models as rows in tables that correspond to the model classes. When you use MongoDB, the Laravel MongoDB stores models as documents in collections that correspond to the model classes.

To define a relationship, add a function to the model class that calls the appropriate relationship method. This function allows you to access the related model as a dynamic property. A dynamic property lets you access the related model by using the same syntax as you use to access a property on the model.

The following sections describe the Laravel Eloquent and MongoDB-specific relationships available in Laravel MongoDB and show examples of how to define and use them:

• One to one relationship, created by using the hasOne() method and its inverse, belongsTo()

• One to many relationship, created by using the hasMany() and its inverse, belongsTo()

• Many to many relationship, created by using the belongsToMany() method

• Embedded document pattern, a MongoDB-specific relationship that can represent a one to one or one to many relationship, created by using the embedsOne() or embedsMany() method

• Cross-database relationships, required when you want to create relationships between MongoDB and SQL models

One to One Relationship

A one to one relationship between models consists of a model record related to exactly one other type of model record.

When you add a one to one relationship, Eloquent lets you access the model by using a dynamic property and stores the model's document ID on the related model.

In Laravel MongoDB, you can define a one to one relationship by using the hasOne() method or belongsTo() method.

When you add the inverse of the relationship by using the belongsTo() method, Eloquent lets you access the model by using a dynamic property, but does not add any fields.

To learn more about one to one relationships, see One to One in the Laravel documentation.

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

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

$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);

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

One to Many Relationship

A one to many relationship between models consists of a model that is the parent and one or more related child model records.

When you add a one to many relationship method, Eloquent lets you access the model by using a dynamic property and stores the parent model's document ID on each child model document.

In Laravel MongoDB, you can define a one to many relationship by adding the hasMany() method on the parent class and, optionally, the belongsTo() method on the child class.

When you add the inverse of the relationship by using the belongsTo() method, Eloquent lets you access the parent model by using a dynamic property without adding any fields.

To learn more about one to many relationships, see One to Many in the Laravel documentation.

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

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

$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);

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

Many to Many Relationship

A many to many relationship consists of a relationship between two different model types in which, for each type of model, an instance of the model can be related to multiple instances of the other type.

In Laravel MongoDB, you can define a many to many relationship by adding the belongsToMany() method to both related classes.

When you define a many to many relationship in a relational database, Laravel creates a pivot table to track the relationships. When you use Laravel MongoDB, it omits the pivot table creation and adds the related document IDs to a document field derived from the related model class name.

To learn more about many to many relationships in Laravel, see Many to Many in the Laravel documentation.

The following section shows an example of how to create a many to many relationship between model classes.

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

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

$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);

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

Embedded Document Pattern

In MongoDB, the embedded document pattern adds the related model's data into the parent model instead of keeping foreign key references. Use this pattern to meet one or more of the following requirements:

• Keeping associated data together in a single collection

• Performing atomic updates on multiple fields of the document and the associated data

• Reducing the number of reads required to fetch the data

In Laravel MongoDB, you can define embedded documents by adding one of the following methods:

• embedsOne() to embed a single document

• embedsMany() to embed multiple documents

To learn more about the MongoDB embedded document pattern, see the following MongoDB server tutorials:

• Model One-to-One Relationships with Embedded Documents

• Model One-to-Many Relationships with Embedded Documents

The following section shows an example of how to use the embedded document pattern.

<?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';
    public function cargo(): EmbedsMany
    {
        return $this->embedsMany(Cargo::class);
    }
}

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

$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);

Cross-Database Relationships

A cross-database relationship in Laravel MongoDB is a relationship between models stored in a relational database and models stored in a MongoDB database.

When you add a cross-database relationship, Eloquent lets you access the related models by using a dynamic property.

Laravel MongoDB supports the following cross-database relationship methods:

• hasOne()

• hasMany()

• belongsTo()

To define a cross-database relationship, you must import the MongoDB\Laravel\Eloquent\HybridRelations package in the class stored in the relational database.

The following section shows an example of how to define a cross-database relationship.

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

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

$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);