Building a GraphQL API in PHP with GraphQLite - GraphQL Hong Kong

thank you very much okay so let's get

started

so i already introduced my talk uh

i'm gonna share my screen here

and yeah so basically there will be

three parts

in this talk the first part is about the

ecosystem the graphql ecosystem in php

it does exist and it is actually quite

large

then how to choose the right library for

your project

if you're doing some php and finally a

demo

of graphqlite

so um about the ecosystem

well i'm sure all of you already know

that when you're doing graphql you need

a graphql client in the browser and a

graphql middleware

on the server side and you have actually

implemented

implementations of graphql middlewares

in all in many languages

of course not js it started there but

also php

java c-sharp or whatever

today we're going to be zooming on php

and if we have a look at the php

graphical middlewares there are actually

two kinds

of uh such middlewares and i will split

them

a bit arbitrarily arbitrarily in two

uh sections ones that i call core

libraries

and another that i call dropper

libraries and

core libraries are actually middlewares

that are

quite low level they are used to parse

the graphical queries to serve

the the the response in json

they are really powerful but they are

kind of

hard to use the the developer the

developer experience

to use such uh library is

kind of poor they're hard to use and so

on top

of those core libraries people build

wrapper libraries which are actually

libraries that use core libraries

and that are more high level more

opinionated

certainly easier to use maybe not that

not as much powerful as the call library

but basically most of the time when you

are doing an application

you will be choosing a verbal diagram

right

in php if we have a look at core

libraries

there are not that many of them there

are actually two right now

there is webinaics which is the de facto

standard in php

almost everybody is using webinx and

then there is a newcomer that is called

ray welty which is developed by

some russian guys it's an active

development

it looks really promising there is no

solid documentation yet

so uh right now if you

need a co-library definitely go to

webonix

but keep an eye and high on

railway there was in the past

more libraries here there was one was

that was called

ushido that has been abandoned in favor

of weaponix so

right now it's pretty much robotics if

you want a core library

and then on top of this core library

there are wrapper libraries and there

are many of them

and today uh

all those libraries are using webonix

under the hood

okay it's a wrapper around webonix to

make it easier to use

so basically we have api platform and

the overblock graphql bundles that are

really

used with the symphony framework if

you're doing laravel you can use

a library called lighthouse i will be

presenting those a bit later

if you're doing um

[Music]

what uh if you're using a cms like

wordpress or drupal

wordpress and drupal have modules

to plug to present a graphql api

so if you want to do a headless cms it's

quite easy using

wordpress or drupal and adding a

a graphql module on them and then there

is graphqlite

which i've been altering for the last

two years and which is

a framework agnostic because you can use

it

whatever the framework you use

let's make a quick look uh a quick zoom

on

webonix okay so webonix it is the core

library here

and how does it look like coding with

webox well

here i've got a graphql type okay

and basically this type is a story it

has

fields with which all have types

building that in webmix the card would

look

like this okay it's kind of verbose

and as i told you the developer

experience is not that great but

basically

i'm creating a type it's its name is

history here and i've got a number of

fields that are declared here with the

type of the field the description

if i've got arguments the arguments are

declared here

and finally i have a resolver that will

be called

when i query this fill the resolver is

called

to fetch the data

this is really verbals right

and also it might look a bit like

some libraries some graphql libraries in

javascript especially if you have been

doing

been using express graphql

webonix started by mimicking a lot what

facebook was doing in its own javascript

library if i want to declare

a query well i'm creating a type query

whose fields are here it's actually

exactly the same thing as defining a

type

because in graphql a query is a field on

the

type whose name is query and finally

if i want to resolve a query i can

compose the exit with query static

method

plus in parameters the schema the schema

is

an object containing all the types that

i have declared

i'm passing in the query string so the

graphical query and it will return an

array that that

i can cast to json and return to the

client

so this is the the experience

you're getting when you're using webinx

directly

