Eloquent: Getting Started

Lighthouse makes it easy for you to perform queries and mutations on your Eloquent models.

Defining Models

Eloquent models usually map directly to GraphQL types.

type User {
  id: ID!
  name: String!
}

It is strongly advised to name the field that corresponds to your primary key id. Popular client libraries such as Apollo provide out-of-the-box caching if you follow that convention.

Retrieving Models

Instead of defining your own resolver manually, you can just rely on Lighthouse to build the Query for you.

type Query {
  users: [User!]! @all
}

The @all directive will assume the name of your model to be the same as the return type of the Field you are trying to resolve and automatically uses Eloquent to resolve the field.

The following query:

{
  users {
    id
    name
  }
}  

Will return the following result:

{
  "data": {
    "users": [
      {"id": 1, "name": "James Bond"},
      {"id": 2, "name": "Madonna"}
    ]
  }
}

Pagination

You can leverage the @paginate directive to query a large list of models in chunks.

type Query {
    posts: [Post!]! @paginate
}

The schema definition is automatically transformed to this:

type Query {
    posts(first: Int!, page: Int): PostPaginator
}

type PostPaginator {
    data: [Post!]!
    paginatorInfo: PaginatorInfo!
}

And can be queried like this:

{
    posts(first: 10) {
        data {
            id
            title
        }
        paginatorInfo {
            currentPage
            lastPage
        }
    }
}

Adding Query Constraints

Lighthouse provides built-in directives to enhance your queries by giving additional query capabilities to the client.

The following field definition allows you to fetch a single User by ID.

type Query {
  user(id: ID! @eq): User @find
}

You can query this field like this:

{
  user(id: 69){
    name
  }
}

And, if a result is found, receive a result like this:

{
  "data": {
    "user": {
      "name": "Chuck Norris"
    }
  }
}

Create

The easiest way to create data on your server is to use the @create directive.

type Mutation {
  createUser(name: String!): User! @create
}

This will take the arguments that the createUser field receives and use them to create a new model instance.

mutation {
  createUser(name: "Donald"){
    id
    name
  }
}

The newly created user is returned as a result:

{
  "data": {
    "createUser": {
      "id": "123",
      "name": "Donald"
    }
  }
}

Note: Due to Laravel's protections against mass assignment, any arguments used in @create or @update must be added to the $fillable property in your Model. For the above example, we would need the following in \App\Models\User:

class User extends Model
{
  // ...
  protected $fillable = ["name"];
}

For more information, see the laravel docs.

Update

You can update a model with the @update directive.

type Mutation {
  updateUser(id: ID!, name: String): User @update
}

Since GraphQL allows you to update just parts of your data, it is best to have all arguments except id as optional.

mutation {
  updateUser(id: "123" name: "Hillary"){
    id
    name
  }
}
{
  "data": {
    "updateUser": {
      "id": "123",
      "name": "Hillary"
    }
  }
}

Be aware that while a create operation will always return a result, provided you pass valid data, the update may fail to find the model you provided and return null:

{
  "data": {
    "updateUser": null
  }
}

Upsert

Use the @upsert directive to update a model with a given id or create it if it does not exist.

type Mutation {
  upsertUser(id: ID!, name: String!, email: String): User @upsert
}

Since upsert can create or update your data you must have all the minimum fields for a creation as required. The id is always required and must be marked as fillable in the model.

mutation {
  upsertUser(id: "123" name: "Hillary"){
    id
    name
    email
  }
}
{
  "data": {
    "upsertUser": {
      "id": "123",
      "name": "Hillary",
      "email": null
    }
  }
}

Delete

Deleting models is a breeze using the @delete directive. Dangerously easy.

type Mutation {
  deleteUser(id: ID!): User @delete
}

Simply call it with the ID of the user you want to delete.

mutation {
  deleteUser(id: "123"){
    secret
  }
}

This mutation will return the deleted object, so you will have a last chance to look at the data. Use it wisely.

{
  "data": {
    "deleteUser": {
      "secret": "Pink is my favorite color!"
    }
  }
}