GraphQL by PoP, a new GraphQL server in PHP

Leonardo Losoviz

GraphQL is great!

But...

No under/over fetching of data

Single endpoint

Query mirrors structure of components (React, Vue)

Easy for client-side developers!

GraphQL is still lacking!

No HTTP/Server-side caching

Dependant on tooling (eg: GraphiQL)

Federation?

Difficult for back-end developers!

General impressions

👍

👎

Declarative way to define the data model

Declarative way to duplicate the data model

Extensible: type, enum, interface, extend, directive, tooling

Extensible? single location, union, directive, tooling, bureaucratic

Versioning, documentation, type validation

Verbose, limited, RESTy, reinvents the wheel

Incremental adoption

Non-comprehensive

👩🏻‍🔧

How can we improve GraphQL?

Intro to GraphQL by PoP

An implementation of a GraphQL server in PHP

An implementation of an extended GraphQL spec, providing additional features

and...

Classic GraphQL

Extended GraphQL

🤔

How does it work?

Components as architectural foundation

The relationships across entities in the data model are modeled NOT through a graph, but through components...

...but a graph results naturally from the component model

author

comments

author

post

Digging deeper

Detailed description of the architecture:

🚀

Let's explore the Features*

*“XT”: it applies to Extended GraphQL.

Otherwise, it applies to both modes.

TL;DR: these features++

HTTP Caching

Federated/Decentralized

One-graph from multiple sources

Fast and efficient (no N+1 problem!)

Composable elements (no need for custom back-end coding)

Gateway: Integrate with APIs in back/front-end

100% spec compliant

No re-inventing anything

There is no creeping business logic

There is no creeping CMS logic (eg: authentication, CRUD operations, validations)

It works with standards (eg: HTTP caching)

Principled GraphQL

All of  GraphQL's principles* are already part of the architecture

*A list of 10 best practices for creating, maintaining, and operating a data graph

Enables HTTP/Server-side caching

Simplifies visualization/execution of queries (straight in the browser, without any client)

GET when it's a GET, POST when it's a POST, pass variables through URL params

/?query=query&variable=value&fragment=fragmentQuery
/?query=field(args)@alias<directive(args)>

URL-based Queries

XT

/?
query=
  field(
    args
  )@alias<
    directive(
      args
    )
  > 

Syntax: Easy to read and write as a URL param

Multi-line: Copy/pasting in Firefox works straight!

/?
query=
  posts(
    limit: 5
  )@posts.
    id|
    date(format: d/m/Y)|
    title<
      skip(if: false)
    >

URL-based Queries

XT

/?
query=
  posts(
    ids: [1, 1499, 1178],
    order: $order
  )@posts.
    id|
    date(format: d/m/Y)|
    title<
      skip(if: false)
    >|
    --props&
order=title|ASC&
props=
  url|
  author.
    name|
    url

(key:value) : Arguments

[key:value] or [value] : Array

$ : Variable

@ : Alias

. : Advance relationship

| : Fetch multiple fields

<...> : Directive

-- : Fragment

URL-based Queries

XT

Dynamic schema

/?query=fullSchema

Because it is generated from code, different schemas can be created for different use cases, from a single source of truth

The schema is natively decentralized or federated, enabling different teams to operate on their own source code.

Schema generation

type Human {
  name: String
  appearsIn: [Episode]
  starships: [Starship]
}

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

type Starship {
  name: String
}
class HumanTypeResolver extends AbstractTypeResolver
{
  public function getTypeName(): string
  {
    return 'Human';
  }

  public function getSchemaTypeDescription(): ?string
  {
    return $this->translationAPI->__('Representation of a human');
  }

  public function getID($resultItem)
  {
    $human = $resultItem;
    return $human->ID;
  }

  public function getTypeDataLoaderClass(): string
  {
    return HumanTypeDataLoader::class;
  }
}

class HumanTypeDataLoader extends AbstractTypeQueryableDataLoader
{
  public function getObjects(array $ids): array
  {
    $humanTypeAPI = HumanTypeAPIFacade::getInstance();
    return $humanTypeAPI->getHumans(['include' => $ids]);
  }