right and the problem with this approach

is that it

actually requires a lot of work

to set up a great graphql api

obviously there are games to use graphql

versus rest

its queries are client-driven

it has introspection you can see the

schema from the client

it has three types which is definitely

one of the

really cool features but if it is too

much of pain to

um to put the api in place

uh well uh it maybe won't be worth it

so what we are going to do is we are

going to use a wrapper library

which is easier to work with to

offset the gains versus the costs

and to make it worthwhile to use

graphical

now if we need to choose a proper

library

well there are basically two kinds of

such libraries there are

schema first libraries and code first

libraries

in the schema first dropper library

basically

your task as a developer will be to

write the

graphql schema and then the job of the

library

will be from the schema to build

to to find a way to link the schema

to the ph key code on the other end if

you are using a code first approach

you will be designing objects and then

the job of the library will be to

generate the schema

from the classes and the objects you've

been

designing so uh

and basically when you are using a

language

that is loosely typed you tend to have

libraries that are schema first if you

are doing javascript you will find a lot

of schemas libraries

on the other end if you are using a

strictly typed language

like java you will find a lot of code

first libraries

php sits a bit in the middle because it

is

optionally tight you can have types but

you're not forced to

and so you have the two kinds of

libraries out there and

uh basically uh in the schema first

part you have uh overblog lighthouse

reality sciler

and the code first category api platform

graphical light

and get bob

let's make a quick zoom on lighthouse

okay so lighthouse

is a schema first library let's see how

it works

lighthouse is built on top of laravel

when you are using lighthouse what we

you are going to do

is you are going to design this

graphql schema

and basically you are going to annotate

this schema with directives okay this is

a directive

this is another directive and

these directives will be used uh by

lighthouse

to bind this schema to the database

model directly

uh basically under the hood lighthouse

is using yellow points

and yellow point is the orm of laravel

so basically if i'm using the

old directive

automatically lighthouse will put

the current user in the mcquery you can

do

quite powerful stuff with only

directives for instance the create

directive here

will create directly an object in

database

when you when you call critpost and it

will put a post directly into the

database and you can do validation

right here on each field

okay so it's very efficient

i mean you can build a complete

graphql api in very few lines of code

with this approach

also it is very very tied to laravel

and to eloquent which is the oram so if

you want

to do advanced things and if you don't

want to

to be too much tied to your database you

will have to write

a custom directive which is a bit of a

pain

but if you have a simple use case and

you only want to

back to to do quick by binding to a

database it is a great tool

okay one thing that is also interesting

it has support for subscriptions

which is uh so you can do real-time

graph you graphql can

can answer in real time which is not

that common in php

so that is lighthouse let's now make

a zoom on api platform so api platform

okay it is a code first library

in api platform the philosophy is the

opposite

you start by writing a php class

and then you're going to put annotations

on the class an api platform will read

the annotation

and generate the graphical schema for

you

okay um api platform was

first built with the rest philosophy in

mind

and uh what is kind of fun with the api

platform is that you can expose

quite easily both a rest api and a

graphql api

very few lines of code so you get both

kind of api

support using the same code

which is cool however

if you want to have a good control on

you the graphical schema that is

generated api platform

may not be the best uh the best

tool out there because the underlying

philosophy

is very much uh rest so you have credit

you have you can create read update and

delete the report

if you want to do some some other things

uh well it will be a bit harder to

customize

it has support for subscriptions too so

yeah so that was the zoom on lighthouse

and

api platform there are many also

libraries out there

and i've been preparing a few schemas

to help you decide what library you can

use

by answering a few questions so let's

jump into that

so basically if you want to pick a

graphical library

i think the first que and if you are

doing php

the first question you should ask is are

you developing

an application or a tool okay

so basically um

if you are

doing uh if you are developing a tool if

your model

is dynamic for instance if uh

you're sorry

if you are developing a cms and the end

user

can create a new content type you can

create new type

