webonyx/graphql-php

graphql-php is a feature-complete implementation of the GraphQL specification in PHP. It acts as a thin wrapper around your existing data layer and business logic without dictating implementation details.

Key features include:

• Primitives to express your application as a Type System.
• Validation and introspection of the Type System (compatible with tools like GraphiQL).
• Parsing, validating, and executing GraphQL queries.
• Rich error reporting for both query validation and execution errors.
• Optional tools for parsing Schema Definition Language (SDL).
• Tools for batching requests to backend storage (solving the N+1 problem).
• Support for Async PHP platforms via promises.
• Standard HTTP server support.

In graphql-php, types are categorized into Input and Output types. This distinction determines whether a type can be used as a field in a response or as an argument in a query.

• Output types (field types): ScalarType, EnumType, ObjectType, InterfaceType, and UnionType.
• Input types (argument types): ScalarType, EnumType, and InputObjectType.

Note that NonNull and List wrappers can belong to either category depending on the type they wrap.

To interact with your graphql-php server, you can use the following clients:

Interactive IDEs (Browser-based)

• GraphiQL: Graphical interactive in-browser GraphQL IDE.
• GraphQL Playground: IDE for enhanced workflows including GraphQL Subscriptions, interactive docs, and collaboration.

Desktop & Specialized Clients

• Altair GraphQL Client: Feature-rich GraphQL client available for all platforms.
• Sailor: A typesafe GraphQL client specifically for PHP.

GraphQL is a data-centric language built around three major pillars:

1. Schema (Type System): The definition of your application's data structure and capabilities.
2. Query: A request for structured data. Queries are designed to mirror the shape of the expected JSON response and are intended to be idempotent.
3. Mutation: A request to perform side effects (creating, updating, or deleting data). Unlike Query fields, fields within the root Mutation type are executed serially.

Typically, you expose your Schema via a single HTTP endpoint where clients send Queries and Mutations (usually via HTTP POST).

In v0.12.x, comments are no longer used as descriptions by default. Descriptions must now be defined using Strings or BlockStrings within the GraphQL language. If you need to maintain the old behavior, you can provide the commentDescriptions option to BuildSchema::buildAST(), BuildSchema::build(), or Printer::doPrint().

New way to define descriptions:

"Description"
type Dog {
  ...
}

"""
Long Description
"""
type Dog {
  ...
}

When upgrading to v15.x.x, note the following breaking changes:

Removed error extension field category

Errors implementing ClientAware no longer include the category key in their formatted output. The ClientAware::getCategory() method has been removed. If you need to maintain the old format, implement custom error formatting.

StandardServer execution changes

The $exitWhenDone argument has been removed from StandardServer::send500Error() and StandardServer::handleRequest(). If your application logic requires the process to exit after handling a request, you must call exit manually.

$server = new GraphQL\Server\StandardServer();
-$server->handleRequest($body, true);
+$server->handleRequest($body);
+exit;

For a more convenient way to explore your GraphQL APIs with syntax highlighting and auto-completion, you can use GraphiQL. The easiest way is to install a Google Chrome extension:

• ChromeiQL
• GraphiQL Feen

Alternatively, you can install GraphiQL locally following the official GraphiQL instructions.

Errors in type definitions (e.g., logical errors in your schema) throw GraphQL\Error\InvariantViolation. These should typically be treated as server errors (HTTP 500).

When building a schema, wrap the instantiation in a try-catch block to capture these errors and return a proper JSON error response.

use GraphQL\GraphQL;
use GraphQL\Type\Schema;
use GraphQL\Error\FormattedError;

try {
    $schema = new Schema([
        // ...
    ]);

    $body = GraphQL::executeQuery($schema, $query);
    $status = 200;
} catch(\Exception $e) {
    $body = [
        'errors' => [
            FormattedError::createFromException($e)
        ]
    ];
    $status = 500;
}

header('Content-Type: application/json', true, $status);
echo json_encode($body, JSON_THROW_ON_ERROR);