Split documentation

Resources/doc/definitions/builders/args.md

@@ -0,0 +1,4 @@
+Args builder
+============
+
+TODO

Resources/doc/definitions/builders/field.md

@@ -0,0 +1,59 @@
+Field builder
+=============
+
+Builder is a way to don't repeat field definition.
+
+Define your custom field builder
+```yaml
+#app/config/config.yml
+overblog_graphql:
+    #... 
+    definitions:
+        #...
+        builders:
+            field:
+                -
+                    alias: "RawId"
+                    class: "MyBundle\\GraphQL\\Field\\RawIdField"
+```
+
+Builder class must implements `Overblog\GraphQLBundle\Definition\Builder\MappingInterface`
+
+```php
+namespace MyBundle\GraphQL\Field;
+
+use Overblog\GraphQLBundle\Definition\Builder\MappingInterface;
+
+class RawIdField implements MappingInterface
+{
+    public function toMappingDefinition(array $config)
+    {
+        return [
+            'description' => 'The raw ID of an object',
+            'type' => 'Int!',
+            'resolve' => '@=value.id',
+        ];
+    }
+}
+```
+
+usage:
+
+```yaml
+#Resources/graphql/schema.yml
+User:
+    type: object
+    config:
+        fields:
+            # equivalent to rawId: { description: "The user raw id", type: 'Int!', resolve: "@=value.id"  }
+            rawId:
+                builder: "RawId"
+                description: "The user raw id"
+
+Post:
+    type: object
+    config:
+        fields:
+            # equivalent to rawId: { description: "The raw ID of an object", type: 'Int!', resolve: "@=value.id"  }
+            rawId: "RawId"
+```

Resources/doc/definitions/builders/index.md

@@ -0,0 +1,5 @@
+Builders
+=========
+
+* [Field](field.md)
+* [Args](args.md)

Resources/doc/definitions/debug/index.md

@@ -0,0 +1,40 @@
+Debug
+=====
+
+Query debug information
+------------------------
+
+To enabled or disabled debug information:
+
+```yaml
+# app/config/config.yml
+
+overblog_graphql:
+    definitions:
+        show_debug_info: true # Debug info is disabled by default
+```
+
+here an example of an answer when debug information is enabled
+```json
+{
+  "data": [{"isEnabled": true}],
+  "extensions": {
+    "debug": {
+      "executionTime": "40 ms",
+      "memoryUsage": "1.00 MiB"
+    }
+  }
+}
+```
+
+Config validation
+------------------
+
+Enabled or disabled the config validation (this should be limited to debug environments) 
+```yaml
+#app/config/config.yml
+
+overblog_graphql:
+    definitions:
+        config_validation: %kernel.debug%
+```

Resources/doc/definitions/expression-language.md

