Tutorial: Building a GraphQL API in PHP

Building a GraphQL API in PHP
@AndrewRota | Longhorn PHP 2019
Code: bit.ly/graphql-php-tutorial-repo
Glitch: bit.ly/graphql-php-glitch
Complete App: bit.ly/complete-graphql-php
Complete Code: bit.ly/complete-graphql-php-glitch

Today we’ll learn about GraphQL and
build a GraphQL API in PHP which can
be consumed with a JavaScript
frontend.

By the end of the workshop you will:
- Understand what GraphQL is and how it works
- Have built a GraphQL API in PHP
- Know why GraphQL might be the right choice for your
application

Andrew Rota
@AndrewRota
Associate Director, Software Engineering

Challenges traditional APIs
‣ Over-fetching data
‣ Under-fetching data, requiring multiple round-trips
‣ Time spent iterating on endpoints and expected data shape

GraphQL oﬀers an alternative
architecture for developing eﬀicient,
easy to understand APIs.

What is GraphQL?
“GraphQL is a query
language for APIs and a
runtime for fulﬁlling those
queries with your existing
data.”

{
conferences {
name
dates
}
}
"conferences": [
{
"name": "Longhorn PHP",
"dates": "May 2-4, 2019"
}
]

{
conferences {
name
speakers {
name
twitter
}
}
}
{
"conferences": [
{
"name": "Longhorn PHP",
"speakers": [
{
"name": "Andrew Rota",
"twitter": "https://twitter.com/AndrewRota"
}
]
}
]
}

Tutorial
Agenda
❏ Intro to GraphQL Concepts
❏ Setup our PHP project
❏ Queries
❏ Types and Resolvers
❏ Deferred Resolvers
❏ Mutations
❏ GraphQL on the Frontend
❏ Q&A

What we’re Building
An API for querying a database of PHP conferences and speakers.

phpconferences.sqlite `conferences` table:
`talks` table:
`speakers` table:

Development Environment
I recommend “Glitch,” a browser-based editor with a server environment that runs PHP code.
bit.ly/graphql-php-glitch

Development Environment
You can also clone the repo and run it locally with PHP 7.2 w/ SQLite and Composer.
Run: `composer install; composer run start --timeout=0`

GraphQL
‣ Developed internally at Facebook in 2012
‣ Open sourced in 2015
‣ Spec: facebook.github.io/graphql/draft

GraphQL Implementations
‣ GraphQL is technology agnostic for both client and server
‣ Client implementations:
‣ Server implementations:

GraphQL Advantages
‣ Client requests exactly the shape of the data it needs
‣ Multiple resources can be queried in a single request
‣ API is defined with a strongly-typed schema
‣ Supports powerful tooling for developers
‣ Streamlines frontend ← → backend API conversations

GraphQL in a web stack
QueryClient
(e.g., browser, mobile
app)
/graphql on
PHP Server
response
Database

Queries + Fields
‣ In GraphQL you make queries
for fields on objects
‣ The response will have the
same shape as the query
query {
conferences {
name
dates
}
}
query
field

Fields
‣ Fields might be scalar values,
or they might be other Objects.
‣ Fields can refer to Objects, and
you can make a sub-selection
for fields of these Objects.
‣ This lets you avoid making
multiple requests for related
resources
query {
conferences {
name
speakers {
name
}
}
}
sub-selection

Arguments
‣ You can pass named
arguments to each field
and nested object.
{
conference(name: "Longhorn PHP") {
speakers {
name
}
}
}
argument

Variables
‣ Dynamic values can be
passed into queries via
variables
query SearchConfs($name: String){
conferences(nameFilter:$name) {
name
}
}
{"name": "Longhorn"}

EXERCISE #1
Write and run GraphQL queries
1. Go to
https://graphql.github.io/swapi-g
raphql
2. Run a query (use docs tab to
explore graph). For example:

Types + Schemas
‣ Every GraphQL service
defines the a set of types
that describe what data can
be requested

Types + Schemas
‣ GraphQL servers can be
written in any language, so
we describe types with a
language-agnostic “GraphQL
schema language”
type Conference {
name: String!
url: String!
description: String
location: String
dates: String!
# List of speakers at this conference
speakers: [Speaker]
}

