Talk about GraphQL and its implementation with Symfony using overblog/GraphQLBundle at Symfony User Group Berlin Meetup on 26.04.2017

1. GRAPHQL

2. ABOUT ME
Bernd Alter
CTO of VOTUM GmbH
bernd.alter@votum.de
@bazoo0815

3. AGENDA
Basic introduction to GraphQL
Schema definition
Queries & Mutations
GraphiQL - the GraphQL GUI
Keyset pagination
Experiences, tips & tricks

4. DEFINITION
GraphQL vs Relay vs React
React = open-source JS library for building user interfaces
Relay = client-side application framework based on React
GraphQL = server-side query language implementation

5. GraphQL server Data sourcesVarious client apps
JSON
payload
GraphQL
queries
WHAT IS GRAPHQL?
query language
created by Facebook 2012
open-source'd in 2015

6. KEY FEATURES
strongly typed objects and fields
highly customizable queries
nested/parallel objects in a single request
no versioning necessary
data aggregation from multiple sources
integrated GUI with auto-completion & error check

7. GRAPHQL IN SYMFONY
several bundles available
overblog/GraphQLBundle
suribit/GraphQLBundle
Youshido/GraphQLBundle
... (see links)
composer require overblog/GraphQLBundle
# also installs base bundle `webonyx/graphql-php`

8. GRAPHQL SCHEMA
Type (for fields/attributes)
Builder
Connection
Edges
Node
Cursor
Union
Interface
Resolver

9. SIMPLE TYPES
Type Example(s)
Int 1 25 432
Float 1.23 7.6
String "Any string"
Boolean true false
Enum 0 (=unknown)
1 (=male)
2 (=female)

10. SIMPLE TYPES (EXAMPLE)
Article:
type: object
fields:
id:
type: Int! <- Exclamation mark = required/not- null
headline:
type: String!
description: "A description can be added anywhere"
featured:
type: Boolean

11. SPECIAL TYPE: ID
global identifier
base64-encoded string
unique application-wide(!)
Article:
type: object
fields:
id:
type: ID! (instead of Int!)
Example:
"YXJ0aWNsZToxMjY=" -> "article:126"

12. BUILDER
reusable and configurable 'templates' or 'functions'
field builder (builder)
argument builder (argsBuilder)

13. FIELD BUILDER (EXAMPLE)
#app/config/config.yml
overblog_graphql:
#...
definitions:
#...
builders:
field:
- alias: "RawId"
class: "MyBundleGraphQLFieldRawIdField"
<?php
class RawIdField implements MappingInterface
{
public function toMappingDefinition(array $config)
{
$name = $config[ 'name'] ?? 'id';
$type = $config[ 'type'] ?? 'Int!';
return [
'description' => 'The raw ID of an object' ,
'type' => $type,
'resolve' => '@=value.' . name,
];
}
}
# in schema definition
Article:
type: object
fields:
rawId:
builder: RawId
...
Video:
type: object
fields:
rawId:
builder: RawId
builderConfig:
name: idVideo
type: String
...

14. NESTING OF OBJECTS
Article:
type: object
fields:
id:
type: ID!
...
artists:
type: "[Artist]"
images:
type: "[Image]"
Artist:
type: object
fields:
id:
type: ID!
name:
type: String!
Image:
type: object
fields:
id:
type: ID!
url:
type: String!

