add docs to php-graphql

Author: joonlabs

docs/getting-started.md

@@ -0,0 +1,63 @@
+# Installation
+To install php-graphql, you basically have two options. You can either use composer or git submodules.
+
+Composer (coming soon):
+````bash
+composer require joonlabs/php-graphql
+````
+
+Git-Submodule
+````bash
+git submodule add https://github.com/joonlabs/php-graphql.git
+````
+# Additional Tools
+Although it is completely possible to communicate with the GraphQL API via HTTP requests, it is much more convenient to use graphical tools like [Altair](https://github.com/imolorhe/altair) or [GraphiQL](https://github.com/graphql/graphiql), while debugging and developing.
+These tools offer syntax highlighting, autocompletion, documentation insights and much more.
+
+# Hello world!
+
+```php
+use GraphQL\Servers\Server;
+use GraphQL\Schemas\Schema;
+use GraphQL\Types\GraphQLString;
+use GraphQL\Types\GraphQLObjectType;
+use GraphQL\Fields\GraphQLTypeField;
+
+// build the query type
+$QueryType = new GraphQLObjectType("Query", "Root Query", function (){
+    return [
+        new GraphQLTypeField(
+            "hello",
+            new GraphQLString(),
+            "Your first hello world GraphQL-Application",
+            function (){ return 'Hello world!'; }
+        )
+    ];
+});
+
+// build the schema
+$schema = new Schema($QueryType);
+
+// start a server
+$server = new Server($schema);
+$server->listen();
+```
+
+That's it! Now the GraphQL server is ready to accept requests at the URL of the PHP script. An example request can now look like this:
+````graphql
+query {
+    hello
+}
+````
+... and will return:
+
+````json
+{
+  "data": {
+    "hello" : "Hello world!"
+  }
+}
+````
+
+# What's next?
+Since this example is extremely simple and does not really address what is possible with GraphQL, it is recommended to take a closer look at the [Star Wars](https://github.com/joonlabs/php-graphql/tree/master/examples/starwars) and [books](https://github.com/joonlabs/php-graphql/tree/master/examples/books) examples.  

docs/index.md

@@ -0,0 +1,26 @@
+# Introduction
+GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
+
+At its core, GraphQL is a standard (see the [official specification](https://spec.graphql.org)) developed by Facebook Engineers. This means that GraphQL is implementation independent.
+A well-documented overview of the features and capabilities of GraphQL can be found on the official website, all of which were implemented in this project.
+
+# php-graphql
+
+**php-graphql** is a new and feature-complete implementation of the GraphQL specifications, based on the [refernce implenentation in JavaScript](https://github.com/graphql/graphql-js).
+The goal of this project is to create a lightweight and superfast alternative to other PHP GraphQL implementations, which also supports file upload from scratch.
+
+To achieve this goal, the library features its own LL(1) parser, validator and executor. Also, performance critical duplicate validations by validator and executor are tried to be avoided to allow fast validation and subsequent execution.
+
+The following features are included in the library:
+- GraphQL-Types for building a Type System
+- Introspection of your Type System (for tools like [Altair](https://github.com/imolorhe/altair) or [GraphiQL](https://github.com/graphql/graphiql))
+- Parsing, validating and executing GraphQL queries
+- Automated input handling and easy GraphQL-Server setup
+
+# Status
+The first release of this project was published in May 2021. 
+The current relaese supports all features described by the official specification.
+As this project was developed out of internal needs to overcome shortcomings of other implementations, it will be maintained for several years. 
+
+# Source Code
+The project's source code is hosted on [GitHub](https://github.com/joonlabs/php-graphql/)

docs/parsing-validating-executing.md

@@ -0,0 +1,59 @@
+# Introduction
+This section describes how parsing, validation and execution in a high level and should only be interesting for building an own processing pipeline or understanding how the GraphQL-Server works. 
+In all other cases the default `Server` should be fine to use.
+
+# Parsing
+Before a query can be executed, it must first be parsed into a so-called document. The string of a query is converted into an associative array, which contains more detailed information about certain parts of the query, such as locations of different words, their meaning in the current context, and so on. This parsed document can then be passed to a validator, or directly to an executor.
+
+Parsing can be done like this:
+```php
+use GraphQL\Parser\Parser;
+
+// define the query
+$query = "
+    query {
+        helloWorld
+    }";
+
+// create parser and parse the query
+$parser = new Parser();
+$parser->parse($query);
+
+// check if query was syntactically correct and obtain parsed document
+if($parser->queryIsValid()){
+    $document = $parser->getParsedDocument();
+}
+```
+
+# Validation
+A validator takes a parsed document, and a schema to decide wether the given operations in the document are valid against the schema or not.
+
+Validation can be done like this:
+
+```php
+use GraphQL\Validation\Validator;
+
+// create validator and validate document against schema
+$validator = new Validator();
+$validator->validate($schema, $document);
+
+// check if document was valid against the schema
+if($validator->documentIsValid()){
+    // continue with execution
+}
+```
+
+# Execution
+An exeutor takes a parsed document, and a schema to perform all operation definitions given by the document on the schema. 
+This can be any kind of query or mutation, or multiple of those. It is highly recommended to validate the query first and execute it afterwards to prevent errors during execution. 
+If you are using the default `Server` this work is already done for you.
+
+```php
+use GraphQL\Execution\Executor;
+
+// create executor 
+$executor = new Executor();
+
+// execute document
+$result = $executor->execute($schema, $document);
+```

docs/schema-definition.md

@@ -0,0 +1,54 @@
+# Schema Definition
+The schema is a container for your type hierarchy that accepts object types as roots for the query type, and the mutation type. 
+It is passed to the validator and the executor and used to model your underlying data structures.
+
+````php
+use GraphQL\Servers\Server;
+
+$schema = new Schema(
+    $QueryType,
+    $MutationType
+);
+````
+
+# Query and Mutation
+As described above, the schema consits of two root types (which are both object types):
+- the **query** type for performing read operations on your data and
+- the **mutation** type for performing changes in and operations on your data (this is completely optional)
+
+```php
+use GraphQL\Types\GraphQLInt;
+use GraphQL\Types\GraphQLString;
+use GraphQL\Types\GraphQLNonNull;
+use GraphQL\Types\GraphQLObjectType;
+use GraphQL\Fields\GraphQLTypeField;
+use GraphQL\Arguments\GraphQLFieldArgument;
+
+$QueryType = new GraphQLObjectType("Query", "Root Query", function (){
+    return [
+        new GraphQLTypeField(
+            "hello",
+            new GraphQLString(),
+            "Your first hello world GraphQL-Application's query",
+            function (){ return 'Hello world!'; }
+        )
+    ];
+});
+
+$MutationType = new GraphQLObjectType("Mutation", "Root Mutation", function (){
+    return [
+        new GraphQLTypeField(
+            "multiply",
+            new GraphQLInt(),
+            "Your first hello world GraphQL-Application's mutation",
+            function ($parent, $args, $context, $info){ 
+                return $args["a"] * $args["b"]; 
+            },
+            [
+                new GraphQLFieldArgument("a", new GraphQLNonNull(new GraphQLInt())),
+                new GraphQLFieldArgument("b", new GraphQLNonNull(new GraphQLInt())),
+            ]
+        )
+    ];
+});
+```

docs/server.md

@@ -0,0 +1,13 @@
+# Server
+The default `Server` is a simple wrapper around a parser, validator and executor to save you work. 
+When constructing a server, simply pass the schema to the constructor and enable processing via the `listen()` function.
+
+```php
+use GraphQL\Servers\Server;
+
+// create server and listen for inputs
+$server = new Server($schema);
+$server->listen();
+```
+
+For more details on parsing, validation and execution, take a look at the according section in the docs.

docs/types/directives.md

@@ -0,0 +1,21 @@
+# Directives
+A directive describes how the data should be processed at a meta level. 
+A directive can be attached to a field or fragment and can affect the execution of the query.
+
+**php-graphql** implements the both directives given by the specification:
+- **@include(if:Boolean)** A field or fragment is only included if this directive's parameter `if` is **true**  
+- **@skip(if:Boolean)** A field or fragment is skipped if this directive's parameter `if` is **true**
+
+For example:
+```graphql
+query Hero($episode: Episode, $withFriends: Boolean!) {
+  hero(episode: $episode) {
+    name
+    friends @include(if: $withFriends) {
+      name
+    }
+  }
+}
+```
+
+The selection `friends` will only be included in the returning data, if the variable **$withFriends** is set to **true**.

docs/types/enums.md

@@ -0,0 +1,16 @@
+# Enums
+Enumeration types are a special kind of scalar that is restricted to a particular set of allowed values and in this implementation handled as string values.
+
+**php-graphql** represents enums as instances of the class `GraphQLEnum`, which accepts a name, description and possible values
+(`GraphQlEnumValue`) as parameters in the constructor.
+
+```php
+use GraphQL\Types\GraphQLEnum;
+use GraphQL\Types\GraphQLEnumValue;
+
+$Episode = new GraphQLEnum("Episode", "One of the films in the Star Wars Trilogy.", [
+    new GraphQLEnumValue("NEW_HOPE", "Released in 1977."),
+    new GraphQLEnumValue("EMPIRE", "Released in 1980."),
+    new GraphQLEnumValue("JEDI", "Released in 1983.")
+]);
+```

docs/types/index.md

@@ -0,0 +1,51 @@
+# Types
+In **php-graphql**, types are represented as instances of a GraphQL-Type-Class. Supported built in types are:
+- ```GraphQLBoolean()```
+- ```GraphQLEnum()```
+- ```GraphQLFloat()```
+- ```GraphQLID()```
+- ```GraphQLInputObjectType()```
+- ```GraphQLInt()```
+- ```GraphQLInterface()```
+- ```GraphQLList()```
+- ```GraphQLNonNull()```
+- ```GraphQLObjectType()```
+- ```GraphQLString()```
+- ```GraphQLUnion()```
+
+# Definition
+All types are created inline. This means that to give an object a type, you just need to create an instance of that type. For example:
+```php
+use GraphQL\Types\GraphQLObjectType;
+use GraphQL\Fields\GraphQLTypeField;
+use GraphQL\Types\GraphQLInt;
+use GraphQL\Types\GraphQLEnum;
+use GraphQL\Types\GraphQLEnumValue;
+use GraphQL\Types\GraphQLString;
+
+// create enum type
+$MyEnumType = new GraphQLEnum(
+    "MyEnumType",
+    "This is the description of my enum type",
+    [
+        new GraphQLEnumValue("PossibleValue1"),
+        new GraphQLEnumValue("PossibleValue2"),
+        new GraphQLEnumValue("PossibleValue3")
+    ]
+);
+
+// create object type
+$MyObjectType = new GraphQLObjectType(
+    "MyObjectType",
+    "This is the description of my object type",
+    function() use(&$MyEnumType){
+        return [
+            new GraphQLTypeField("myIntField", new GraphQLInt()),
+            new GraphQLTypeField("myStringField", new GraphQLString()),
+            new GraphQLTypeField("myEnumField", $MyEnumType)
+        ];   
+    }
+);
+```
+
+For more details about each type, just check the corresponding sections.

docs/types/interfaces.md

@@ -0,0 +1,41 @@
+# Interfaces
+An Interface is an abstract type that includes a certain set of fields that a type must include to implement the interface.
+An Interface can never be returned directly but must be implemented by 'child types'.
+
+**php-graphql** represents interfaces as instances of the class `GraphQLInterface`, which accepts several parameters
+in the constructor for configuring the interface.
+
+```php
+use GraphQL\Types\GraphQLInterface;
+use GraphQL\Fields\GraphQLTypeField;
+use GraphQL\Types\GraphQLNonNull;
+use GraphQL\Types\GraphQLString;
+use GraphQL\Types\GraphQLList;
+
+$Character = new GraphQLInterface("Character", "A character in the Star Wars Trilogy.", function () use (&$Character, &$Episode) {
+    return [
+        new GraphQLTypeField("id", new GraphQLNonNull(new GraphQLString()), "The id of the character."),
+        new GraphQLTypeField("name", new GraphQLString(), "The name of the character."),
+        new GraphQLTypeField("friends", new GraphQLList($Character), "The friends of the character, or an empty list if they have none."),
+        new GraphQLTypeField("appearsIn", new GraphQLList($Episode), "Which movies they appear in."),
+    ];
+}, function ($character) {
+    if ($character["type"] === "human") {
+        return "Human";
+    }
+    return "Droid";
+});
+```
+# GraphQLInterface Constructor
+Parameters used for the `GraphQLInterface` constructors are (in the following order):
+
+| Parameter | Type | Description | Required |
+| --- | --- | --- | --- |
+| **type** | `string` | Name of the new interface. Used for introspection. | ☑️ |
+| **description** | `string` | Description of the new interface. Used for introspection. | ☑️ |
+| **fields** | `\Closure` | Function that returns an array of `GraphQLTypeField`. Each field must be implemented in the type that implements this interface. Is called as soon the fields are needed. Used during validation and execution. | ☑️ |
+| **resolveTypeFn** | `\Closure` | Function that decides to which implementing object type a data object belongs to. If not passed, the default resolver is used. Used during validation and execution. | ️ |
+
+
+# Implementing Interfaces
+Interfaces can be implemented by a `GraphQLObjectType`, when passing the interface (reference) to the `GraphQLObjectType` constructor (see parameters of `GraphQLObjectType` constructor in the according section).  

docs/types/list-and-non-nulls.md

@@ -0,0 +1,25 @@
+# Lists and Non-Nulls
+Lists and Non-Nulls are wrapping types in GraphQL. This means, that they cannot be used solely, but must feature an inner type, which they hold.
+
+
+# Lists
+**php-graphql** represents lists of other types as instances of the class `GraphQLList`, which accepts an inner type
+as parameter in the constructor.
+
+```php
+use GraphQL\Types\GraphQLList;
+use GraphQL\Types\GraphQLInt;
+
+$ListOfInts = new GraphQLList(new GraphQLInt()); 
+```
+
+# Non-Null
+**php-graphql** represents non-null types as instances of the class `GraphQLNonNull`, which accepts an inner type
+as parameter in the constructor.
+
+```php
+use GraphQL\Types\GraphQLNonNull;
+use GraphQL\Types\GraphQLInt;
+
+$NonNullInt = new GraphQLNonNull(new GraphQLInt());
+```