Types + Schemas
‣ GraphQL servers can be
written in any language, so
we describe types with a
language-agnostic “GraphQL
schema language”
‣ Types include: object, scalar,
list, enumeration, union,
interface, and non-nullable.
type Conference {
name: String!
url: String!
description: String
location: String
dates: String!
# List of speakers at this conference
speakers: [Speaker]
}
non-nullable
scalar type
list of
object
types

Query + Mutation Types
‣ There are two special types
in every GraphQL schema:
Query and Mutation
‣ Root fields you define on
Query and Mutation are the
entry points of requests
type Query {
# Returns conferences
conferences: [Conference]
# Returns speakers
speakers: [Speaker]
}
root
fields
root type

Queries
‣ Queries ask for for data;
analogous to GET requests.
‣ GraphQL clients (e.g.,
browsers, mobile apps),
make queries against a single
GraphQL endpoint
‣ Operation name and type
can be optional
query ConferenceNamesAndDates{
conferences {
name
dates
}
}
operation nameoperation type
fields

Mutations
‣ Mutations are for modifying
data; analogous to
POST/PUT/DELETE requests.
‣ They start with the mutation
root type, and will often
leverage arguments, but are
otherwise the same as
queries
mutation {
addSpeaker(
name: "Andrew Rota",
twitter: "https://twitter.com/andrewrota")
{
id
}
}

Introspection
‣ A key feature of GraphQL is
its introspection system
‣ You can ask any GraphQL
schema about what queries
it supports
‣ This unlocks opportunities
for powerful tooling
{
"data": {
"__schema": {
"queryType": {
"name": "Query"
},
"types": [
{
"kind": "OBJECT",
"name": "Query",
"description": null,
"fields": [
{
"name": "conferences",
"description": "Returns a list of PHP conferences",
"args": [],
"type": {
"kind": "LIST",
"name": null,
"ofType": {
"kind": "OBJECT",
"name": "Conference",
"ofType": null
}
},
"isDeprecated": false,
"deprecationReason": null
}
]
}
]
}
}
}

GraphiQL - in browser IDE for exploring GraphQL

Voyager - Any GraphQL API as an interactive graph

Graphql Playground - like GraphiQL, but more features

PHPStorm JS GraphQL Plugin - IDE Integration

EXERCISE #2
-- Discussion --
Explore an API with Voyager
● What did you notice about the
data graph?
● How does the data compare or
contrast with data in applications
you work with?

EXERCISE #2
Explore an API with Voyager
1. Go to apis.guru/graphql-voyager
2. Select and API and explore!

EXERCISE #3
Setup our PHP workspace with
Glitch
1. Go to: bit.ly/graphql-php-glitch
2. Click “Remix to Edit”
3. Explore and run the project
● index.php: links to voyager and
graphql-playground and JS
clients
● graphql.php: the graphql
endpoint

EXERCISE #3
Modify the code and see it run in
graphql_playground.php
1. In graphql.php, add “hello world”
string to the output array
2. Test that the endpoint now returns
that array in graphql.php

webonyx/graphql-php
Provides:
‣ Type primitives for your Type system
‣ Query parsing, validation, and
execution against a Type system
‣ Type introspection
‣ Tools for deferred field resolution
Feature-complete implementation of the
GraphQL spec in PHP, inspired by
Facebook’s original node-js reference library.

webonyx/graphql-php
Used by:
‣ Folkloreatelier/laravel-graphql
‣ overblog/GraphQLBundle (symfony)
‣ ivome/graphql-relay-php
‣ wp-graphql/wp-graphql
‣ tim-field/graphql-wp
Feature-complete implementation of the
GraphQL spec in PHP, inspired by
Facebook’s original node-js reference library.

EXERCISE #3: Install graphql-php
1. In the console, run:
composer require webonyx/graphql-php; refresh;
2. Check composer.json for the webonyx/graphql-php entry

Schemas start with the special root type, Query.