add new fields stuff like that then you

want to go for webinars

okay you want to go low level and build

your own tool

on it if you are developing an

application and you have a set of

classes

already well defined then you want to go

for a wrapper library then there is a

question

do you need subscriptions if you want to

do things

in real time then you have to pick

a library that supports subscriptions

there are not many out there

it's lighthouse api platform silo of all

webinars

otherwise you can choose any library

then there is another question which is

do you want

do you want to do do you want to use

relay on your front end if you are

using relay a relay imposes

a number of constraints of the on the

schemas that are generated

and not all the libraries out there have

support for

this kind of schema so if you want to do

to use relay you should definitely aim

for those libraries

maybe lighthouse and graphical bundles

finally depending on the framework you

are using

you will also have to to put to pick

one of those

libraries some libraries

are framework agnostics like webinarics

and graphic lite and you can use them

everywhere alright so

finally the last question do you prefer

a schema first or

a code first approach if you want

to go schema first pick one here

if you want to go code first pick one

here

and when you unsword all those questions

if you are lucky well you still have a

choice between one or two libraries

if you are unlucky there are no

libraries uh

answering you need for instance if you

want uh to do

to use a code first approach in laravel

and using subscriptions well

you can't basically

and but yes this

approach should help you choose uh one

of those libraries

okay and uh i try to be

not too much biased but yes of course i

i altered a graphic light and so well

now we will enter the third phase of

this talk

and i will be doing a quick demo about

graphic light

before doing the demo i will try to

explain you the philosophy

that drove a graphical light basically

my id was uh well let's imagine

you want to do a simple echo query

in php okay

if you want to do such a query

in graphql it will look like this i'm

creating a query type and basically

yes there is a echo it takes a message

it will return um well i

i'm doing an echo to build that

using webonix i would need to put cisco

i already presented it i need to put an

echo field

which returns a string that takes into

argument a string

and and that results by reading the

arguments and returning them

but if i want to write the same echo in

pure php

basically it only takes four lines

basically the function name could map

the query name in graphql the parameters

here could

map graphical arguments and the return

type is already defined

and then the body of the function is

actually my resolver

so what would be really cool

would be what if i was able to simply

put

a query annotation here

and well this query annotation

uh would automatically

tell my library graphically like in my

case

that this function should be actually

a graphical query expose it in graphql

that's it

and so that's the philosophy behind

graphqlite using annotations

and using the fact that php

is already typed and

basically taking php types and mapping

them

automatically to graphical types so

this is graphic light graphicalite is a

mapper between php types

and graphql types and

what is kind of fun is that it actually

plays quite nice with doctrine

okay doctrine is the orm

used by a symphony

and basically in doctrine you put

annotations in your php objects

and doctrine is doing a mapping between

php objects

and database tables and from the php

objects

it can generate the database model and

with graphilite we are doing the same

thing

we are starting from the php object and

we are generating a graphql schema

yeah so let's go for the live coding

quick note i already told it is

framework agnostic

you can use it starting from php 7.2

and it's based on webonix

now for the hard part for me

the demo yeah so we are going

to uh make a quick demo with a

marketplace and basically my marketplace

has companies and in each company

can have several products and we will be

focusing on this relationship between

companies and products

in the last uh in the next five minutes

right so

let's jump to the code here

i already did set up a

graphql a graphical light in

a symphony project the database is

already loaded

and i wrote a company controller okay so

it's actually a controller like like

like you can find some in nbc frameworks

except it is in the graphql controller

namespace

okay and if you want to put queries or

mutations

somewhere in your code you will put them

in a controller

so my controller is fed with a company

repository

the company repository is the object

that will access the database

okay and i have this

method which is called get companies

that takes

a search string and that will query the

database for the string and return the

results

what i'm going to do is i'm going to put

an annotation

here and

i'm going to put a query annotation to

tell graphic life okay

take this company's

[Music]

function and expose it in the graphql