@@ -0,0 +1,44 @@
+Expression language
+===================
+
+All definitions configs entries can use expression language but it must be explicitly triggered using "@=" like prefix.
+
+**Functions description:**
+
+Expression | Description | Usage 
+---------- | ----------- | -----
+object **service**(string $id) | Get a service from the container | @=service('my_service').customMethod()
+mixed **parameter**(string $name) | Get parameter from the container | @=parameter('kernel.debug')
+boolean **isTypeOf**(string $className) | Verified if `value` is instance of className | @=isTypeOf('AppBundle\\User\\User')
+mixed **resolver**(string $alias, array $args = []) | call the method on the tagged service "overblog_graphql.resolver" with args | @=resolver('blog_by_id', [value['blogID']])
+mixed **mutation**(string $alias, array $args = []) | call the method on the tagged service "overblog_graphql.mutation" with args | @=mutation('remove_post_from_community', [value])
+string **globalId**(string\|int id, string $typeName = null) | Relay node globalId | @=globalId(15, 'User')
+array **fromGlobalId**(string $globalId) | Relay node fromGlobalId | @=fromGlobalId('QmxvZzox')
+object **newObject**(string $className, array $args = []) | Instantiation $className object with $args | @=newObject('AppBundle\\User\\User', ['John', 15])
+boolean **hasRole**(string $role) | Checks whether the token has a certain role. | @=hasRole('ROLE_API')
+boolean **hasAnyRole**(string $role1, string $role2, ...string $roleN) | Checks whether the token has any of the given roles. | @=hasAnyRole('ROLE_API', 'ROLE_ADMIN')
+boolean **isAnonymous**() | Checks whether the token is anonymous. | @=isAnonymous()
+boolean **isRememberMe**() | Checks whether the token is remember me. | @=isRememberMe()
+boolean **isFullyAuthenticated**() | Checks whether the token is fully authenticated. | @=isFullyAuthenticated()
+boolean **isAuthenticated**() | Checks whether the token is not anonymous. | @=isAuthenticated()
+boolean **hasPermission**(mixed $var, string $permission) | Checks whether the token has the given permission for the given object (requires the ACL system). |@=hasPermission(object, 'OWNER')
+boolean **hasAnyPermission**(mixed $var, array $permissions) | Checks whether the token has any of the given permissions for the given object | @=hasAnyPermission(object, ['OWNER', 'ADMIN'])
+
+**Variables description:**
+
+Expression | Description | Scope
+---------- | ----------- | --------
+**container** | DI container | global
+**request** | Refers to the current request. | Request
+**token** | Refers to the token which is currently in the security token storage. Token can be null. | Token
+**user** | Refers to the user which is currently in the security token storage. User can be null. | Valid Token
+**object** | Refers to the value of the field for which access is being requested. For array `object` will be each item of the array. For Relay connection `object` will be the node of each connection edges. | only available for `config.fields.*.access` with query operation or mutation payload type.
+**value** | Resolver value | only available in resolve context 
+**args** | Resolver args array | only available in resolve context 
+**info** | Resolver GraphQL\Type\Definition\ResolveInfo Object | only available in resolve context
+**context** | context is defined by your application on the top level of query execution (useful for storing current user, environment details, etc) | only available in resolve context
+**childrenComplexity** | Selection field children complexity | only available in complexity context
+
+[For more details on expression syntax](http://symfony.com/doc/current/components/expression_language/syntax.html)
+
+**Tips**: the expression language service can be custom using bundle configuration.

Resources/doc/definitions/index.md

@@ -0,0 +1,15 @@
+Definitions
+===========
+
+* [System types](system-types/index.md)
+* [Schema](schema.md)
+
+Go further 
+----------
+
+* [Relay](relay/index.md)
+* [Builders](builders/index.md)
+* [Expression language](expression-language.md)
+* [Debug](debug/index.md)
+
+Next step [secure your server](../security/index.md).

Resources/doc/definitions/relay/connection.md

@@ -0,0 +1,53 @@
+Connection
+===========
+
+```yaml
+Query:
+    type: object
+    config:
+        fields:
+            user:
+                type: User
+                resolve: '@=resolver("query")'
+
+User:
+    type: object
+    config:
+        fields:
+            name:
+                type: String
+            friends:
+                type: friendConnection
+                argsBuilder: ConnectionArgs
+                resolve: '@=resolver("friends", [value, args])'
+            friendsForward:
+                type: userConnection
+                argsBuilder: ForwardConnectionArgs
+                resolve: '@=resolver("friends", [value, args])'
+            friendsBackward:
+                type: userConnection
+                argsBuilder: BackwardConnectionArgs
+                resolve: '@=resolver("friends", [value, args])'
+
+friendConnection:
+    type: relay-connection
+    config:
+        nodeType: User
+        resolveNode: '@=resolver("node", [value])'
+        edgeFields:
+            friendshipTime:
+                type: String
+                resolve: "Yesterday"
+        connectionFields:
+            totalCount:
+                type: Int
+                resolve: '@=resolver("connection")'
+
+userConnection:
+    type: relay-connection
+    config:
+        nodeType: User
+        resolveNode: '@=resolver("node", [value])'
+```
+
+To ease relay connection pagination you can use the [pagination helper](../../helpers/relay-paginator.md).

Resources/doc/definitions/relay/index.md

@@ -0,0 +1,6 @@
+Relay
+=====
+
+* [connection](connection.md)
+* [node](node/index.md)
+* [mutation](mutation.md)

Resources/doc/definitions/relay/mutation.md

@@ -0,0 +1,44 @@
+Mutation
+========
+
+```yaml
+RootMutation:
+    type: object
+    config:
+        fields:
+            simpleMutation:
+                builder: Mutation
+                builderConfig:
+                    inputType: simpleMutationInput
+                    payloadType: simpleMutationPayload
+                    mutateAndGetPayload: "@={'result': 1}"
+            simpleMutationWithThunkFields:
+                builder: Mutation
+                builderConfig:
+                    inputType: simpleMutationWithThunkFieldsInput
+                    payloadType: simpleMutationWithThunkFieldsPayload
+                    mutateAndGetPayload: "@={'result': value['inputData'] }"
+
+simpleMutationInput:
+    type: relay-mutation-input
+    config:
+        fields: []
+
+simpleMutationWithThunkFieldsInput:
+    type: relay-mutation-input
+    config:
+        fields:
+            inputData : { type: "Int" }
+
+simpleMutationPayload:
+    type: relay-mutation-payload
+    config:
+        fields:
+            result: { type: "Int" }
+
+simpleMutationWithThunkFieldsPayload:
+    type: relay-mutation-payload
+    config:
+        fields:
+            result: { type: "Int" }
+```

Resources/doc/definitions/relay/node/global-id.md

@@ -0,0 +1,59 @@
+Global ID
+=======
+
+```yaml
+Query:
+    type: object
+    config:
+        fields:
+            node:
+                builder: Node
+                builderConfig:
+                    nodeInterfaceType: NodeInterface
+                    idFetcher: '@=service("overblog_graphql.test.resolver.global").idFetcher(value)'
+            allObjects:
+                type: '[NodeInterface]'
+                resolve: '@=service("overblog_graphql.test.resolver.global").resolveAllObjects()'
+
+NodeInterface:
+    type: relay-node
+    config:
+        resolveType: '@=service("overblog_graphql.test.resolver.global").typeResolver(value)'
+
+User:
+    type: object
+    config:
+        fields:
+            id:
+                builder: GlobalId
+                builderConfig:
+                    typeName: User
+            name:
+                type: String
+        interfaces: [NodeInterface]
+
+Photo:
+    type: object
+    config:
+        fields:
+            id:
+                builder: GlobalId
+                builderConfig:
+                    typeName: Photo
+                    idFetcher: '@=value["photoId"]'
+            width:
+                type: Int
+        interfaces: [NodeInterface]
+
+Post:
+    type: object
+    config:
+        fields:
+            id:
+                builder: GlobalId
+                builderConfig:
+                    typeName: Post
+            text:
+                type: String
+        interfaces: [NodeInterface]
+```

Resources/doc/definitions/relay/node/index.md

@@ -0,0 +1,6 @@
+Node
+=====
+
+* [node](node.md)
+* [plural](plurial.md)
+* [global id](global-id.md)

Resources/doc/definitions/relay/node/node.md

@@ -0,0 +1,39 @@
+Node
+=====
+
+```yaml
+Query:
+    type: object
+    config:
+        fields:
+            node:
+                builder: Node
+                builderConfig:
+                    nodeInterfaceType: Node
+                    idFetcher: '@=resolver("node_id_fetcher", [value])'
+
+Node:
+    type: relay-node
+    config:
+        resolveType: '@=resolver("node_type", [value])'
+
+Photo:
+    type: object
+    config:
+        fields:
+            id:
+                type: ID!
+            width:
+                type: Int
+        interfaces: [Node]
+
+User:
+    type: object
+    config:
+        fields:
+            id:
+                type: ID!
+            name:
+                type: String
+        interfaces: [Node]
+```