Creating a Query Type
‣ ObjectType is a collection of
fields
‣ Query has root fields, the
entry points for queries.
‣ Each field must have a name
and type. It can also have a
resolve function, args,
description, and other
properties.
use GraphQLTypeDefinitionObjectType;
use GraphQLTypeDefinitionType;
$queryType = new ObjectType([
'name' => 'Query',
'fields' => [
'message' => [
'type' => Type::string(),
'resolve' => function ($root, $args) {
return 'hello world';
}
],
]
]);

Exercise #4
Creating the Query type
1. See the Query type
configuration in
App/Type/QueryType.php
2. Add a field “message” with a
resolver that returns a string
$config = [
'name' => 'Query',
'fields' => [
'message' => [
'resolve' => function () {
return 'hello world!';
}
],
]
];

The graphql.php endpoint should take a query, execute it against
a schema, and return the data from resolvers.

1. Parse the query into an AST
2. Validate the query against the schema
3. Traverse the query, breadth first, and execute a resolver
function for each field

Facade Method for
Query Execution
‣ graphql-php oﬀers a facade
for this process in the class
GraphQLGraphQL
use GraphQLGraphQL;
$result = GraphQL::executeQuery(
$schema,
$queryString,
$rootValue = null,
$context = null,
$variableValues = null,
$operationName = null,
$fieldResolver = null,
$validationRules = null
);
$serializableResult = $result->toArray();

Exercise #5
Initialize Schema and Execute Query
1. Initialize Schema instance with
Query type
2. Execute query and return result
// graphql.php
$schema = new Schema([
'query' => Types::query()
]);
$schema,
$data['query'],
null,
null,
(array)$data['variables']
);
$output = $result->toArray($debug);

Exercise #6
Add to the message field
1. Add an argument to the
message field
2. Make the argument required
(hint: use Type::nonNull)
3. Add a description to the field,
and view it in docs tab of
graphql_playground
$config = [
'name' => 'Query',
'fields' => [
'message' => [
'args' => [
'name' => Type::string(),
],
'resolve' => function ($root, $args) {
return 'hello' . $args['name'];
}
],
]
];

Building a GraphQL server is primarily about structuring schema
types, and then implementing their field resolvers

The schema defines what queries can be made, what types of
data can be requested, and the relationships between those types
The resolver functions define how to get the data for each field.
definition
implementation

Types
graphql-php provides types, which are instances of classes from GraphQLTypeDefinition
○ ObjectType → collection of fields, each with their own type
○ ScalarType → built in scalars types: string, int, float, boolean, or id
○ InterfaceType → abstract type with a collection of fields
○ UnionType → abstract type which enumerates other possible object types
○ InputObjectType → like ObjectType, but for complex args inputted by user
○ EnumType → scalar type which is restricted to a set of allowed values
○ listOf → array (or Traversable) list of another type
○ nonNull → any type which is guaranteed to not be null

Common pattern for adding new objects to the graph:
1. Define a custom object type
2. Add it to a new field on an existing object type
3. Write the field resolver function

Custom Object Types
○ We can define custom types by extending the ObjectType
○ These types will be a collection of fields, which could be other
custom or builtin types

Type Registry
Each type must only be a single instance
in the Schema, so we can use a registry
class with static functions to store each
type.
Our type registry is in App/Types.php
Whenever we add a new type, we should
also add it to the type registry.
/**
* @return QueryType
*/
public static function query()
{
return self::$query ?: (self::$query = new
QueryType());
}

Let’s create our first custom type

Exercise #7
Add a conference type
1. Define the type for a conference in
App/Type/ConferenceType.php
2. Add all of the type’s scalar fields
(i.e., omit the more complex
“speaker” type)
3. Add the type to the types registry
(App/Types.php)
$config = [
'name' => 'Conference',
'fields' => [
'id' => Type::nonNull(Types::int()),
'name' => Type::nonNull(Types::string()),
'url' => Type::nonNull(Types::string()),
'description' => Types::string(),
'location' => Types::string(),
'dates' => Type::nonNull(Types::string())
]
];

Exercise #8a
Add conferences to root query
1. Add conferences field to the
root query that returns all the
conferences with
DataSource::getConferences
2. Add an argument to filter by
name, using
DataSource::searchConferencesByName
'conferences' => [
'type' => Types::listOf(Types::conference()),
'description' => 'List PHP Conferences',
'resolve' => function() {
return DataSource::getConferences();
}
],

