simpod / graphql-utils

Set of utilities to power up your development with webonyx/graphql

PHP GraphQL Utils for graphql-php

Installation

Add as Composer dependency:

composer require simpod/graphql-utils

Features

Schema Builders

Instead of defining your schema as an array, use can use more objective-oriented approach. This library provides set of strictly typed builders that help you build your schema:

• EnumBuilder
• FieldBuilder
• InputFieldBuilder
• InputObjectBuilder
• InterfaceBuilder
• ObjectBuilder
• TypeBuilder
• UnionBuilder

ObjectBuilder and FieldBuilder

✔️ Standard way with webonyx/graphql-php

<?php

use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\ResolveInfo;

$userType = new ObjectType([
    'name' => 'User',
    'description' => 'Our blog visitor',
    'fields' => [
        'firstName' => [
            'type' => Type::string(),
            'description' => 'User first name'
        ],
        'email' => Type::string()
    ],
    'resolveField' => static function(User $user, $args, $context, ResolveInfo $info) {
        switch ($info->fieldName) {
            case 'name':
              return $user->getName();
            case 'email':
              return $user->getEmail();
            default:
              return null;
        }
    }
]);

✨ The same can be produced in objective way

<?php

use GraphQL\Type\Definition\ObjectType;
use GraphQL\Type\Definition\ResolveInfo;
use SimPod\GraphQLUtils\Builder\ObjectBuilder;

$userType = new ObjectType(
    ObjectBuilder::create('User')
        ->setDescription('Our blog visitor')
        ->setFields([
            FieldBuilder::create('firstName', Type::string())
                ->setDescription('User first name')
                ->build(),
            FieldBuilder::create('email', Type::string())->build(),
        ])
        ->setFieldResolver(
            static function(User $user, $args, $context, ResolveInfo $info) {
               switch ($info->fieldName) {
                   case 'name':
                     return $user->getName();
                   case 'email':
                     return $user->getEmail();
                   default:
                     return null;
               }
            }
        )
        ->build()
);

EnumBuilder

✔️ Standard way with webonyx/graphql-php

<?php

use GraphQL\Type\Definition\EnumType;

$episodeEnum = new EnumType([
    'name' => 'Episode',
    'description' => 'One of the films in the Star Wars Trilogy',
    'values' => [
        'NEWHOPE' => [
            'value' => 4,
            'description' => 'Released in 1977.'
        ],
        'EMPIRE' => [
            'value' => 5,
            'description' => 'Released in 1980.'
        ],
        'JEDI' => [
            'value' => 6,
            'description' => 'Released in 1983.'
        ],
    ]
]);

✨ The same can be produced in objective way

<?php

use GraphQL\Type\Definition\EnumType;
use SimPod\GraphQLUtils\Builder\EnumBuilder;

$episodeEnum = new EnumType( 
    EnumBuilder::create('Episode')
        ->setDescription('One of the films in the Star Wars Trilogy')
        ->addValue(4, 'NEWHOPE', 'Released in 1977.')
        ->addValue(5, 'EMPIRE', 'Released in 1980.')
        ->addValue(6, 'JEDI', 'Released in 1983.')
        ->build()
);

InterfaceBuilder

✔️ Standard way with webonyx/graphql-php

<?php

use GraphQL\Type\Definition\InterfaceType;
use GraphQL\Type\Definition\Type;

$character = new InterfaceType([
    'name' => 'Character',
    'description' => 'A character in the Star Wars Trilogy',
    'fields' => [
        'id' => [
            'type' => Type::nonNull(Type::string()),
            'description' => 'The id of the character.',
        ],
        'name' => [
            'type' => Type::string(),
            'description' => 'The name of the character.'
        ]
    ],
    'resolveType' => static function ($value) : object {
        if ($value->type === 'human') {
            return MyTypes::human();            
        }

        return MyTypes::droid();
    }
]);

✨ The same can be produced in objective way

<?php

use GraphQL\Type\Definition\InterfaceType;
use GraphQL\Type\Definition\Type;
use SimPod\GraphQLUtils\Builder\InterfaceBuilder;
use SimPod\GraphQLUtils\Builder\FieldBuilder;

$character = new InterfaceType(
    InterfaceBuilder::create('Character')
        ->setDescription('A character in the Star Wars Trilogy')
        ->setFields([
            FieldBuilder::create('id', Type::nonNull(Type::string()))
                ->setDescription('The id of the character.')
                ->build(),
            FieldBuilder::create('name', Type::string())
                ->setDescription('The name of the character.')
                ->build()
        ])
        ->setResolveType(
            static function ($value) : object {
                if ($value->type === 'human') {
                    return MyTypes::human();            
                }
    
                return MyTypes::droid();
            }
        )
        ->build()
);

UnionBuilder

✔️ Standard way with webonyx/graphql-php

<?php

use GraphQL\Type\Definition\UnionType;