schema

if i go in firefox here i've got a

graphical

test client setup so i'm going to

refresh

the page and oops

okay i'm getting an error let's make

a quick zoom on this error and basically

what graphicality is telling me is that

in the get companies method a type hint

is missing okay you remember

that php is optionally typed but graphql

must have types so when i'm using

graphqlite i must put type

into all my functions uh

all my queries here i did not define

any return type so i need to define one

so

i'm going to say company get companies

is returning an array of companies now i

have a problem

it's that php does not have the notion

of generics so i cannot say something

like okay it's an array of company

this is not valid php right so what i'm

gonna do

is i'm going to put an uh

a code a command in the php doc and

in the php dock i can put anything and

especially

i will give a type hint to uh

to graph the light and tell him that

this array is actually

an array of companies so let's go back

to firefox refresh the page

and oh i'm getting another error

okay let's zoom on this lever

it's error driven development i'm a big

fan of ever

driven development it works really well

no i and i actually tried to

make sure that all the error messages

are quite clear

it's really important and well

in your own code try uh to pay attention

on the other messages you are generating

you are doing

your future self favor uh yeah

so basically it's telling me that in get

companies

it cannot map the class company to a

known required type

what graduality is actually tell me

telling me is that i did not tell

him explicitly that company

is a graphical type and so to do that

i simply add an annotation which is the

type annotation

and the type annotation is

telling graphical life okay map this

class to a tie

of course a type must have some face so

i'm going to

put annotations in the in the gators

here and i'm going to say okay expose

id as a fill and name

as a field and maybe website

as a field too also notice that i'm

putting

the field annotation on getters i'm not

putting the annotation

on the properties the properties are are

private so i cannot access them directly

doctrine has annotation on properties

because

it is doing some black magic and

actually

accessing directly private properties

i'm not doing that in graphic light

okay so yes i must put the fill

annotation on the getters

so let's go back to

graphical i'm refreshing the page

i don't have any error so it looks good

and if i'm looking at writing a query

i can my company pool will just appear

and yeah i can do a search on any

companies containing the a

and i'm going to display the id and the

name

place the request and it is working and

if i'm

adding the website right

good so basically you can see that i

managed to create

a graphql api by basically adding three

annotations

query type and fill which is pretty cool

um and yeah

let's so far i only fetched

fields from companies so let's do some

binding with a product

so i'm going to go in the get products

getter and i'm gonna add a field on it

i'm gonna refresh the page

and i'm getting another evolve if i'm

zooming on this error

it is telling me that it cannot map the

product class

to a known graphical type okay we

already saw

this error two minutes ago so i'm pretty

sure you know what i should do i should

go in the product class

and instruct graphicalize that the

product

class is also a tie

and so i'm putting a type here and i'm

going to

put a field annotation

on the id on the name

on the price on the margin of the

product and

if i'm refreshing the page

yeah everything seems to be going great

and i can access the products

and access the id and the name of the

product

and it's working yeah

so that's it and basically

my job when i set up a graphql api

becomes adding a few annotations and

yeah

that's it

so yeah for the live demo

i won't be going any further i will be

presenting you very quickly a few

additional

features for instance if you want to put

to create a mutation you have a mutation

annotation

that can be used to create a mutation it

works exactly the same as

the query annotation works

there is a brilliant support for

authentication and authorization

that is plugged into your favorite

framework

laravel symphony whatever but basically

if you are using the right annotation

and passing the name of a write

well then this query will be

visible only if the user that is

currently logged

has this right you can also use the

right annotation and feels directly

you can even do fine-grained

authorization

if you want to say that some objects can

be seen but not others

in this example i've got an email field

from a user and basically i am saying

that i am looking at the component of

the

the user of the current user

and comparing it with the company of the

user that is logged

user here refers to the user that is

currently loaded

and basically this is saying i can see

the email of the people that are

in the same company as me i can see the