  public function executeQuery($query, array $options = [])
  {
    $options['return-type'] = 'ids';
    $humanTypeAPI = HumanTypeAPIFacade::getInstance();
    return $humanTypeAPI->getHumans($query, $options);
  }
}

class HumanFieldResolver extends AbstractDBDataFieldResolver
{
  public const NEWHOPE = 'newhope';
  public const EMPIRE = 'empire';
  public const JEDI = 'jedi';

  public static function getClassesToAttachTo(): array
  {
    return array(
      HumanTypeResolver::class,
    );
  }

  public static function getFieldNamesToResolve(): array
  {
    return [
      'name',
      'appearsIn',
      'starship',
    ];
  }

  public function getSchemaFieldType(TypeResolverInterface $typeResolver, string $fieldName): ?string
  {
    $types = [
      'name' => SchemaDefinition::TYPE_STRING,
      'appearsIn' => SchemaDefinition::TYPE_ENUM,
      'starship' => SchemaDefinition::TYPE_ID,
    ];
    return $types[$fieldName] ?? parent::getSchemaFieldType($typeResolver, $fieldName);
  }

  public function addSchemaDefinitionForField(array &$schemaDefinition, TypeResolverInterface $typeResolver, string $fieldName): void
  {
    switch ($fieldName) {
      case 'appearsIn':
        $schemaDefinition[SchemaDefinition::ARGNAME_ENUMVALUES] = [
          self::NEWHOPE,
          self::EMPIRE,
          self::JEDI,
        ];
        break;
    }
  }

  public function getSchemaFieldDescription(TypeResolverInterface $typeResolver, string $fieldName): ?string
  {
    $translationAPI = TranslationAPIFacade::getInstance();
    $descriptions = [
      'name' => $translationAPI->__('Name of the human'),
      'appearsIn' => $translationAPI->__('In what film the human appears'),
      'starship' => $translationAPI->__('Human\'s starship'),
    ];
    return $descriptions[$fieldName] ?? parent::getSchemaFieldDescription($typeResolver, $fieldName);
  }

  public function resolveValue(TypeResolverInterface $typeResolver, $resultItem, string $fieldName, array $fieldArgs = [], ?array $variables = null, ?array $expressions = null, array $options = [])
  {
    // It receives a Human object
    $human = $resultItem;
    switch ($fieldName) {
      case 'name':
        return $human->name;
      case 'appearsIn':
        return $human->episode;
      case 'starship':
        // It returns a Starship ID, not an object!
        return $human->starship;
    }

    return parent::resolveValue($typeResolver, $resultItem, $fieldName, $fieldArgs, $variables, $expressions, $options);
  }

  public function resolveFieldTypeResolverClass(TypeResolverInterface $typeResolver, string $fieldName, array $fieldArgs = []): ?string
  {
    switch ($fieldName) {
      case 'starship':
        return StarshipTypeResolver::class;
    }

    return parent::resolveFieldTypeResolverClass($typeResolver, $fieldName, $fieldArgs);
  }
}

The schema is automatically generated by traversing the relationships among all types

Resolvers

Type Resolvers

Mutation Resolvers

Type DataLoaders

Directive Resolvers

Field Resolvers

/?
postId=1&
query=
  post($postId).
    date(d/m/Y)|
    title<
      skip(false)
    >

Skip argument names

Have field and directive argument names deduced from the schema

/?
postId=1&
query=
  post(id:$postId).
    date(format:d/m/Y)|
    title<
      skip(if:false)
    >

=

XT

1. /?query=not(true)
2. /?query=or([1,0])
3. /?query=and([1,0])
4. /?query=if(true, Show this text, Hide this text)
5. /?query=equals(first text, second text)
6. /?query=isNull(),isNull(something)
7. /?query=sprintf(%s API is %s, [PoP, cool])
8. /?query=context

Operators and Helpers

Availability of all operators and functions provided by the language (PHP) as fields

Can define any custom helper functionality

XT

/?query=
  post(
    id: arrayItem(
      posts(
        limit: 1,
        order: date|DESC
      ), 
    0)
  )@latestPost.
    id|
    title|
    date

Composable fields...

The value from a field is the input to another one

No limit how many levels deep

If it contains (), it is a field (eg: posts() vs posts)

XT

...with Operators