$searchResultType = new UnionType([
    'name' => 'SearchResult',
    'types' => [
        MyTypes::story(),
        MyTypes::user()
    ],
    'resolveType' => static function($value) {
        if ($value->type === 'story') {
            return MyTypes::story();            
        }

        return MyTypes::user();
    }
]);

✨ The same can be produced in objective way

<?php

use SimPod\GraphQLUtils\Builder\UnionBuilder;

$character = new UnionType(
    UnionBuilder::create(
        'SearchResult',
        [
            MyTypes::story(),
            MyTypes::user()
        ]
    )
        ->setResolveType(
            static function($value) {
                if ($value->type === 'story') {
                    return MyTypes::story();            
                }
        
                return MyTypes::user();
            }
        )
        ->build()
);

Error Handling

Extending your exception with SimPod\GraphQLUtils\Error\Error forces you to implement getType() method.

Example Error class

<?php

use SimPod\GraphQLUtils\Error\Error;

final class InvalidCustomerIdProvided extends Error
{
    private const TYPE = 'INVALID_CUSTOMER_ID_PROVIDED';

    public static function noneGiven() : self
    {
        return new self('No CustomerId provided');
    }

    public function getType() : string
    {
        return self::TYPE;
    }

    public function isClientSafe() : bool
    {
        return true;
    }
}

Create your formatter

<?php

use GraphQL\Error\Error;
use SimPod\GraphQLUtils\Error\FormattedError;

$formatError = static function (Error $error) : array
{
   if (! $error->isClientSafe()) {
       // eg. log error
   }

   return FormattedError::createFromException($error);
};

$errorFormatterCallback = static function (Error $error) use ($formatError) : array {
    return $formatError($error);
};
        
$config = GraphQL::executeQuery(/* $args */)
    ->setErrorFormatter($errorFormatterCallback)
    ->setErrorsHandler(
        static function (array $errors, callable $formatter) : array {
            return array_map($formatter, $errors);
        }
    );

Error types will then be provided in your response so client can easier identify the error type

{
    "errors": [
        {
            "message": "No CustomerId provided",
            "extensions": {
                "type": "INVALID_CUSTOMER_ID_PROVIDED",
                "category": "validation"
            }
        }
    ]
}

graphql-utils's Issues

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

composer

composer.json

• php ^8.2
• webonyx/graphql-php ^15.4
• doctrine/coding-standard ^12.0
• infection/infection ^0.28.0
• phpstan/extension-installer ^1.1
• phpstan/phpstan ^1.3
• phpstan/phpstan-phpunit ^1.0
• phpstan/phpstan-strict-rules ^1.1
• phpunit/phpunit ^11.0

github-actions

.github/workflows/ci.yml

• actions/checkout v4
• shivammathur/setup-php v2
• ramsey/composer-install v2
• actions/upload-artifact v4
• actions/checkout v4
• actions/download-artifact v4
• codecov/codecov-action v4
• ubuntu 22.04
• ubuntu 22.04

.github/workflows/coding-standards.yml

• actions/checkout v4
• shivammathur/setup-php v2
• ramsey/composer-install v2
• ubuntu 22.04

.github/workflows/infection.yaml

• actions/checkout v4
• shivammathur/setup-php v2
• ramsey/composer-install v2
• ubuntu 22.04

.github/workflows/static-analysis.yml

• actions/checkout v4
• shivammathur/setup-php v2
• ramsey/composer-install v2
• ubuntu 22.04

---

• Check this box to trigger a request for Renovate to run again on this repository

Default field resolver per type

Sometimes it might be convenient to set default field resolver per type. Webonyx implements it like a charm

What do you think? Should I submit a PR?

Should the result of the builder be still passed to an ObjectBuilder object?

I was going through the docs of webonyx/graphql-php when I came across this lib. I got a question about the examples shown in the readme. Looking at the following example https://github.com/simPod/GraphQL-Utils#objectbuilder-and-fieldbuilder. The variable $userType do not have the same type. One is an object and the other an array. I think the $userType in the "objective way" example still needs to be passed to the ObjectType() ?

So the complete example should look like this?:

<?php

use GraphQL\Type\Definition\ResolveInfo;
use SimPod\GraphQLUtils\Builder\ObjectBuilder;

$userTypeArray = ObjectBuilder::create('User')
    ->setDescription('Our blog visitor')
    ->setFields([
        FieldBuilder::create('firstName', Type::string())
            ->setDescription('User first name')
            ->build(),
        FieldBuilder::create('email', Type::string())->build(),
    ])
    ->setFieldResolver(
        static function(User $user, $args, $context, ResolveInfo $info) {
           switch ($info->fieldName) {
               case 'name':
                 return $user->getName();
               case 'email':
                 return $user->getEmail();
               default:
                 return null;
           }
        }
    )->build();

$userType = new ObjectType($userTypeArray);

Release new version for Safe v1 compatibility

I can see that thecodingmachine/safe has already been upgraded to v1 on master (de1815d, 194abf4). Can you please release new version so that simpod/graphql-utils is compatible with Save v1? Thanks.