email of my colleagues

but i cannot see the email of someone

that is

not my colleague so with this security

annotation

we can have something that is going

quite deep

to do fine-grained authorization

another feature i like a lot is auto

wiring

uh basically here we are in a domain

object a product and uh

let's admit i want to compute the v80 of

a product

computing the v80 of a product can be

quite complicated

maybe i need to know uh the type of the

product the country the

uh the user is in so it can be difficult

and we typically won't do it in the

domain object but rather

rather we will call a service but you

when you are in a domain object

accessing services accessing services is

difficult and what we can do here is

auto wire called the auto wire ring and

basically graphic light will

automatically

inject when i'm calling the v80 field it

will automatically inject

from the dependency injection container

the service

the v80 service and i can use it

directly in the resolver here

so it enables me to access services and

from a domain object by passing those

services

in parameters of the resolver which is

kind of

kind of cool yeah there are many many

more features

available uh we have support for

validation

uh for uh indium types even if they

don't

exist in php file uploads um

what i invite you to do if you are

interested

in trying out graphqlite is

having a look at the documentation

everything is i hope clearly documented

and if you have any issue well you can

always

contact me either on

twitter directly or if you prefer

uh just open an issue

on the graphqlite repository yeah

so yeah that's repetitive let's wrap uh

this um this talk uh

basically uh doing graphql in php is

definitely possible

you have many possibilities out there uh

and this is

since graphql is pretty cool uh

well i definitely invite you to to try

it out

and uh that's it do you have any

questions

thanks so much david it was such

incredible talk

i really enjoyed it all the life current

day we were scared

yeah everything was incredible so that's

great uh so yeah

do yeah we have a question yes

uh so florian he's asking about

if graph graphic graph live

is is gonna support or is currently

supporting subscriptions

it is not currently supporting

subscriptions

i plan to add support for subscriptions

in the future maybe

not in the in the two coming months

because i want to

to release a version 4.1 of graphqlite

and i'm no subscriptions won't be part

of this release

but yes i would like to to work on that

for the end of the year definitely

definitely well that

that's that sounds super exciting i

guess and

i think i have another question because

i found

out super super interesting so i'd like

to understand like

like why do you why did you decide to

go and build this incredible technology

and what are kind of like the future

plans for for it

oh okay uh um

well when i started uh writing

graphically light it was

two years ago and basically you had only

two options at the time it was using

webonix directly

or uh using um

[Music]

using ushido which is a library that has

been abandoned

and basically they were really low level

libraries and they were hard to use

and i have this huge project for a

client of mine

uh we are just at the coding machine we

are doing mostly internet and extranet

applications and a client of mine

uh had uh this huge rest api

with a lot of end points and maybe read

on the end points

i wanted to do graphql because i knew

that

the flexibility of graph create would be

really really beneficial

for that client and uh the only option i

had was webonix which was

too hard to use uh and so i decided

i started writing a small library which

became a bit more complex

and uh i did two three versions of the

library and then i

i told myself okay uh i i must work on

it

really seriously put it on um

open source it and well that's how

graphic light

was born actually well that sounds that

sounds

so great and i think like thanks so much

for

contributing with the graphql community

in this case in the php because

yeah i think there are not so many

people that either they don't know that

they are able to do these or they

figure out they like realize that it's a

bit more difficult so it's even like a

start you know like to contribute so

i i i think like like like this is super

super super interested and i think like

a if the people they do know this

library they are going to start to use

it

they are going to like it and they are

going to like adopting their company so

um yeah thanks so much for sharing this

knowledge with us

you're welcome yeah

yeah thanks so much for like like like

like contacting us to

speak uh because it's it's been

difficult to find

kind of like people that they have

companies in hong kong although you are

not in hong kong right now but i

you're like really connected to the hong

kong community so

i am so so glad to have you here and

thanks so much and

i really really hope to see you soon

thank you very much okay david thanks

so up next so