A typesafe GraphQL client for PHP

Fund package maintenance!

dev-master 2020-05-06 19:05 UTC

This package is auto-updated.

Last update: 2020-05-06 19:17:42 UTC



CI Status codecov StyleCI Latest Stable Version Total Downloads

A typesafe GraphQL client for PHP


GraphQL provides typesafe API access through the schema definition each server provides through introspection. Sailor leverages that information to enable an ergonomic workflow and reduce type-related bugs in your code.

The native GraphQL query language is the most universally used tool to formulate GraphQL queries and works natively with the entire ecosystem of GraphQL tools. Sailor takes the plain queries you write and generates executable PHP code, using the server schema to generate type safe operations and results.


Install Sailor through composer by running:

composer require spawnia/sailor

Caveat: This library requires bleeding edge features of webonyx/graphql-php, see, so dev-master is required for now.


Run vendor/bin/sailor to set up the configuration. A file called sailor.php will be created in your project root.

You can take a look at the example configuration to see what options are available for configuration: sailor.php.

It is quite useful to include dynamic values in your configuration. You might use PHP dotenv to load environment variables (run composer require vlucas/phpdotenv if you do not have it installed already.).

# sailor.php
+$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);

        public function makeClient(): Client
            return new \Spawnia\Sailor\Client\Guzzle(
-               'http://hardcoded.url/',
+               getenv('EXAMPLE_API_URL'),
                    'headers' => [
-                       'Authorization' => 'hardcoded-api-token',
+                       'Authorization' => getenv('EXAMPLE_API_TOKEN'),



Run vendor/bin/sailor introspect to update your schema with the latest changes from the server by running an introspection query. As an example, a very simple server might result in the following file being placed in your project:

# schema.graphqls
type Query {
  hello(name: String): String

Define operations

Put your queries and mutations into .graphql files and place them anywhere within your configured project directory. You are free to name and structure the files in any way. Let's query the example schema from above:

# src/example.graphql
query HelloSailor {
  hello(name: "Sailor")

The only requirement is that you must give all your operations unique names.

# Invalid, operations have to be named
query {

# Invalid, names must be unique across all operations
query Foo { ... }
mutation Foo { ... }

Generate code

Run vendor/bin/sailor to generate PHP code for your operations. For the example above, Sailor will generate a class called HelloSailor, place it in the configured namespace and write it to the configured location.



namespace Example\Api;

class HelloSailor extends \Spawnia\Sailor\Operation { ... }

There are additional generated classes that represent the results of calling the operations. The plain data from the server is wrapped up and contained within those value classes so you can access them in a typesafe way.

Execute queries

You are now set up to run a query against the server, just call the execute() function of the new query class:

$result = \Example\Api\HelloSailor::execute();

The returned $result is going to be a class that extends \Spawnia\Sailor\Result and holds the decoded response returned from the server. You can just grab the $data, $errors or $extensions off of it.

$result->data        // `null` or a generated subclass of `\Spawnia\Sailor\TypedObject`
$result->errors      // `null` or a list of errors
$result->extensions  // `null` or an arbitrary map


You can find examples of how a project would use Sailor within examples.


Please have a look at


Please have a look at


This package is licensed using the MIT License.