Eloquent Relationships

Eloquent relationships can be accessed just like any other properties. This makes it super easy to use in your schema.

Suppose you have defined the following model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Post extends Model
{
    public function comments(): HasMany
    {
        return $this->hasMany(Comment::class);
    }

    public function author(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

Just add fields to your type that are named just like the relationships:

type Post {
  author: User
  comments: [Comment!]
}

This approach is fine if performance is not super critical or if you only fetch a single post. However, as your queries become larger and more complex, you might want to optimize performance.

Defining Relationships

Just like in Laravel, you can define Eloquent Relationships (opens new window) in your schema. Lighthouse has got you covered with specialized directives that optimize the Queries for you.

Suppose you want to load a list of posts and associated comments. When you tell Lighthouse about the relationship, it automatically eager loads the comments when you need them.

One To One

Use the @hasOne directive to define a one-to-one relationship (opens new window) between two types in your schema.

type User {
  phone: Phone @hasOne
}

The inverse can be defined through the @belongsTo directive.

type Phone {
  user: User @belongsTo
}

One To Many

Use the @hasMany directive to define a one-to-many relationship (opens new window).

type Post {
  comments: [Comment!]! @hasMany
}

Again, the inverse is defined with the @belongsTo directive.

type Comment {
  post: Post! @belongsTo
}

Many To Many

While many-to-many relationships (opens new window) are a bit more work to set up in Laravel, defining them in Lighthouse is a breeze. Use the @belongsToMany directive to define it.

type User {
  roles: [Role!]! @belongsToMany
}

The inverse works the same.

type Role {
  users: [User!]! @belongsToMany
}

Renaming Relations

When you define a relation, Lighthouse assumes that the field and the relationship method have the same name. If you need to name your field differently, you have to specify the name of the method.

type Post {
  author: User! @belongsTo(relation: "user")
}

This would work for the following model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Post extends Model
{
    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}