No more RESTy data model

Composable elements: No need for custom code in resolvers

/?
format=Y-m-d&
query=
  posts.
    if (
      has-comments(), 
      sprintf(
        "This post has %s comment(s) and title '%s'", [
          comments-count(),
          title()
        ]
      ), 
      sprintf(
        "This post was created on %s and has no comments", [
          date(format: if(not(empty($format)), $format, d/m/Y))
        ]
      )
    )@postDesc

XT

/?query=
  posts.
    title|
    featuredimage<
      skip(if:isNull(featuredimage()))
    >.
      src

...in directive arguments

The directive can be evaluated against the object, granting it a dynamic behavior

XT

/?
format=Y-m-d&
query=
  posts.
    sprintf(
      "This post has %s comment(s) and title '%s'", [
        comments-count(),
        title()
      ]
    )@postDesc<include(if:has-comments())>|
    sprintf(
      "This post was created on %s and has no comments", [
        date(format: if(not(empty($format)), $format, d/m/Y))
      ]
    )@postDesc<include(if:not(has-comments()))>

...in directive arguments

Retrieve data for an object only if it satisfies a certain condition, or customize its properties

XT

/?query=
  posts.
    title|
    featuredimage?.
      src

Skip output if null

Exactly same result as doing <skip(if(isNull(...)))>

? : Add after the field to skip its output if null

XT

/?query=
  echo([
    [banana, apple],
    [strawberry, grape, melon]
  ])@fruitJoin<
    forEach<
      applyFunction(
        function: arrayJoin,
        addArguments: [
          array: %value%,
          separator: "---"
        ]
      )
    >
  >

Composable directives

A directive can change/prepare the context for its nested directives

Unlimited levels deep

Directive <forEach> unpacks array items for its nested directive <applyFunction> to apply operator arrayJoin on each, then packs them into an array again

XT

/?query=
  echo([
    [
      text: Hello my friends,
      translateTo: fr
    ],
    [
      text: How do you like this software so far?,
      translateTo: es
    ],
  ])@translated<
    forEach<
      advancePointerInArray(
        path: text,
        appendExpressions: [
          toLang:extract(%value%,translateTo)
        ]
      )<
        translate(
          from: en,
          to: %toLang%,
          oneLanguagePerField: true,
          override: true
        )
      >
    >
  >

Directive expressions

%...% : Expression

Can be pre-defined (%value% in <forEach>)

Can define on-the-fly (%toLang%)

They are variables used by directives to communicate with each other

XT

//1. Operators have max-age 1 year
/?query=
  echo(Hello world!)

//2. Most fields have max-age 1 hour
/?query=
  echo(Hello world!)|
  posts.
    title

//3. Nested fields also supported
/?query=
  echo(posts())

//4. "time" field has max-age 0
/?query=
  time

//5. To not cache a response:
//a. Add field "time"
/?query=
  time|
  echo(Hello world!)|
  posts.
    title

//b. Add <cacheControl(maxAge:0)>
/?query=
  echo(Hello world!)|
  posts.
    title<cacheControl(maxAge:0)>

HTTP Caching

Response contains Cache-Control header with max-age

Max-age values are configured field by field

Response max-age is the lowest max-age among all requested fields

//1. Standard behaviour
/?query=
  posts.
    excerpt

//2. New feature not yet available
/?query=
  posts.
    excerpt(length:30)

//3. New feature available under 
// experimental branch
/?query=
  posts.
    excerpt(
      length:30,
      branch:experimental
    )

Many resolvers per field

Customize data model for client/project

Autonomous teams, avoid bureaucracy

Rapid iteration, quick bug fixing

Field-based versioning

/?query=
  me.
    name

Validate user state/roles

Fields can be made available only if user is logged-in, or has a specific role

When validation fails, the schema can be set to either show an error or hide the field

The schema can be public/private at the same time, depending on the user

/?query=
  posts.
     author.
       posts.
         comments.
           author.
             id|
             name|
             posts.
               id|
               title|
               url|
               tags.
                 id|
                 slug

O(n) time complexity

