name : getting-started.md ## Prerequisites This documentation assumes your familiarity with GraphQL concepts. If it is not the case - first learn about GraphQL on [the official website](https://graphql.org/learn/). ## Installation Using [composer](https://getcomposer.org/doc/00-intro.md), run: ```sh composer require webonyx/graphql-php ``` ## Upgrading We try to keep library releases backwards compatible when possible. For breaking changes we provide [upgrade instructions](https://github.com/webonyx/graphql-php/blob/master/UPGRADE.md). ## Install Tools (optional) While it is possible to communicate with GraphQL API using regular HTTP tools it is way more convenient for humans to use [GraphiQL](https://github.com/graphql/graphiql) - an in-browser IDE for exploring GraphQL APIs. It provides syntax-highlighting, auto-completion and auto-generated documentation for GraphQL API. The easiest way to use it is to install one of the existing Google Chrome extensions: - [ChromeiQL](https://chrome.google.com/webstore/detail/chromeiql/fkkiamalmpiidkljmicmjfbieiclmeij) - [GraphiQL Feen](https://chrome.google.com/webstore/detail/graphiql-feen/mcbfdonlkfpbfdpimkjilhdneikhfklp) Alternatively, you can follow instructions on [the GraphiQL](https://github.com/graphql/graphiql) page and install it locally. ## Hello World Let's create a type system that will be capable to process the following simple query: ``` query { echo(message: "Hello World") } ``` We need an object type with the field `echo`: ```php use GraphQL\Type\Definition\ObjectType; use GraphQL\Type\Definition\Type; $queryType = new ObjectType([ 'name' => 'Query', 'fields' => [ 'echo' => [ 'type' => Type::string(), 'args' => [ 'message' => Type::nonNull(Type::string()), ], 'resolve' => fn ($rootValue, array $args): string => $rootValue['prefix'] . $args['message'], ], ], ]); ``` (Note: type definition can be expressed in [different styles](type-definitions/index.md#definition-styles)) The interesting piece here is the **resolve** option of the field definition. It is responsible for returning a value of our field. Values of **scalar** fields will be directly included in the response while values of **composite** fields (objects, interfaces, unions) will be passed down to nested field resolvers (not in this example though). Now when our type is ready, let's create a GraphQL endpoint file for it **graphql.php**: ```php use GraphQL\GraphQL; use GraphQL\Type\Schema; $schema = new Schema([ 'query' => $queryType ]); $rawInput = file_get_contents('php://input'); $input = json_decode($rawInput, true); $query = $input['query']; $variableValues = isset($input['variables']) ? $input['variables'] : null; try { $rootValue = ['prefix' => 'You said: ']; $result = GraphQL::executeQuery($schema, $query, $rootValue, null, $variableValues); $output = $result->toArray(); } catch (\Exception $e) { $output = [ 'errors' => [ [ 'message' => $e->getMessage() ] ] ]; } header('Content-Type: application/json'); echo json_encode($output, JSON_THROW_ON_ERROR); ``` Our example is finished. Try it by running: ```sh php -S localhost:8080 graphql.php curl http://localhost:8080 -d '{"query": "query { echo(message: \"Hello World\") }" }' ``` Check out the full [source code](https://github.com/webonyx/graphql-php/blob/master/examples/00-hello-world) of this example which also includes simple mutation. Check out [the blog example](https://github.com/webonyx/graphql-php/blob/master/examples/01-blog) for something which is closer to real-world apps or read about the details of [schema definition](schema-definition.md). ## Next Steps Obviously hello world only scratches the surface of what is possible. To learn by example, check out the [blog example](https://github.com/webonyx/graphql-php/tree/master/examples/01-blog) which is quite close to real-world GraphQL hierarchies. For a deeper understanding of GraphQL in general, check out [concepts](concepts.md). To delve right into the implementation, see [schema definition](schema-definition.md).