Skip to content

Concepts

Overview

GraphQL is data-centric. On the very top level it is built around three major concepts: Schema, Query and Mutation.

You are expected to express your application as a Schema (aka Type System) and expose it as a single HTTP endpoint (e.g. using our standard server). Application clients (e.g. web or mobile clients) send Queries to this endpoint to request structured data and Mutations to perform changes (usually with HTTP POST method).

Queries

Queries are expressed in simple language that resembles JSON:

{
  hero {
    name
    friends {
      name
    }
  }
}

It was designed to mirror the structure of the expected response:

{
  "hero": {
    "name": "R2-D2",
    "friends": [
      { "name": "Luke Skywalker" },
      { "name": "Han Solo" },
      { "name": "Leia Organa" }
    ]
  }
}

The graphql-php runtime parses Queries, makes sure that they are valid for a given Type System and executes using data fetching tools provided by you as part of the integration. Queries are supposed to be idempotent.

Mutations

Mutations are root fields that are allowed to have side effects, such as creating, updating or deleting data. In contrast to Query fields, the fields within the root Mutation type are executed serially. Otherwise, their definition and execution is identical to all other fields.

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

Variables $ep and $review are sent alongside with the mutation. A full HTTP request might look like this:

// POST /graphql-endpoint
// Content-Type: application/javascript
//
{
  "query": "mutation CreateReviewForEpisode...",
  "variables": {
    "ep": "JEDI",
    "review": {
      "stars": 5,
      "commentary": "This is a great movie!"
    }
  }
}

As you see variables may include complex objects and they will be correctly validated by the graphql-php runtime.

Another nice feature of GraphQL mutations is that they also hold the query for data to be returned after mutation. In our example the mutation will return:

{
  "createReview": {
    "stars": 5,
    "commentary": "This is a great movie!"
  }
}

Type System

Conceptually a GraphQL type is a collection of fields. Each field in turn has its own type which allows building complex hierarchies.

Quick example on pseudo-language:

type BlogPost {
    title: String!
    author: User
    body: String
}

type User {
    id: Id!
    firstName: String
    lastName: String
}

The type system is at the heart of GraphQL integration. That's where graphql-php comes into play.

It provides the following tools and primitives to describe your App as a hierarchy of types:

  • Primitives for defining objects and interfaces
  • Primitives for defining enumerations and unions
  • Primitives for defining custom scalar types
  • Built-in scalar types: ID, String, Int, Float, Boolean
  • Built-in type modifiers: ListOf and NonNull

Same example expressed in graphql-php:

<?php
use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ObjectType;

$userType = new ObjectType([
    'name' => 'User',
    'fields' => [
        'id' => Type::nonNull(Type::id()),
        'firstName' => Type::string(),
        'lastName' => Type::string()
    ]
]);

$blogPostType = new ObjectType([
    'name' => 'BlogPost',
    'fields' => [
        'title' => Type::nonNull(Type::string()),
        'author' => $userType
    ]
]);

Further Reading

To get deeper understanding of GraphQL concepts - read the docs on official GraphQL website

To get started with graphql-php - continue to next section "Getting Started"