Exercise #8b
Add getConferenceById field
1. Create another root field for
getting conferences, but with
an argument to select
conference by id using
DataSource::getConferenceById
'conferences' => [
'type' => Types::listOf(Types::conference()),
}
],

Data fetching happens in resolve functions.

Resolvers
‣ Resolve function can be
implemented however you’d like to
get the data: SQL queries, cache, or
another API.
‣ Start by implementing the resolver
on the Query’s field
‣ For scalars, the return value will be
the value of the field
‣ For object types, the return value
will be passed on to nested fields
// QueryType.php
'conferences' => [
'type' => Types::listOf(Types::Conference()),
}
],

Default + Custom Resolvers
‣ The default field resolver for
objects will return the value
(or null) by key or property
on the object
‣ Or you can implement a
custom resolver at the type
or field level itself
○ ‘resolveField’ on type
○ ‘resolve’ on field
// SomeType.php
'fields' => [
// Default resolvers return property on object
'id' => Type::nonNull(Types::int()),
'name' => Type::nonNull(Types::string()),
// Custom resolver function
'otherField' => ['type' => Types::string(), 'resolve' =>
function ($value) {
return 'some other value';
}],
// Field not on object, to be handled by resolveField
'formattedName' => Type::nonNull(Types::string()),
],
// Custom resolveField function for type
'resolveField' => function($value, $args, $ctx, $info) {
if ($info->fieldName === 'formattedName') {
return $value->name . '!';
}
return $value->{$info->fieldName};
}

...let’s take a closer look at a resolve function
function($root, $args, $context, ResolveInfo $info) {
return DataSource::getData($root->id);
}
root / parent
result
arguments app context
query AST and
other meta info

Exercise #9
Add custom field resolvers
1. Add a custom field to the
conference type that returns a
formatted value not available on
the original object.
2. Refactor to use the field-level
resolve function and type-level
resolveField function
'formattedName' => [
'type' => Types::string(),
'resolve' => function($value) {
return $value->name . '!!! 🎉';
}
]

Let’s add another type and root field!

Exercise #10
Add speakers type and fields
1. Add a Speakers type in App/Type/SpeakerType.php
2. Add a root `speakers` field in QueryType.php to get all speakers with
DataSource::getSpeakers()
3. Add a speakers field to conference, and resolve data with
DataSource::getSpeakersAtConference($id)

Context
‣ A value to hold information
shared by all resolvers, e.g.,
user data, request metadata,
etc.
‣ Set initially as 4th argument
to GraphQL::executeQuery()
‣ Available as the 3rd
argument in all resolvers
// graphql.php
$schema,
$data['query'],
null,
$appContext,
(array) $data['variables']
);
// resolver function
function($value, $args, $context) {
return $context->someValue;
}

Exercise #11
Add context
1. Add a context object in
executeQuery with some global
data (e.g., a hard coded username)
2. Output that context as part of a field
resolver’s return value.
// graphql.php
class AppContext{
public $user;
}
// ...
$appContext = new AppContext();
$appContext->user = 'something';
// ...
$schema,
$data['query'],
null,
$appContext,
(array) $data['variables']
);

n+1 problem
‣ Data-fetching problem that
occurs when you need to
fetch related items in a
one-to-many relationship
{
conferences {
name
speakers{
name
}
}
}

Solution: deferred resolvers
‣ We can use GraphQLDeferred to
delay field resolution until we can
make a single batch request for the
data
‣ Once all non-deferred fields are
resolved, graphql-php will call the
wrapped closures
‣ If you have an environment that
supports async operations (e.g.,
HHVM, ReactPHP, PHP threads),
some fields can also resolve async.
'resolve' => function($root) {
SpeakerCollection::add($root->id);
return new Deferred(function() use ($root) {
return SpeakerCollection::get($root->id);
});
}

Exercise #12
Implement a deferred resolver
1. Refactor speakers field on
Conference type to use a deferred
resolver
2. See App/SpeakerCollection.php
and DataSource::selectSpeakers to
see how this might be more
eﬀicient
'resolve' => function($root) {
SpeakerCollection::add($root->id);
return new Deferred(function() use ($root) {
return SpeakerCollection::get($root->id);
});
}