To resolve the query graph (n: #nodes)

N+1 problem avoided by architectural design

Feasible to resolve deeply-nested graphs

// The Google Translate API is called once,
// containing 10 pieces of text to translate:
// 2 fields (title and excerpt) for 5 posts
/?query=
  posts(limit:5).
    --props|
    --props@spanish<
      translate(en,es)
    >&
props=
  title|
  excerpt

// Here there are 3 calls to the API, one for
// every language (Spanish, French and German),
// 10 strings each, all calls are concurrent
/?query=
  posts(limit:5).
    --props|
    --props@spanish<
      translate(en,es)
    >|
    --props@french<
      translate(en,fr)
    >|
    --props@german<
      translate(en,de)
    >&
props=
  title|
  excerpt

Efficient directive calls

Directives receive all their affected objects and fields together, for a single execution

//1. <translate> calls the Google Translate API
/?query=
  posts(limit:5).
    title|
    title@spanish<
      translate(en,es)
    >
    
//2. Translate to Spanish and back to English
/?query=
  posts(limit:5).
    title|
    title@translateAndBack<
      translate(en,es),
      translate(es,en)
    >
    
//3. Change the provider through arguments
// (link gives error: Azure is not implemented)
/?query=
  posts(limit:5).
    title|
    title@spanish<
      translate(en,es,provider:azure)
    >

Interact with APIs...

...from the back-end

/?query=
echo([
  usd: [
    bitcoin: extract(
      getJSON("https://api.cryptonator.com/api/ticker/btc-usd"), 
      ticker.price
    ),
    ethereum: extract(
      getJSON("https://api.cryptonator.com/api/ticker/eth-usd"), 
      ticker.price
    )
  ],
  euro: [
    bitcoin: extract(
      getJSON("https://api.cryptonator.com/api/ticker/btc-eur"), 
      ticker.price
    ),
    ethereum: extract(
      getJSON("https://api.cryptonator.com/api/ticker/eth-eur"), 
      ticker.price
    )
  ]
])@cryptoPrices

Interact with APIs...

...from the client-side

XT

//1. Get data from a REST endpoint
/?query=
  getJSON("https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions")@userEmailLangList
    
//2. Access and manipulate the data
/?query=
  extract(
    getJSON("https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions"),
    email
  )@userEmailList
  
//3. Convert the data into an input to another system
/?query=
  getJSON(
    sprintf(
      "https://newapi.getpop.org/users/api/rest/?query=name|email%26emails[]=%s",
      [arrayJoin(
        extract(
          getJSON("https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions"),
          email
        ),
        "%26emails[]="
      )]
    )
  )@userNameEmailList

A single query can perform all required logic

Interact with APIs...

XT

/?query=
  echo([
    github: "https://api.github.com/repos/leoloso/PoP",
    weather: "https://api.weather.gov/zones/forecast/MOZ028/forecast",
    photos: "https://picsum.photos/v2/list"
  ])@meshServices|
  getAsyncJSON(getSelfProp(%self%, meshServices))@meshServiceData|
  echo([
    weatherForecast: extract(
      getSelfProp(%self%, meshServiceData),
      weather.periods
    ),
    photoGalleryURLs: extract(
      getSelfProp(%self%, meshServiceData),
      photos.url
    ),
    githubMeta: echo([
      description: extract(
        getSelfProp(%self%, meshServiceData),
        github.description
      ),
      starCount: extract(
        getSelfProp(%self%, meshServiceData),
        github.stargazers_count
      )
    ])
  ])@contentMesh

Create your content or service mesh

All services in one query

XT

// 1. Inspect services
/?query=
  meshServices

// 2. Retrieve data
/?query=
  meshServiceData

// 3. Process data
/?query=
  contentMesh

// 4. Customize data
/?query=
  contentMesh(
    githubRepo: "getpop/api-graphql",
    weatherZone: AKZ017,
    photoPage: 3
  )@contentMesh

Use custom fields to expose your data and create a single, comprehensive, unified graph

One-graph ready

// 1. Save services
/?query=
  --meshServices

// 2. Retrieve data
/?query=
  --meshServiceData

// 3. Process data
/?query=
  --contentMesh

// 4. Customize data
/?
githubRepo=getpop/api-graphql&
weatherZone=AKZ017&
photoPage=3&
query=
  --contentMesh

Query sections of any size and shape can be stored in the server

Persisted fragments

Automatically namespace types and interfaces

Namespaces

Normal schema

Namespaced schema

// Query data for a single resource
{single-post-url}/api/rest/?query=
  id|
  title|
  author.
    id|
    name

// Query data for a set of resources
{post-list-url}/api/rest/?query=
  id|
  title|
  author.
    id|
    name

Combine with REST

Get the best from both GraphQL and REST: query resources based on endpoint, with no under/overfetching

// Output as XML: Replace /graphql with /xml
/api/xml/?query=
  posts.
    id|
    title|
    author.
      id|
      name

// Output as props: Replace /graphql with /props
/api/props/?query=
  posts.
    id|
    title|
    excerpt

Output in many formats

Replace "/graphql" to output the data in a different format

/api/?query=
  posts.
     author.
       posts.
         comments.
           author.
             id|
             name|
             posts.
               id|
               title|
               url

Normalize data for client

Reduced output size when a same field is fetched multiple times

Just remove the "/graphql" bit from the URL

//1. Deprecated fields
/?query=
  posts.
    title|
    published

Handle issues by severity

Deprecated fields/directives (informative): To be replaced

Schema/Database warnings (non-blocking): issues on non-mandatory arguments

Query/Schema/Database errors (blocking): Use a wrong syntax, non-existing fields/directives, issues on mandatory arguments

//1. Deprecated fields
/?query=
  posts.
    title|
    published
    
//2. Schema warning
/?query=
  posts(limit:3.5).
    title
    
//3. Database warning
/?query=
  users.
    posts(limit:name()).
      title
      
//4. Query error
/?query=
  posts.
    id[book](key:value)
    
//5. Schema error
/?query=
  posts.
    non-existant-field|
    is-status(
      status:non-existant-value
    )
//1. Deprecated fields
/?query=
  posts.
    title|
    published
    
//2. Schema warning
/?query=
  posts(limit:3.5).
    title
    
//3. Database warning
/?query=
  users.
    posts(limit:name()).
      title
/?query=
  posts(limit:3.5).
    title

Type casting/validation

When an argument has its type declared in the schema, its inputs will be casted to the type

If the input and the type are incompatible, it ignores setting the input and throws a warning

/?query=
  post(divide(a,4)).
    title

Issues bubble upwards

If a field or directive fails and it is input to another field, this one may also fail

/?query=
  echo([hola,chau])<
    forEach<
      translate(notexisting:prop)
    >
  >

Path to the issue

Issues contain the path to the nested field or directive were it was produced

/?
actions[]=show-logs&
postId=1&
query=
  post($postId).
    title|
    date(d/m/Y)

Log information

🏋🏻‍♀️

Let's implement some use case

TL;DR: problems considered difficult become easy to solve

Use case to implement

Create an automated email-sending service. Data comes from 3 sources:

1. REST API to fetch the recipients (email, lang)

2. REST API to fetch client data (email, name)

3. Blog posts published in your website

The email needs to be customized:

1. Greeting the person by name

 

2. Translating the content to their language

Solution for use case

/?
postId=1&
query=
  post($postId)@post.
    content|
    date(d/m/Y)@date,
  getJSON("https://newapi.getpop.org/wp-json/newsletter/v1/subscriptions")@userList|
  arrayUnique(
    extract(
      getSelfProp(%self%, userList),
      lang
    )
  )@userLangs|
  extract(
    getSelfProp(%self%, userList),
    email
  )@userEmails|
  arrayFill(
    getJSON(
      sprintf(
        "https://newapi.getpop.org/users/api/rest/?query=name|email%26emails[]=%s",
        [arrayJoin(
          getSelfProp(%self%, userEmails),
          "%26emails[]="
        )]
      )
    ),
    getSelfProp(%self%, userList),
    email
  )@userData,
  self.
    post($postId)@post<
      copyRelationalResults(
        [content, date],
        [postContent, postDate]
      )
    >|
    self.
      getSelfProp(%self%, postContent)@postContent<
        translate(
          from: en,
          to: arrayDiff([
            getSelfProp(%self%, userLangs),
            [en]
          ])
        ),
        renameProperty(postContent-en)
      >|
      getSelfProp(%self%, userData)@userPostData<
        forEach<
          applyFunction(
            function: arrayAddItem(
              array: [],
              value: ""
            ),
            addArguments: [
              key: postContent,
              array: %value%,
              value: getSelfProp(
                %self%,
                sprintf(
                  postContent-%s,
                  [extract(%value%, lang)]
                )
              )
            ]
          ),
          applyFunction(
            function: arrayAddItem(
              array: [],
              value: ""
            ),
            addArguments: [
              key: header,
              array: %value%,
              value: sprintf(
                string: "<p>Hi %s, we published this post on %s, enjoy!</p>",
                values: [
                  extract(%value%, name),
                  getSelfProp(%self%, postDate)
                ]
              )
            ]
          )
        >
      >|
      self.
        getSelfProp(%self%, userPostData)@translatedUserPostProps<
          forEach(
            if: not(
              equals(
                extract(%value%, lang),
                en
              )
            )
          )<
            advancePointerInArray(
              path: header,
              appendExpressions: [
                toLang: extract(%value%, lang)
              ]
            )<
              translate(
                from: en,
                to: %toLang%,
                oneLanguagePerField: true,
                override: true
              )
            >
          >
        >|
        self.
          getSelfProp(%self%,translatedUserPostProps)@emails<
            forEach<
              applyFunction(
                function: arrayAddItem(
                  array: [],
                  value: []
                ),
                addArguments: [
                  key: content,
                  array: %value%,
                  value: concat([
                    extract(%value%, header),
                    extract(%value%, postContent)
                  ])
                ]
              ),
              applyFunction(
                function: arrayAddItem(
                  array: [],
                  value: []
                ),
                addArguments: [
                  key: to,
                  array: %value%,
                  value: extract(%value%, email)
                ]
              ),
              applyFunction(
                function: arrayAddItem(
                  array: [],
                  value: []
                ),
                addArguments: [
                  key: subject,
                  array: %value%,
                  value: "PoP API example :)"
                ]
              ),
              sendByEmail
            >
          >

Digging deeper

Step-by-step description of the solution:

🛫

What's coming next

Mutations

Can concatenate operations, nest results, add feedback loops, keep querying data

/?query=
  addPost($title, $content).
    addComment($comment1)|
    addComment($comment2).
      author<sendConfirmationByEmail>.
        followers<notifyByEmail, notifyBySlack>

Can be added anywhere on the query, not only on the root

👩🏻‍🔧

Installation details

Open source code

License: MIT

Many repos

Technology stack

Implemented in PHP

It is CMS-agnostic: It can work with any CMS or framework (WordPress, Symfony, Laravel, Joomla, Drupal)

So far implemented contracts for WordPress

Installing for WordPress

"require": {
  "getpop/graphql": "dev-master",
  "getpop/engine-wp": "dev-master",
  "getpop/posts-wp": "dev-master",
  "getpop/users-wp": "dev-master",
  "getpop/comments-wp": "dev-master",
  "getpop/pages-wp": "dev-master",
  "getpop/postmedia-wp": "dev-master",
  "getpop/taxonomies-wp": "dev-master"
}

1. Add to composer.json

2. Run composer update

3. Run composer install

It relies on Composer for installation

Is it ready yet?

Project status

Code: stable and working well (no version 1.0 released yet though... so use in PROD at your own risk ☠️)

Documentation: not much yet

Test units: pretty much nothing yet

With your involvement, version 1.0 can be released sooner

Become involved!

Monetary sponsors

🎅🏼

👩🏼‍💻

Code/Unit tests contributors

👨🏻‍🏫

Documentation contributors

If you like it, share it with your friends and colleagues

Spread the word!

🙏

⛹🏻‍♀️

It's time to go play!

Thanks!

👋

Leonardo Losoviz

Intro to “GraphQL by PoP”, a new GraphQL server in PHP

By Leonardo Losoviz

Intro to “GraphQL by PoP”, a new GraphQL server in PHP

“GraphQL by PoP” is a brand-new GraphQL server in PHP, CMS-agnostic (adapters currently implemented for WordPress), which implements the GraphQL spec and expands it with several additional features

  • 273
Loading comments...

More from Leonardo Losoviz