15. CONNECTIONS
lists of objects
used for cursor-based (or keyset) pagination
can have arguments
(for filtering, sorting, aggregation)
connection: {
edges: [
{
node: {
id
...
}
}
],
pageInfo: {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
}

16. CONNECTIONS (EXAMPLE)
ArticleConnection :
type: relay-connection
config:
nodeType: Article
allArticles:
type: ArticleConnection
argsBuilder: ConnectionArgs
args:
artist:
type: Int
description: "Artist id, e.g. 525338 for artist 'Rihanna'"
dateFrom:
type: String
description: "Filter connection by date (greater than or equal)"
dateTo:
type: String
description: "Filter connection by date (lower than or equal)"
resolve: "@=resolver('article_connection', [args])"

17. UNIONS
Use it to ...
... handle multiple object types in one field
... deal with heterogeneous structures

18. UNIONS: EXAMPLE
Schema/Query
Content:
type: union
config:
types: [Article,Product]
Article:
type: object
fields:
headline:
type: String!
Product:
type: object
fields:
title:
type: String!
query Root {
content(artist: "Rihanna") {
... on Article {
__typename
id
headline
}
... on Product {
__typename
id
title
}
}
}

19. UNIONS: EXAMPLE
Response
{
"data": {
"content": [
{
"__typename": "Product",
"id": "QXJ0aWNsZToyMzc4OTI=" ,
"title": "Unapologetic"
},
{
"__typename": "Article",
"id": "QXJ0aWNsZToyMzgyMjg=" ,
"headline": "ECHO 2017: Rihanna ist fÃŒr den deutschen Musikpreis nominiert"
},
{
"__typename": "Product",
"id": "QXJ0aWNsZToyMzgyMjU=" ,
"title": "ANTI"
},
{
"__typename": "Product",
"id": "QXJ0aWNsZToyMzgyMjY=" ,
"title": "Diamonds"
}
]
}
}

20. INTERFACES
just like in PHP
objects can have multiple interfaces
not cascading
object can implement interfaces
interface cannot implement interfaces
SeoContent:
type: interface
config:
fields:
seoKeywords:
type: String
Article:
type: object
config:
interfaces: [SeoContent, Node]
fields:
id:
type: ID!
headline:
type: String!
seoKeywords:
type: String
# NOT POSSIBLE
OtherInterface:
type: interface
config:
interfaces: [SeoContent]

21. RESOLVER
connecting objects/fields to methods
# schema definition in Query.types.yml
Query:
type: object
config:
fields:
articles:
type: ArticleConnection
args:
type:
type: ArticleType
artist:
type: Int
resolve: "@=resolver('article_connection', [args])"

22. RESOLVER
# config in services.yml
services:
my.graphql.resolver.content:
class: MyGraphQlBundle ResolverContentResolver
tags:
- { name: overblog_graphql.resolver, alias: "root_query", method: "resolveRootQuery" }
- { name: overblog_graphql.resolver, alias: "article", method: "resolveArticle" }
- { name: overblog_graphql.resolver, alias: "article_connection" , method: "resolveArticleConnection" }
# in class MyGraphQlBundleResolverContentResolver
<?php
...
/**
* @param Argument $argument
* @return ArticleConnectionObject
*/
public function resolveArticleConnection (Argument $argument)
{
if (isset($argument['artist']) {
$filters[] = $this->createArtistFilter($argument);
}
/** other code ... */
return $this->getArticleConnection($filters);
}

23. REQUESTS
Queries
Mutations
Fragments
Variables

24. QUERY
read-only request
highly customizable
nesting of objects
any combination of fields
multiple resources in one request
query Root {
article(id: 123) {
id
headline
}
videos(first: 5) {
title
url
}
artist(name: "Rihanna") {
name
articles( first: 2, sortBy: "date")
headline
}
}
}

25. MUTATION
data changing request
requires payload object
# Request
mutation myLogin($input: CredentialsInput!) {
loginUser(input: $input) {
userName
loginSuccessful
}
}
# Payload (variables)
{
"input": {
"email": "me@email.com" ,
"password": "123456",
}
}
# Response
{
"data": {
"loginEmailUser" : {
"userName": "Max",
"loginSuccessful" : true
}
}
}

26. FRAGMENTS
reusable request pieces
nesting allowed
beware of (infinite) loops!
query Root {
article(id: 123) {
...articleFragment
}
artist(name: "Rihanna") {
name
articles( first: 2, sortBy: "date")
...articleFragment
}
}
}
fragment articleFragment on Article {
id
headline
}
fragment artistFragment on Artist {
name
articles {
...articleFragment
}
}
fragment articleFragment on Article {
id
headline
artist {
...artistFragment
}
}

27. VARIABLES
needed for payload objects (see mutations)
reusable values/parameters

28. GRAPHIQL
built-in GUI
available in dev-
mode under
auto-generated docs
sidebar
good demo:
/graphiql
swapi-
graphql

29. GRAPHIQL
DEMO!

30. KEYSET PAGINATION
WHAT IS IT ABOUT?
usually offset is used
overhead of read-ahead
using cursor containing
required information
only read what you need
# OFFSET
SELECT * FROM articles
ORDER BY date DESC, id DESC
LIMIT 10 OFFSET 50;
# KEYSET
# cursor: date=2017-03-29, id=165
SELECT * FROM articles
WHERE date < :cursor_date
OR (date = :cursor_date AND id < :cursor_id)
ORDER BY date DESC, id DESC
LIMIT 10;

31. KEYSET PAGINATION
OFFSET VS KEYSET
Source: http://blog.novatec-gmbh.de/art-pagination-offset-vs-value-based-paging/

32. KEYSET PAGINATION
Advantages Disadvantages
'real' pagination no page browsing
(only previous and next)
better performance hard(er) to implement
good for endless scrolling

33. PROBLEMS / PITFALLS
resolvers are atomic
agnostic to parent/child objects
(potential) need to forward settings
loss of control about queries
can lead to performance problems
danger of cyclic/recursive queries

34. NOTES, TIPS & TRICKS
possible to wrap (existing) REST API in GraphQL
prepare application to deal with pre-flight request
(CORS, HTTP method OPTIONS)
add caching (on object level)
filenames for type definitions have to end with .types.yml
use aliases for usage of same object/field in query
query Root {
article(artist: "Rihanna") {
id
headline
}
otherArticle: article(artist: "Kasabian") {
id
headline
}
}

35. LINKS: DOCUMENTATION
Official website:
Dra RFC Specification (10/2016)
GraphQL: A data query language
GraphQL Schema Language Cheat Sheet
Connections explained:
http://graphql.org/
http://facebook.github.io/graphql/
https://code.facebook.com/posts/1691455094417024
https://wehavefaces.net/graphql-shorthand-notation-cheatsheet-
17cd715861b6
https://dev-blog.apollodata.com/explaining-graphql-connections-
c48b7c3d6976

36. LINKS: SYMFONY & OTHER
IMPLEMENTATIONS
Reference implementation in PHP:
Symfony bundle:
GraphQL with PHP and the Symfony Framework:
List of implementations for various languages:
https://github.com/webonyx/graphql-php
overblog/GraphQLBundle
https://www.symfony.fi/entry/graphql-with-php-and-the-symfony-
framework
https://github.com/chentsulin/awesome-graphql

37. LINKS: VIDEOS
by Lee Byron
by Steven Luscher
Exploring GraphQL at react-europe 2015
Zero to GraphQL in 30 Minutes

38. LINKS: KEYSET PAGINATION
Slides: Pagination done the right way (by Markus Winand):
The art of pagination - Offset vs. value based paging:
https://www.slideshare.net/MarkusWinand/p2d2-
pagination-done-the-postgresql-way
http://blog.novatec-gmbh.de/art-pagination-offset-vs-value-
based-paging/

39. THANKS FOR LISTENING