So far we’ve been reading data with queries, but like any API,
GraphQL can also manipulate data with mutations.

Mutation Types
‣ Mutation is a special root type, just
like Query, which extends from
ObjectType
‣ Mutation types and their fields work
the same as other types, but the
resolvers will add/change rather
than read
‣ The type of a mutation field can be
an Object type with a return value
(e.g., id of added item)
// graphql.php
$schema = new Schema([
'query' => Types::query(),
'mutation' => Types::mutation()
]);
// App/Type/MutationType.php
$config = [
'name' => 'Mutation',
'fields' => [
]
];

Exercise #13
Create a mutation to add a speaker
1. Create the Mutation type in
App/type/Mutation.php
2. Add the Mutation type to the
schema in graphql.php
3. In Mutation.php, create an
addSpeaker field, which will use
DataSource::addSpeaker to add a
new speaker to the database.
'addSpeaker' => [
'type' => Types::listOf(Types::speaker()),
'args' => [
'name' => Type::nonNull(Type::string()),
'twitter' => Type::string()
],
'type' => new ObjectType([
'name' => 'CreateSpeakerOutput',
'fields' => [
'id' => ['type' => Type::int()]
]
]),
'description' => 'Adds a new conference',
'resolve' => function($root, $args) {
return DataSource::addSpeaker($args['name'],
isset($args['twitter']) ? $args['twitter'] : null);
}
]

Client-side GraphQL is about writing queries to request data from
a GraphQL server with a defined schema.

Queries from JavaScript
‣ Queries are made via HTTP
requests to a single endpoint
‣ There are several libraries
available to manage
GraphQL on the client
query ConferenceNamesAndDates{
conferences {
name
dates
}
}

Lokka
a simple graphql client library
‣ A simple JavaScript library for sending GraphQL queries in JavaScript,
just like standard fetch or ajax requests

Exercise #14
Run a client-side query with Lokka
1. Open lokka.php and write
JavaScript to initialize the Lokka
client
2. Using the query method, run a
query and print it to the console
once the promise resolves
var client = new Lokka({
transport: new Transport('/graphql.php')
});
client.query(``).then(response =>
{ console.log(response); });

Apollo Client
complete data management solution
‣ Declarative API for queries and mutations
‣ Normalized client-side caching
‣ Combine local and remote data
‣ Features for pagination, error handling, refetching, and optimistic UI
‣ Client libraries for popular frontend frameworks (React.js, Angular, Vue), as
well as native Android and iOS applications

Exercise #15
Run a client-side query with Apollo
1. Open apollo.php and write
JavaScript to initialize the Apollo
client
2. Using the <Query> component, run
a query to request conferences, and
render them in a list
const client = new ApolloClient({
link: new HttpLink( { uri: "/graphql.php" }),
cache: new InMemoryCache()
});
const CONFERENCES_QUERY = gql``;
ReactDOM.render(
<Query client={client} query={CONFERENCES_QUERY}>
{({ loading, error, data }) => {
if (loading) return 'Loading...';
if (error) return `Error!`;
return (
<ul>
{data.conferences.map(conference => (
<li key={conference.id}>
{conference.name}
</li>
))}
</ul>
);
}}
</Query>,
document.getElementById('root')
);

GraphQL makes it easier to make
more eﬀicient queries between your
client and your server.

GraphQL provides new ways to think
about your APIs and the structure of
your application’s data.

Andrew Rota
@AndrewRota
Resources
‣ graphql.org
‣ github.com/webonyx/graphql-php
‣ github.com/chentsulin/awesome-graphql
‣ Howtographql.com
Code: bit.ly/graphql-php-tutorial-repo
Glitch: bit.ly/graphql-php-glitch
Complete App: bit.ly/complete-graphql-php
Complete Code: bit.ly/complete-graphql-php-glitch

Tutorial: Building a GraphQL API in PHP

In this document

More Related Content

What's hot

Similar to Tutorial: Building a GraphQL API in PHP

More from Andrew Rota

Recently uploaded

Tutorial: Building a GraphQL API in PHP