Versioning docs for the 4.0 release

Author: moufmouf

website/versioned_docs/version-4.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+---
+id: version-4.0-changelog
+title: Changelog
+sidebar_label: Changelog
+original_id: changelog
+---
+
+## 4.0
+
+This is a complete refactoring from 3.x. While existing annotations are kept compatible, the internals have completely
+changed.
+
+New features:
+
+- You can directly [annotate a PHP interface with `@Type` to make it a GraphQL interface](inheritance-interfaces.md#mapping-interfaces)
+- You can autowire services in resolvers, thanks to the new `@Autowire` annotation
+- Added [user input validation](validation.md) (using the Symfony Validator or the Laravel validator or a custom `@Assertion` annotation
+- Improved security handling:
+  - Unauthorized access to fields can now generate GraphQL errors (rather that schema errors in GraphQLite v3)
+  - Added fine-grained security using the `@Security` annotation. A field can now be [marked accessible or not depending on the context](fine-grained-security.md).
+    For instance, you can restrict access to the field "viewsCount" of the type `BlogPost` only for post that the current user wrote.
+  - You can now inject the current logged user in any query / mutation / field using the `@InjectUser` annotation
+- Performance:
+  - You can inject the [Webonyx query plan in a parameter from a resolver](query_plan.md)
+  - You can use the [dataloader pattern to improve performance drastically via the "prefetchMethod" attribute](prefetch_method.md)
+- Customizable error handling has been added:
+  - You can throw [GraphQL errors](error_handling.md) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLException`
+  - You can specify the HTTP response code to send with a given error, and the errors "extensions" section 
+  - You can throw [many errors in one exception](error_handling.md#many-errors-for-one-exception) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLAggregateException` 
+- You can map [a given PHP class to several PHP input types](input_types.md#declaring-several-input-types-for-the-same-php-class) (a PHP class can have several `@Factory` annotations)
+- You can force input types using `@UseInputType(for="$id", inputType="ID!")`
+- You can extend an input types (just like you could extend an output type in v3) using [the new `@Decorate` annotation](extend_input_type.md)
+- In a factory, you can [exclude some optional parameters from the GraphQL schema](input_types#ignoring-some-parameters)
+
+
+Many extension points have been added 
+
+- Added a "root type mapper" (useful to map scalar types to PHP types or to add custom annotations related to resolvers)
+- Added ["field middlewares"](field_middlewares.md) (useful to add middleware that modify the way GraphQL fields are handled)
+- Added a ["parameter type mapper"](argument_resolving.md) (useful to add customize parameter resolution or add custom annotations related to parameters)
+
+New framework specific features:
+
+Symfony:
+
+- The Symfony bundle now provides a "login" and a "logout" mutation (and also a "me" query)
+
+Laravel:
+
+- [Native integration with the Laravel paginator](laravel-package-advanced.md#support-for-pagination) has been added
+
+Internals:
+
+- The `FieldsBuilder` class has been split in many different services (`FieldsBuilder`, `TypeHandler`, and a 
+  chain of *root type mappers*)
+- The `FieldsBuilderFactory` class has been completely removed.
+- Overall, there is not much in common internally between 4.x and 3.x. 4.x is much more flexible with many more hook points
+  than 3.x. Try it out!

website/versioned_docs/version-4.0/annotations_reference.md

@@ -0,0 +1,244 @@
+---
+id: version-4.0-annotations_reference
+title: Annotations reference
+sidebar_label: Annotations reference
+original_id: annotations_reference
+---
+
+## @Query annotation
+
+The `@Query` annotation is used to declare a GraphQL query.
+
+**Applies on**: controller methods.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *no*       | string | The name of the query. If skipped, the name of the method is used instead.
+[outputType](custom_output_types.md)     | *no*       | string | Forces the GraphQL output type of a query.
+
+## @Mutation annotation
+
+The `@Mutation` annotation is used to declare a GraphQL mutation.
+
+**Applies on**: controller methods.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *no*       | string | The name of the mutation. If skipped, the name of the method is used instead.
+[outputType](custom_output_types.md)     | *no*       | string | Forces the GraphQL output type of a query.
+
+## @Type annotation
+
+The `@Type` annotation is used to declare a GraphQL object type.
+
+**Applies on**: classes.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+class          | *no*       | string | The targeted class. If no class is passed, the type applies to the current class. The current class is assumed to be an entity. If the "class" attribute is passed, [the class annotated with `@Type` is a service](external_type_declaration.md).
+name           | *no*       | string | The name of the GraphQL type generated. If not passed, the name of the class is used. If the class ends with "Type", the "Type" suffix is removed
+default        | *no*       | bool   | Defaults to *true*. Whether the targeted PHP class should be mapped by default to this type.
+external       | *no*       | bool   | Whether this is an [external type declaration](external_type_declaration.md) or not. You usually do not need to use this attribute since this value defaults to true if a "class" attribute is set. This is only useful if you are declaring a type with no PHP class mapping using the "name" attribute.
+
+## @ExtendType annotation
+
+The `@ExtendType` annotation is used to add fields to an existing GraphQL object type.
+
+**Applies on**: classes.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+class          | see below  | string | The targeted class. [The class annotated with `@ExtendType` is a service](extend_type.md).
+name           | see below  | string | The targeted GraphQL output type.
+
+One and only one of "class" and "name" parameter can be passed at the same time.
+
+## @Field annotation
+
+The `@Field` annotation is used to declare a GraphQL field.
+
+**Applies on**: methods of classes annotated with `@Type` or `@ExtendType`.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *no*       | string | The name of the field. If skipped, the name of the method is used instead.
+[outputType](custom_output_types.md)     | *no*       | string | Forces the GraphQL output type of a query.
+
+## @SourceField annotation
+
+The `@SourceField` annotation is used to declare a GraphQL field.
+
+**Applies on**: classes annotated with `@Type` or `@ExtendType`.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *yes*       | string | The name of the field.
+[outputType](custom_output_types.md)     | *no*       | string | Forces the GraphQL output type of the field. Otherwise, return type is used.
+phpType        | *no*       | string | The PHP type of the field (as you would write it in a Docblock)
+annotations    | *no*       | array<Annotations>  | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here.
+
+**Note**: `outputType` and `phpType` are mutually exclusive.
+
+## @MagicField annotation
+
+The `@MagicField` annotation is used to declare a GraphQL field that originates from a PHP magic property (using `__get` magic method).
+
+**Applies on**: classes annotated with `@Type` or `@ExtendType`.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *yes*       | string | The name of the field.
+[outputType](custom_output_types.md)  | *no*(*)       | string | The GraphQL output type of the field.
+phpType     | *no*(*)       | string | The PHP type of the field (as you would write it in a Docblock)
+annotations    | *no*       | array<Annotations>  | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here.
+
+(*) **Note**: `outputType` and `phpType` are mutually exclusive. You MUST provide one of them.
+
+## @Logged annotation
+
+The `@Logged` annotation is used to declare a Query/Mutation/Field is only visible to logged users.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+This annotation allows no attributes.
+
+## @Right annotation
+
+The `@Right` annotation is used to declare a Query/Mutation/Field is only visible to users with a specific right.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *yes*       | string | The name of the right.
+
+## @FailWith annotation
+
+The `@FailWith` annotation is used to declare a default value to return in the user is not authorized to see a specific
+query / mutation / field (according to the `@Logged` and `@Right` annotations).
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` and one of `@Logged` or `@Right` annotations.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+*default*      | *yes*       | mixed | The value to return if the user is not authorized.
+
+## @HideIfUnauthorized annotation
+
+The `@HideIfUnauthorized` annotation is used to completely hide the query / mutation / field if the user is not authorized
+to access it (according to the `@Logged` and `@Right` annotations).
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` and one of `@Logged` or `@Right` annotations.
+
+`@HideIfUnauthorized` and `@FailWith` are mutually exclusive.
+
+## @InjectUser annotation
+
+Use the `@InjectUser` annotation to inject an instance of the current user logged in into a parameter of your 
+query / mutation / field.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+Attribute      | Compulsory | Type   | Definition
+---------------|------------|--------|--------
+*for*          | *yes*      | string | The name of the PHP parameter
+
+## @Security annotation
+
+The `@Security` annotation can be used to check fin-grained access rights.
+It is very flexible: it allows you to pass an expression that can contains custom logic.
+
+See [the fine grained security page](fine-grained-security.md) for more details.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+Attribute      | Compulsory | Type   | Definition
+---------------|------------|--------|--------
+*default*      | *yes*      | string | The security expression
+
+## @Factory annotation
+
+The `@Factory` annotation is used to declare a factory that turns GraphQL input types into objects.
+
+**Applies on**: methods from classes in the "types" namespace.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *no*       | string | The name of the input type. If skipped, the name of class returned by the factory is used instead.
+default        | *no*       | bool | If `true`, this factory will be used by default for its PHP return type. If set to `false`, you must explicitly [reference this factory using the `@Parameter` annotation](http://localhost:3000/docs/input-types#declaring-several-input-types-for-the-same-php-class).
+
+## @UseInputType annotation
+
+Used to override the GraphQL input type of a PHP parameter.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` annotation.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for*          | *yes*      | string | The name of the PHP parameter
+*inputType*    | *yes*      | string | The GraphQL input type to force for this input field
+
+## @Decorate annotation
+
+The `@Decorate` annotation is used [to extend/modify/decorate an input type declared with the `@Factory` annotation](extend_input_type.md).
+
+**Applies on**: methods from classes in the "types" namespace.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+name           | *yes*      | string | The GraphQL input type name extended by this decorator.
+
+## @Autowire annotation
+
+[Resolves a PHP parameter from the container](autowiring.md).
+
+Useful to inject services directly into `@Field` method arguments.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` annotation.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for*          | *yes*      | string | The name of the PHP parameter
+*identifier*   | *no*       | string | The identifier of the service to fetch. This is optional. Please avoid using this attribute as this leads to a "service locator" anti-pattern.
+
+## @HideParameter annotation
+
+Removes [an argument from the GraphQL schema](input_types.md#ignoring_some_parameters).
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for*          | *yes*      | string | The name of the PHP parameter to hide
+
+
+## @Validate annotation
+
+<div class="alert alert-info">This annotation is only available in the GraphQLite Laravel package</div>
+
+[Validates a user input in Laravel](laravel-package-advanced.md).
+
+**Applies on**: methods annotated with `@Query`, `@Mutation`, `@Field`, `@Factory` or `@Decorator` annotation.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for*          | *yes*      | string | The name of the PHP parameter
+*rule*         | *yes       | string | Laravel validation rules
+
+Sample:
+
+```
+@Validate(for="$email", rule="email|unique:users")
+```
+
+## @Assertion annotation
+
+[Validates a user input](validation.md).
+
+The `@Assertion` annotation  is available in the *thecodingmachine/graphqlite-symfony-validator-bridge* third party package.
+It is available out of the box if you use the Symfony bundle.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation`, `@Field`, `@Factory` or `@Decorator` annotation.
+
+Attribute      | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for*          | *yes*      | string | The name of the PHP parameter
+*constraint*   | *yes       | annotation | One (or many) Symfony validation annotations.

website/versioned_docs/version-4.0/argument_resolving.md

@@ -0,0 +1,160 @@
+---
+id: version-4.0-argument-resolving
+title: Extending argument resolving
+sidebar_label: Custom argument resolving
+original_id: argument-resolving
+---
+<small>Available in GraphQLite 4.0+</small>
+
+Using a **parameter middleware**, you can hook into the argument resolution of field/query/mutation/factory.
+
+<div class="alert alert-info">Use a parameter middleware if you want to alter the way arguments are injected  in a method 
+or if you want to alter the way input types are imported (for instance if you want to add a validation step)</div>
+
+As an example, GraphQLite uses *parameter middlewares* internally to:
+
+- Inject the Webonyx GraphQL resolution object when you type-hint on the `ResolveInfo` object. For instance:
+  ```php
+  /**
+   * @Query
+   * @return Product[]
+   */
+  public function products(ResolveInfo $info): array  
+  ```
+  In the query above, the `$info` argument is filled with the Webonyx `ResolveInfo` class thanks to the 
+  [`ResolveInfoParameterHandler parameter middleware`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Mappers/Parameters/ResolveInfoParameterHandler.php)
+- Inject a service from the container when you use the `@Autowire` annotation
+- Perform validation with the `@Validate` annotation (in Laravel package)
+
+<!-- https://docs.google.com/drawings/d/10zHfWdbvEab6_dyQBcM68_I_bXQkZtO5ePqt4jdDlk8/edit?usp=sharing -->
+
+**Parameter middlewares**
+
+![](assets/parameter_middleware.svg)
+
+Each middleware is passed number of objects describing the parameter:
+
+- a PHP `ReflectionParameter` object representing the parameter being manipulated
+- a `phpDocumentor\Reflection\DocBlock` instance (useful to analyze the `@param` comment if any)
+- a `phpDocumentor\Reflection\Type` instance (useful to analyze the type if the argument)
+- a `TheCodingMachine\GraphQLite\Annotations\ParameterAnnotations` instance. This is a collection of all custom annotations that apply to this specific argument (more on that later)
+- a `$next` handler to pass the argument resolving to the next middleware.
+
+Parameter resolution is done in 2 passes.
+
+On the first pass, middlewares are traversed. They must return a `TheCodingMachine\GraphQLite\Parameters\ParameterInterface` (an object that does the actual resolving).
+
+```php
+interface ParameterMiddlewareInterface
+{
+    public function mapParameter(ReflectionParameter $parameter, DocBlock $docBlock, ?Type $paramTagType, ParameterAnnotations $parameterAnnotations, ParameterHandlerInterface $next): ParameterInterface;
+}
+```
+
+Then, resolution actually happen by executing the resolver (this is the second pass).
+
+## Annotations parsing
+
+If you plan to use annotations while resolving arguments, your annotation should extend the [`ParameterAnnotationInterface`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Annotations/ParameterAnnotationInterface.php)
+
+For instance, if we want GraphQLite to inject a service in an argument, we can use `@Autowire(for="myService")`.
+
+The annotation looks like this:
+
+```php
+/**
+ * Use this annotation to autowire a service from the container into a given parameter of a field/query/mutation.
+ *
+ * @Annotation
+ */
+class Autowire implements ParameterAnnotationInterface
+{
+    /**
+     * @var string
+     */
+    public $for;
+
+    /**
+     * The getTarget method must return the name of the argument
+     */
+    public function getTarget(): string
+    {
+        return $this->for;
+    }
+}
+```
+
+## Writing the parameter middleware
+
+The middleware purpose is to analyze a parameter and decide whether or not it can handle it.
+
+**Parameter middleware class**
+```php
+class ContainerParameterHandler implements ParameterMiddlewareInterface
+{
+    /** @var ContainerInterface */
+    private $container;
+
+    public function __construct(ContainerInterface $container)
+    {
+        $this->container = $container;
+    }
+
+    public function mapParameter(ReflectionParameter $parameter, DocBlock $docBlock, ?Type $paramTagType, ParameterAnnotations $parameterAnnotations, ParameterHandlerInterface $next): ParameterInterface
+    {
+        // The $parameterAnnotations object can be used to fetch any annotation implementing ParameterAnnotationInterface
+        $autowire = $parameterAnnotations->getAnnotationByType(Autowire::class);
+
+        if ($autowire === null) {
+            // If there are no annotation, this middleware cannot handle the parameter. Let's ask
+            // the next middleware in the chain (using the $next object)
+            return $next->mapParameter($parameter, $docBlock, $paramTagType, $parameterAnnotations);
+        }
+
+        // We found a @Autowire annotation, let's return a parameter resolver.
+        return new ContainerParameter($this->container, $parameter->getType());
+    }
+}
+```
+
+The last step is to write the actual parameter resolver.
+
+**Parameter resolver class**
+```php
+/**
+ * A parameter filled from the container.
+ */
+class ContainerParameter implements ParameterInterface
+{
+    /** @var ContainerInterface */
+    private $container;
+    /** @var string */
+    private $identifier;
+
+    public function __construct(ContainerInterface $container, string $identifier)
+    {
+        $this->container = $container;
+        $this->identifier = $identifier;
+    }
+
+    /**
+     * The "resolver" returns the actual value that will be fed to the function.
+     */
+    public function resolve(?object $source, array $args, $context, ResolveInfo $info)
+    {
+        return $this->container->get($this->identifier);
+    }
+}
+```
+
+## Registering a parameter middleware
+
+The last step is to register the parameter middleware we just wrote:
+
+You can register your own parameter middlewares using the `SchemaFactory::addParameterMiddleware()` method.
+
+```php
+$schemaFactory->addParameterMiddleware(new ContainerParameterHandler($container));
+```
+ 
+If you are using the Symfony bundle, you can tag the service as "graphql.parameter_middleware".

website/versioned_docs/version-4.0/authentication_authorization.md

@@ -0,0 +1,151 @@
+---
+id: version-4.0-authentication_authorization
+title: Authentication and authorization
+sidebar_label: Authentication and authorization
+original_id: authentication_authorization
+---
+
+You might not want to expose your GraphQL API to anyone. Or you might want to keep some queries/mutations or fields
+reserved to some users.
+
+GraphQLite offers some control over what a user can do with your API. You can restrict access to resources:
+ 
+- based on authentication using the [`@Logged` annotation](#logged-and-right-annotations) (restrict access to logged users)
+- based on authorization using the [`@Right` annotation](#logged-and-right-annotations) (restrict access to logged users with certain rights).
+- based on fine-grained authorization using the [`@Security` annotation](fine-grained-security.md) (restrict access for some given resources to some users).
+
+<div class="alert alert-info">
+GraphQLite does not have its own security mechanism.
+Unless you're using our Symfony Bundle or our Laravel package, it is up to you to connect this feature to your framework's security mechanism.<br>
+See <a href="implementing-security.md">Connecting GraphQLite to your framework's security module</a>.
+</div>
+
+## `@Logged` and `@Right` annotations
+
+GraphQLite exposes two annotations (`@Logged` and `@Right`) that you can use to restrict access to a resource.
+
+```php
+namespace App\Controller;
+
+use TheCodingMachine\GraphQLite\Annotations\Query;
+use TheCodingMachine\GraphQLite\Annotations\Logged;
+use TheCodingMachine\GraphQLite\Annotations\Right;
+
+class UserController
+{
+    /**
+     * @Query
+     * @Logged
+     * @Right("CAN_VIEW_USER_LIST")
+     * @return User[]
+     */
+    public function users(int $limit, int $offset): array
+    {
+        // ...
+    }
+}
+```
+
+In the example above, the query `users` will only be available if the user making the query is logged AND if he
+has the `CAN_VIEW_USER_LIST` right.
+
+`@Logged` and `@Right` annotations can be used next to:
+
+* `@Query` annotations
+* `@Mutation` annotations
+* `@Field` annotations
+
+<div class="alert alert-info">By default, if a user tries to access an unauthorized query/mutation/field, an error is raised and the query fails.</div>
+
+## Not throwing errors
+
+If you do not want an error to be thrown when a user attempts to query a field/query/mutation he has no access to, you can use the `@FailWith` annotation.
+
+The `@FailWith` annotation contains the value that will be returned for users with insufficient rights.
+
+```php
+class UserController
+{
+    /**
+     * If a user is not logged or if the user has not the right "CAN_VIEW_USER_LIST",
+     * the value returned will be "null".
+     *
+     * @Query
+     * @Logged
+     * @Right("CAN_VIEW_USER_LIST")
+     * @FailWith(null)
+     * @return User[]
+     */
+    public function users(int $limit, int $offset): array
+    {
+        // ...
+    }
+}
+```
+
+## Injecting the current user as a parameter
+
+Use the `@InjectUser` annotation to get an instance of the current user logged in.
+
+```php
+namespace App\Controller;
+
+use TheCodingMachine\GraphQLite\Annotations\Query;
+use TheCodingMachine\GraphQLite\Annotations\InjectUser;
+
+class ProductController
+{
+    /**
+     * @Query
+     * @InjectUser(for="$user") 
+     * @return Product
+     */
+    public function product(int $id, User $user): Product
+    {
+        // ...
+    }
+}
+```
+
+The `@InjectUser` annotation can be used next to:
+
+* `@Query` annotations
+* `@Mutation` annotations
+* `@Field` annotations
+
+The object injected as the current user depends on your framework. It is in fact the object returned by the 
+["authentication service" configured in GraphQLite](implementing-security.md).
+
+## Hiding fields / queries / mutations
+
+By default, a user analysing the GraphQL schema can see all queries/mutations/types available.
+Some will be available to him and some won't.
+
+If you want to add an extra level of security (or if you want your schema to be kept secret to unauthorized users),
+you can use the `@HideIfUnauthorized` annotation.
+
+```php
+class UserController
+{
+    /**
+     * If a user is not logged or if the user has not the right "CAN_VIEW_USER_LIST",
+     * the schema will NOT contain the "users" query at all (so trying to call the
+     * "users" query will result in a GraphQL "query not found" error.
+     *
+     * @Query
+     * @Logged
+     * @Right("CAN_VIEW_USER_LIST")
+     * @HideIfUnauthorized()
+     * @return User[]
+     */
+    public function users(int $limit, int $offset): array
+    {
+        // ...
+    }
+}
+```
+
+While this is the most secured mode, it can have drawbacks when working with development tools
+(you need to be logged as admin to fetch the complete schema).
+
+<div class="alert alert-info">The "HideIfUnauthorized" mode was the default mode in GraphQLite 3 and is optionnal from GraphQLite 4+.</div>

website/versioned_docs/version-4.0/autowiring.md

@@ -0,0 +1,114 @@
+---
+id: version-4.0-autowiring
+title: Autowiring services
+sidebar_label: Autowiring services
+original_id: autowiring
+---
+
+GraphQLite can automatically inject services in your fields/queries/mutations signatures.
+
+Some of your fields may be computed. In order to compute these fields, you might need to call a service.
+
+Most of the time, your `@Type` annotation will be put on a model. And models do not have access to services.
+Hopefully, if you add a type-hinted service in your field's declaration, GraphQLite will automatically fill it with
+the service instance.
+
+## Sample
+
+Let's assume you are running an international store. You have a `Product` class. Each product has many names (depending
+on the language of the user).
+
+```php
+namespace App\Entities;
+
+use TheCodingMachine\GraphQLite\Annotations\Autowire;
+use TheCodingMachine\GraphQLite\Annotations\Field;
+use TheCodingMachine\GraphQLite\Annotations\Type;
+
+use Symfony\Component\Translation\TranslatorInterface;
+
+/**
+ * @Type()
+ */
+class Product
+{
+    // ...
+
+    /**
+     * @Field()
+     * @Autowire(for="$translator")
+     */
+    public function getName(TranslatorInterface $translator): string
+    {
+        return $translator->trans('product_name_'.$this->id);
+    }
+}
+```
+
+When GraphQLite queries the name, it will automatically fetch the translator service.
+
+<div class="alert alert-warning">As with most autowiring solutions, GraphQLite assumes that the service identifier
+in the container is the fully qualified class name of the type-hint. So in the example above, GraphQLite will 
+look for a service whose name is <code>Symfony\Component\Translation\TranslatorInterface</code>.</div>
+
+## Best practices
+
+It is a good idea to refrain from type-hinting on concrete implementations.
+Most often, your field declaration will be in your model. If you add a type-hint on a service, you are binding your domain
+with a particular service implementation. This makes your code tightly coupled and less testable.
+
+<div class="alert alert-error">
+Please don't do that:
+
+<pre><code>    /**
+     * @Field()
+     */
+    public function getName(MyTranslator $translator): string
+    {
+        // Your domain is suddenly tightly coupled to the MyTranslator class.
+    }
+</code></pre>
+</div>
+
+Instead, be sure to type-hint against an interface.
+
+<div class="alert alert-success">
+Do this instead:
+
+<pre><code>    /**
+     * @Field()
+     */
+    public function getName(TranslatorInterface $translator): string
+    {
+        // Good. You can switch translator implementation any time.
+    }
+</code></pre>
+</div>
+
+By type-hinting against an interface, your code remains testable and is decoupled from the service implementation.
+
+## Fetching a service by name (discouraged!)
+
+Optionally, you can specify the identifier of the service you want to fetch from the controller:
+
+```php
+/**
+ * @Autowire(for="$translator", identifier="translator")
+ */
+```
+
+<div class="alert alert-error">While GraphQLite offers the possibility to specify the name of the service to be
+autowired, we would like to emphasize that this is <strong>highly discouraged</strong>. Hard-coding a container
+identifier in the code of your class is akin to using the "service locator" pattern, which is known to be an
+anti-pattern. Please refrain from doing this as much as possible.</div>
+
+## Alternative solution
+
+You may find yourself uncomfortable with the autowiring mechanism of GraphQLite. For instance maybe:
+
+- Your service identifier in the container is not the fully qualified class name of the service (this is often true if you are not using a container supporting autowiring)
+- You do not want to inject a service in a domain object
+- You simply do not like the magic of injecting services in a method signature
+
+If you do not want to use autowiring and if you still need to access services to compute a field, please read on 
+the next chapter to learn [how to extend a type](extend_type).

website/versioned_docs/version-4.0/custom_types.md

@@ -0,0 +1,220 @@
+---
+id: version-4.0-custom-types
+title: Custom types
+sidebar_label: Custom types
+original_id: custom-types
+---
+
+In some special cases, you want to override the GraphQL return type that is attributed by default by GraphQLite.
+
+For instance:
+
+```php
+/**
+ * @Type(class=Product::class)
+ */
+class ProductType
+{
+    /**
+     * @Field(name="id")
+     */
+    public function getId(Product $source): string
+    {
+        return $source->getId();
+    }
+}
+```
+
+In the example above, GraphQLite will generate a GraphQL schema with a field `id` of type `string`:
+
+```graphql
+type Product {
+    id: String!
+}
+```
+
+GraphQL comes with an `ID` scalar type. But PHP has no such type. So GraphQLite does not know when a variable
+is an `ID` or not.
+
+You can help GraphQLite by manually specifying the output type to use:
+
+```php
+    /**
+     * @Field(name="id", outputType="ID")
+     */
+``` 
+
+## Usage
+
+The `outputType` attribute will map the return value of the method to the output type passed in parameter.
+
+You can use the `outputType` attribute in the following annotations:
+
+* `@Query`
+* `@Mutation`
+* `@Field`
+* `@SourceField`
+* `@MagicField`
+
+## Registering a custom output type (advanced)
+
+In order to create a custom output type, you need to:
+
+1. Design a class that extends `GraphQL\Type\Definition\ObjectType`.
+2. Register this class in the GraphQL schema.
+
+You'll find more details on the [Webonyx documentation](https://webonyx.github.io/graphql-php/type-system/object-types/).
+
+---
+
+In order to find existing types, the schema is using *type mappers* (classes implementing the `TypeMapperInterface` interface).
+
+You need to make sure that one of these type mappers can return an instance of your type. The way you do this will depend on the framework
+you use.
+
+### Symfony users
+
+Any class extending `GraphQL\Type\Definition\ObjectType` (and available in the container) will be automatically detected 
+by Symfony and added to the schema.
+
+If you want to automatically map the output type to a given PHP class, you will have to explicitly declare the output type
+as a service and use the `graphql.output_type` tag:
+
+```yaml
+# config/services.yaml
+services:
+    App\MyOutputType:
+        tags:
+            - { name: 'graphql.output_type', class: 'App\MyPhpClass' }
+```
+
+### Other frameworks
+
+The easiest way is to use a `StaticTypeMapper`. This class is used to register custom output types.
+
+```php
+// Sample code:
+$staticTypeMapper = new StaticTypeMapper();
+
+// Let's register a type that maps by default to the "MyClass" PHP class
+$staticTypeMapper->setTypes([
+    MyClass::class => new MyCustomOutputType()
+]);
+
+// If you don't want your output type to map to any PHP class by default, use:
+$staticTypeMapper->setNotMappedTypes([
+    new MyCustomOutputType()
+]);
+
+```
+
+The `StaticTypeMapper` instance MUST be registered in your container and linked to a `CompositeTypeMapper`
+that will aggregate all the type mappers of the application.
+
+## Registering a custom scalar type (advanced)
+
+If you need to add custom scalar types, first, check the [GraphQLite Misc. Types library](https://github.com/thecodingmachine/graphqlite-misc-types).
+It contains a number of "out-of-the-box" scalar types ready to use and you might find what you need there.
+
+You still need to develop your custom scalar type? Ok, let's get started.
+
+In order to add a scalar type in GraphQLite, you need to:
+
+- create a [Webonyx custom scalar type](https://webonyx.github.io/graphql-php/type-system/scalar-types/#writing-custom-scalar-types).
+  You do this by creating a class that extends `GraphQL\Type\Definition\ScalarType`.
+- create a "type mapper" that will map PHP types to the GraphQL scalar type. You do this by writing a class implementing the `RootTypeMapperInterface`.
+- create a "type mapper factory" that will be in charge of creating your "type mapper".
+
+```php
+interface RootTypeMapperInterface
+{
+    public function toGraphQLOutputType(Type $type, ?OutputType $subType, ReflectionMethod $refMethod, DocBlock $docBlockObj): OutputType;
+
+    public function toGraphQLInputType(Type $type, ?InputType $subType, string $argumentName, ReflectionMethod $refMethod, DocBlock $docBlockObj): InputType;
+
+    public function mapNameToType(string $typeName): NamedType;
+}
+```
+
+The `toGraphQLOutputType` and `toGraphQLInputType` are meant to map a return type (for output types) or a parameter type (for input types)
+to your GraphQL scalar type. Return your scalar type if there is a match or `null` if there no match.
+
+The `mapNameToType` should return your GraphQL scalar type if `$typeName` is the name of your scalar type.
+
+RootTypeMapper are organized **in a chain** (they are actually middlewares).
+Each instance of a `RootTypeMapper` holds a reference on the next root type mapper to be called in the chain.
+
+For instance:
+
+```php
+class AnyScalarTypeMapper implements RootTypeMapperInterface
+{
+    /** @var RootTypeMapperInterface */
+    private $next;
+
+    public function __construct(RootTypeMapperInterface $next)
+    {
+        $this->next = $next;
+    }
+
+    public function toGraphQLOutputType(Type $type, ?OutputType $subType, ReflectionMethod $refMethod, DocBlock $docBlockObj): ?OutputType
+    {
+        if ($type instanceof Scalar) {
+            // AnyScalarType is a class implementing the Webonyx ScalarType type.
+            return AnyScalarType::getInstance();
+        }
+        // If the PHPDoc type is not "Scalar", let's pass the control to the next type mapper in the chain
+        return $this->next->toGraphQLOutputType($type, $subType, $refMethod, $docBlockObj);
+    }
+
+    public function toGraphQLInputType(Type $type, ?InputType $subType, string $argumentName, ReflectionMethod $refMethod, DocBlock $docBlockObj): ?InputType
+    {
+        if ($type instanceof Scalar) {
+            // AnyScalarType is a class implementing the Webonyx ScalarType type.
+            return AnyScalarType::getInstance();
+        }
+        // If the PHPDoc type is not "Scalar", let's pass the control to the next type mapper in the chain
+        return $this->next->toGraphQLInputType($type, $subType, $argumentName, $refMethod, $docBlockObj);
+    }
+
+    /**
+     * Returns a GraphQL type by name.
+     * If this root type mapper can return this type in "toGraphQLOutputType" or "toGraphQLInputType", it should
+     * also map these types by name in the "mapNameToType" method.
+     *
+     * @param string $typeName The name of the GraphQL type
+     * @return NamedType|null
+     */
+    public function mapNameToType(string $typeName): ?NamedType
+    {
+        if ($typeName === AnyScalarType::NAME) {
+            return AnyScalarType::getInstance();
+        }
+        return null;
+    }
+}
+```
+
+Now, in order to create an instance of your `AnyScalarTypeMapper` class, you need an instance of the `$next` type mapper in the chain.
+How do you get the `$next` type mapper? Through a factory:
+
+```php
+class AnyScalarTypeMapperFactory implements RootTypeMapperFactoryInterface
+{
+    public function create(RootTypeMapperInterface $next, RootTypeMapperFactoryContext $context): RootTypeMapperInterface
+    {
+        return new AnyScalarTypeMapper($next);
+    }
+}
+```
+
+Now, you need to register this factory in your application, and we are done.
+
+You can register your own root mapper factories using the `SchemaFactory::addRootTypeMapperFactory()` method.
+
+```php
+$schemaFactory->addRootTypeMapperFactory(new AnyScalarTypeMapperFactory());
+```
+ 
+If you are using the Symfony bundle, the factory will be automatically registered, you have nothing to do (the service 
+is automatically tagged with the "graphql.root_type_mapper_factory" tag).

website/versioned_docs/version-4.0/error_handling.md

@@ -0,0 +1,185 @@
+---
+id: version-4.0-error-handling
+title: Error handling
+sidebar_label: Error handling
+original_id: error-handling
+---
+
+In GraphQL, when an error occurs, the server must add an "error" entry in the response.
+
+```json
+{
+  "errors": [
+    {
+      "message": "Name for character with ID 1002 could not be fetched.",
+      "locations": [ { "line": 6, "column": 7 } ],
+      "path": [ "hero", "heroFriends", 1, "name" ],
+      "extensions": {
+        "category": "Exception"
+      }
+    }
+  ]
+}
+```
+
+You can generate such errors with GraphQLite by throwing a `GraphQLException`.
+
+```php
+use TheCodingMachine\GraphQLite\Exceptions\GraphQLException;
+
+throw new GraphQLException("Exception message");
+```
+
+## HTTP response code
+
+By default, when you throw a `GraphQLException`, the HTTP status code will be 500.
+
+If your exception code is in the 4xx - 5xx range, the exception code will be used as an HTTP status code.
+
+```php
+// This exception will generate a HTTP 404 status code
+throw new GraphQLException("Not found", 404);
+```
+
+<div class="alert alert-info">GraphQL allows to have several errors for one request. If you have several 
+<code>GraphQLException</code> thrown for the same request, the HTTP status code used will be the highest one.</div>
+
+## Customizing the category
+
+By default, GraphQLite adds a "category" entry in the "extensions section". You can customize the category with the 
+4th parameter of the constructor:
+
+```php
+throw new GraphQLException("Not found", 404, null, "NOT_FOUND");
+```
+
+will generate:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Not found",
+      "extensions": {
+        "category": "NOT_FOUND"
+      }
+    }
+  ]
+}
+```
+
+## Customizing the extensions section
+
+You can customize the whole "extensions" section with the 5th parameter of the constructor:
+
+```php
+throw new GraphQLException("Field required", 400, null, "VALIDATION", ['field' => 'name']);
+```
+
+will generate:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Field required",
+      "extensions": {
+        "category": "VALIDATION",
+        "field": "name"
+      }
+    }
+  ]
+}
+```
+
+## Writing your own exceptions
+
+Rather that throwing the base `GraphQLException`, you should consider writing your own exception.
+
+Any exception that implements interface `TheCodingMachine\GraphQLite\Exceptions\GraphQLExceptionInterface` will be displayed
+in the GraphQL "errors" section.
+
+```php
+class ValidationException extends Exception implements GraphQLExceptionInterface
+{
+    /**
+     * Returns true when exception message is safe to be displayed to a client.
+     */
+    public function isClientSafe(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Returns string describing a category of the error.
+     *
+     * Value "graphql" is reserved for errors produced by query parsing or validation, do not use it.
+     */
+    public function getCategory(): string
+    {
+        return 'VALIDATION';
+    }
+
+    /**
+     * Returns the "extensions" object attached to the GraphQL error.
+     *
+     * @return array<string, mixed>
+     */
+    public function getExtensions(): array
+    {
+        return [];
+    }
+}
+```
+
+## Many errors for one exception
+
+Sometimes, you need to display several errors in the response. But of course, at any given point in your code, you can
+throw only one exception.
+
+If you want to display several exceptions, you can bundle these exceptions in a `GraphQLAggregateException` that you can
+throw.
+
+```php
+use TheCodingMachine\GraphQLite\Exceptions\GraphQLAggregateException;
+
+/**
+ * @Query
+ */
+public function createProduct(string $name, float $price): Product
+{
+    $exceptions = new GraphQLAggregateException();
+
+    if ($name === '') {
+        $exceptions->add(new GraphQLException('Name cannot be empty', 400, null, 'VALIDATION'));
+    }
+    if ($price <= 0) {
+        $exceptions->add(new GraphQLException('Price must be positive', 400, null, 'VALIDATION'));
+    }
+
+    if ($exceptions->hasExceptions()) {
+        throw $exceptions;
+    }
+}
+```
+
+## Webonyx exceptions
+
+GraphQLite is based on the wonderful webonyx/GraphQL-PHP library. Therefore, the Webonyx exception mechanism can
+also be used in GraphQLite. This means you can throw a `GraphQL\Error\Error` exception or any exception implementing
+[`GraphQL\Error\ClientAware` interface](http://webonyx.github.io/graphql-php/error-handling/#errors-in-graphql)
+
+Actually, the `TheCodingMachine\GraphQLite\Exceptions\GraphQLExceptionInterface` extends Webonyx's `ClientAware` interface.
+
+## Behaviour of exceptions that do not implement ClientAware
+
+If an exception that does not implement `ClientAware` is thrown, by default, GraphQLite will not catch it.
+
+The exception will propagate to your framework error handler/middleware that is in charge of displaying the classical error page.
+
+You can [change the underlying behaviour of Webonyx to catch any exception and turn them into GraphQL errors](http://webonyx.github.io/graphql-php/error-handling/#debugging-tools).
+The way you adjust the error settings depends on the framework you are using ([Symfony](symfony-bundle.md), [Laravel](laravel-package.md)).
+
+<div class="alert alert-info">To be clear: we strongly discourage changing this setting. We strongly believe that the
+default "RETHROW_UNSAFE_EXCEPTIONS" setting of Webonyx is the only sane setting (only putting in "errors" section exceptions 
+designed for GraphQL).</div>

website/versioned_docs/version-4.0/extend_input_type.md

@@ -0,0 +1,76 @@
+---
+id: version-4.0-extend_input_type
+title: Extending an input type
+sidebar_label: Extending an input type
+original_id: extend_input_type
+---
+<small>Available in GraphQLite 4.0+</small>
+
+<div class="alert alert-info">If you are not familiar with the <code>@Factory</code> tag, <a href="input-types">read first the "input types" guide</a>.</div>
+
+Fields exposed in a GraphQL input type do not need to be all part of the factory method.
+
+Just like with output type (that can be [extended using the `ExtendType` annotation](extend_type.md)), you can extend/modify
+an input type using the `@Decorate` annotation.
+
+Use the `@Decorate` annotation to add additional fields to an input type that is already declared by a `@Factory` annotation,
+or to modify the returned object.
+
+<div class="alert alert-info">
+    The <code>@Decorate</code> annotation is very useful in scenarios where you cannot touch the <code>@Factory</code> method.
+    This can happen if the <code>@Factory</code> method is defined in a third-party library or if the <code>@Factory</code> method is part
+    of auto-generated code.
+</div>
+
+Let's assume you have a `Filter` class used as an input type. You most certainly have a `@Factory` to create the input type. 
+
+```
+class MyFactory
+{
+    /**
+     * @Factory()
+     */
+    public function createFilter(string $name): Filter
+    {
+        // Let's assume you have a flexible 'Filter' class that can accept any kind of filter
+        $filter = new Filter();
+        $filter->addFilter('name', $name);
+        return $filter;
+    }
+}
+```
+
+Assuming you **cannot** modify the code of this factory, you can still modify the GraphQL input type generated by
+adding a "decorator" around the factory. 
+
+```
+class MyDecorator
+{
+    /**
+     * @Decorate(inputTypeName="FilterInput")
+     */
+    public function addTypeFilter(Filter $filter, string $type): Filter
+    {
+        $filter->addFilter('type', $type);
+        return $filter;
+    }
+}
+```
+
+In the example above, the "Filter" input type is modified. We add an additional "type" field to the input type.
+
+A few things to notice:
+
+- The decorator takes the object generated by the factory as first argument
+- The decorator MUST return an object of the same type (or a sub-type)
+- The decorator CAN contain additional parameters. They will be added to the fields of the GraphQL input type.
+- The `@Decorate` annotation must contain a `inputTypeName` attribute that contains the name of the GraphQL input type
+  that is decorated. If you did not specify this name in the `@Factory` annotation, this is by default the name of the
+  PHP class + "Input" (for instance: "Filter" => "FilterInput")
+
+
+<div class="alert alert-warning"><strong>Heads up!</strong> The <code>MyDecorator</code> class must exist in the container of your 
+application and the container identifier MUST be the fully qualified class name.<br/><br/>
+If you are using the Symfony bundle (or a framework with autowiring like Laravel), this 
+is usually not an issue as the container will automatically create the controller entry if you do not explicitly 
+declare it.</div> 

website/versioned_docs/version-4.0/extend_type.md

@@ -0,0 +1,149 @@
+---
+id: version-4.0-extend_type
+title: Extending a type
+sidebar_label: Extending a type
+original_id: extend_type
+---
+
+Fields exposed in a GraphQL type do not need to be all part of the same class.
+
+Use the `@ExtendType` annotation to add additional fields to a type that is already declared.
+
+<div class="alert alert-info">
+    Extending a type has nothing to do with type inheritance. 
+    If you are looking for a way to expose a class and its children classes, have a look at 
+    the <a href="inheritance-interfaces">Inheritance</a> section</a>
+</div>
+
+Let's assume you have a `Product` class. In order to get the name of a product, there is no `getName()` method in 
+the product because the name needs to be translated in the correct language. You have a `TranslationService` to do that.
+
+```php
+namespace App\Entities;
+
+use TheCodingMachine\GraphQLite\Annotations\Field;
+use TheCodingMachine\GraphQLite\Annotations\Type;
+
+/**
+ * @Type()
+ */
+class Product
+{
+    // ...
+
+    /**
+     * @Field()
+     */
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    /**
+     * @Field()
+     */
+    public function getPrice(): ?float
+    {
+        return $this->price;
+    }
+}
+```
+
+```php
+// You need to use a service to get the name of the product in the correct language. 
+$name = $translationService->getProductName($productId, $language);
+```
+
+Using `@ExtendType`, you can add an additional `name` field to your product:
+
+```php
+namespace App\Types;
+
+use TheCodingMachine\GraphQLite\Annotations\ExtendType;
+use TheCodingMachine\GraphQLite\Annotations\Field;
+use App\Entities\Product;
+
+/**
+ * @ExtendType(class=Product::class)
+ */
+class ProductType
+{
+    private $translationService;
+    
+    public function __construct(TranslationServiceInterface $translationService)
+    {
+        $this->translationService = $translationService;
+    }
+    
+    /**
+     * @Field()
+     */
+    public function getName(Product $product, string $language): string
+    {
+        return $this->translationService->getProductName($product->getId(), $language);
+    }
+}
+```
+
+Let's break this sample:
+
+```php
+/**
+ * @ExtendType(class=Product::class)
+ */
+```
+
+With the `@ExtendType` annotation, we tell GraphQLite that we want to add fields in the GraphQL type mapped to
+the `Product` PHP class.
+
+```php
+class ProductType
+{
+    private $translationService;
+    
+    public function __construct(TranslationServiceInterface $translationService)
+    {
+        $this->translationService = $translationService;
+    }
+    
+    // ...
+}
+```
+
+
+- The `ProductType` class must be in the types namespace. You configured this namespace when you installed GraphQLite.
+- The `ProductType` class is actually a **service**. You can therefore inject dependencies in it (like the `$translationService` in this example)
+
+<div class="alert alert-warning"><strong>Heads up!</strong> The <code>ProductType</code> class must exist in the container of your 
+application and the container identifier MUST be the fully qualified class name.<br/><br/>
+If you are using the Symfony bundle (or a framework with autowiring like Laravel), this 
+is usually not an issue as the container will automatically create the controller entry if you do not explicitly 
+declare it.</div> 
+
+```php
+/**
+ * @Field()
+ */
+public function getName(Product $product, string $language): string
+{
+    return $this->translationService->getProductName($product->getId(), $language);
+}
+```
+
+The `@Field` annotation is used to add the "name" field to the `Product` type.
+
+Take a close look at the signature. The first parameter is the "resolved object" we are working on.
+Any additional parameters are used as arguments.
+
+Using the "[Type language](https://graphql.org/learn/schema/#type-language)" notation, we defined a type extension for
+the GraphQL "Product" type:
+
+```graphql
+Extend type Product {
+    name(language: !String): String!
+}
+```
+
+<div class="alert alert-success">Type extension is a very powerful tool. Use it to add fields that needs to be 
+computed from services not available in the entity.
+</div>

website/versioned_docs/version-4.0/external_type_declaration.md

@@ -0,0 +1,160 @@
+---
+id: version-4.0-external_type_declaration
+title: External type declaration
+sidebar_label: External type declaration
+original_id: external_type_declaration
+---
+
+In some cases, you cannot or do not want to put an annotation on a domain class.
+
+For instance:
+
+* The class you want to annotate is part of a third party library and you cannot modify it
+* You are doing domain-driven design and don't want to clutter your domain object with annotations from the view layer
+* etc.
+
+## `@Type` annotation with the `class` attribute
+
+GraphQLite allows you to use a *proxy* class thanks to the `@Type` annotation with the `class` attribute:
+
+```php
+namespace App\Types;
+
+use TheCodingMachine\GraphQLite\Annotations\Type;
+use TheCodingMachine\GraphQLite\Annotations\Field;
+use App\Entities\Product;
+
+/**
+ * @Type(class=Product::class)
+ */
+class ProductType
+{    
+    /**
+     * @Field()
+     */
+    public function getId(Product $product): string
+    {
+        return $product->getId();
+    }
+}
+```
+
+The `ProductType` class must be in the *types* namespace. You configured this namespace when you installed GraphQLite.
+
+The `ProductType` class is actually a **service**. You can therefore inject dependencies in it.
+
+<div class="alert alert-warning"><strong>Heads up!</strong> The <code>ProductType</code> class must exist in the container of your application and the container identifier MUST be the fully qualified class name.<br/><br/>
+If you are using the Symfony bundle (or a framework with autowiring like Laravel), this 
+is usually not an issue as the container will automatically create the controller entry if you do not explicitly 
+declare it.</div> 
+
+In methods with a `@Field` annotation, the first parameter is the *resolved object* we are working on. Any additional parameters are used as arguments.
+
+## `@SourceField` annotation
+
+If you don't want to rewrite all *getters* of your base class, you may use the `@SourceField` annotation:
+
+```php
+use TheCodingMachine\GraphQLite\Annotations\Type;
+use TheCodingMachine\GraphQLite\Annotations\SourceField;
+use App\Entities\Product;
+
+/**
+ * @Type(class=Product::class)
+ * @SourceField(name="name")
+ * @SourceField(name="price")
+ */
+class ProductType
+{
+}
+```
+
+By doing so, you let GraphQLite know that the type exposes the `getName` method of the underlying `Product` object.
+
+Internally, GraphQLite will look for methods named `name()`, `getName()` and `isName()`).
+
+## `@MagicField` annotation
+
+If your object has no getters, but instead uses magic properties (using the magic `__get` method), you should use the `@MagicField` annotation:
+
+```php
+use TheCodingMachine\GraphQLite\Annotations\Type;
+use TheCodingMachine\GraphQLite\Annotations\SourceField;
+use App\Entities\Product;
+
+/**
+ * @Type()
+ * @MagicField(name="name", outputType="String!")
+ * @MagicField(name="price", outputType="Float")
+ */
+class ProductType
+{
+    public function __get(string $property) {
+        // return some magic property
+    }
+}
+```
+
+By doing so, you let GraphQLite know that the type exposes "name" and the "price" magic properties of the underlying `Product` object.
+
+This is particularly useful in frameworks like Laravel, where Eloquent is making a very wide use of such properties.
+
+Please note that GraphQLite has no way to know the type of a magic property. Therefore, you have specify the GraphQL type
+of each property manually.
+
+### Authentication and authorization
+
+You may also check for logged users or users with a specific right using the "annotations" property.
+
+```php
+use TheCodingMachine\GraphQLite\Annotations\Type;
+use TheCodingMachine\GraphQLite\Annotations\SourceField;
+use TheCodingMachine\GraphQLite\Annotations\Logged;
+use TheCodingMachine\GraphQLite\Annotations\Right;
+use TheCodingMachine\GraphQLite\Annotations\FailWith;
+use App\Entities\Product;
+
+/**
+ * @Type(class=Product::class)
+ * @SourceField(name="name")
+ * @SourceField(name="price", annotations={@Logged, @Right(name="CAN_ACCESS_Price", @FailWith(null)}))
+ */
+class ProductType extends AbstractAnnotatedObjectType
+{
+}
+```
+
+Any annotations described in the [Authentication and authorization page](authentication_authorization.md) can be used in the `@SourceField` "annotations" attribute.
+
+## Declaring fields dynamically (without annotations)
+
+In some very particular cases, you might not know exactly the list of `@SourceField` annotations at development time.
+If you need to decide the list of `@SourceField` at runtime, you can implement the `FromSourceFieldsInterface`:
+
+```php
+use TheCodingMachine\GraphQLite\FromSourceFieldsInterface;
+
+/**
+ * @Type(class=Product::class)
+ */
+class ProductType implements FromSourceFieldsInterface
+{
+    /**
+     * Dynamically returns the array of source fields 
+     * to be fetched from the original object.
+     *
+     * @return SourceFieldInterface[]
+     */
+    public function getSourceFields(): array
+    {
+        // You may want to enable fields conditionally based on feature flags...
+        if (ENABLE_STATUS_GLOBALLY) {
+            return [
+                new SourceField(['name'=>'status', 'logged'=>true]),
+            ];        
+        } else {
+            return [];
+        }
+    }
+}
+```

website/versioned_docs/version-4.0/features.md

@@ -0,0 +1,65 @@
+---
+id: version-4.0-features
+title: GraphQLite
+sidebar_label: GraphQLite
+original_id: features
+---
+
+<p align="center">
+    <img src="https://graphqlite.thecodingmachine.io/img/logo.svg" alt="GraphQLite logo" width="250" height="250" />
+</p>
+
+
+A PHP library that allows you to write your GraphQL queries in simple-to-write controllers.
+
+## Features
+
+* Create a complete GraphQL API by simply annotating your PHP classes
+* Framework agnostic, but Symfony, Laravel and PSR-15 bindings available!
+* Comes with batteries included: queries, mutations, mapping of arrays / iterators, file uploads, security, validation, extendable types and more!
+
+## Basic example
+
+First, declare a query in your controller:
+
+```php
+class ProductController
+{
+    /**
+     * @Query()
+     */
+    public function product(string $id): Product
+    {
+        // Some code that looks for a product and returns it.
+    }
+}
+```
+
+Then, annotate the `Product` class to declare what fields are exposed to the GraphQL API:
+
+```php
+/**
+ * @Type()
+ */
+class Product
+{
+    /**
+     * @Field()
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+    // ...
+}
+```
+
+That's it, you're good to go! Query and enjoy!
+
+```grapql
+{
+  product(id: 42) {
+    name
+  }
+}
+```

website/versioned_docs/version-4.0/field_middlewares.md

@@ -0,0 +1,140 @@
+---
+id: version-4.0-field-middlewares
+title: Adding custom annotations with Field middlewares
+sidebar_label: Custom annotations
+original_id: field-middlewares
+---
+<small>Available in GraphQLite 4.0+</small>
+
+Just like the `@Logged` or `@Right` annotation, you can develop your own annotation that extends/modifies the behaviour
+of a field/query/mutation.
+
+<div class="alert alert-warning">If you want to create an annotation that targets a single argument (like <code>@AutoWire(for="$service")</code>),
+you should rather check the documentation about <a href="argument-resolving">custom argument resolving</a></div>
+
+## Field middlewares
+
+GraphQLite is based on the Webonyx/Graphql-PHP library. In Webonyx, fields are represented by the `FieldDefinition` class.
+In order to create a `FieldDefinition` instance for your field, GraphQLite goes through a series of "middlewares".
+
+![](assets/field_middleware.svg)
+
+Each middleware is passed a `TheCodingMachine\GraphQLite\QueryFieldDescriptor` instance. This object contains all the
+parameters used to initialize the field (like the return type, the list of arguments, the resolver to be used, etc...)
+
+Each middleware must return a `GraphQL\Type\Definition\FieldDefinition` (the object representing a field in Webonyx/GraphQL-PHP).
+
+```php
+/**
+ * Your middleware must implement this interface.
+ */
+interface FieldMiddlewareInterface
+{
+    public function process(QueryFieldDescriptor $queryFieldDescriptor, FieldHandlerInterface $fieldHandler): ?FieldDefinition;
+}
+```
+
+```php
+class QueryFieldDescriptor
+{
+    public function getName() { /* ... */ }
+    public function setName(string $name)  { /* ... */ }
+    public function getType() { /* ... */ }
+    public function setType($type): void  { /* ... */ }
+    public function getParameters(): array  { /* ... */ }
+    public function setParameters(array $parameters): void  { /* ... */ }
+    public function getPrefetchParameters(): array  { /* ... */ }
+    public function setPrefetchParameters(array $prefetchParameters): void  { /* ... */ }
+    public function getPrefetchMethodName(): ?string { /* ... */ }
+    public function setPrefetchMethodName(?string $prefetchMethodName): void { /* ... */ }
+    public function setCallable(callable $callable): void { /* ... */ }
+    public function setTargetMethodOnSource(?string $targetMethodOnSource): void { /* ... */ }
+    public function isInjectSource(): bool { /* ... */ }
+    public function setInjectSource(bool $injectSource): void { /* ... */ }
+    public function getComment(): ?string { /* ... */ }
+    public function setComment(?string $comment): void { /* ... */ }
+    public function getMiddlewareAnnotations(): MiddlewareAnnotations { /* ... */ }
+    public function setMiddlewareAnnotations(MiddlewareAnnotations $middlewareAnnotations): void { /* ... */ }
+    public function getOriginalResolver(): ResolverInterface { /* ... */ }
+    public function getResolver(): callable { /* ... */ }
+    public function setResolver(callable $resolver): void { /* ... */ }
+}
+```
+
+The role of a middleware is to analyze the `QueryFieldDescriptor` and modify it (or to directly return a `FieldDefinition`).
+
+If you want the field to purely disappear, your middleware can return `null`.
+
+## Annotations parsing
+
+Take a look at the `QueryFieldDescriptor::getMiddlewareAnnotations()`.
+
+It returns the list of annotations applied to your field that implements the `MiddlewareAnnotationInterface`.
+
+Let's imagine you want to add a `@OnlyDebug` annotation that displays a field/query/mutation only in debug mode (and 
+hides the field in production). That could be useful, right?
+
+First, we have to define the annotation. Annotations are handled by the great [doctrine/annotations](https://www.doctrine-project.org/projects/doctrine-annotations/en/1.6/index.html) library.
+
+**OnlyDebug.php**
+```php
+namespace App\Annotations;
+
+use TheCodingMachine\GraphQLite\Annotations\MiddlewareAnnotationInterface;
+
+/**
+ * @Annotation
+ * @Target({"METHOD", "ANNOTATION"})
+ */
+class OnlyDebug implements MiddlewareAnnotationInterface
+{
+}
+```
+
+Apart from being a classical annotation, this class implements the `MiddlewareAnnotationInterface`. This interface
+is a "marker" interface. It does not have any methods. It is just used to tell GraphQLite that this annotation 
+is to be used by middlewares.
+
+Now, we can write a middleware that will act upon this annotation.
+
+```php
+namespace App\Middlewares;
+
+use App\Annotations\OnlyDebug;
+use TheCodingMachine\GraphQLite\Middlewares\FieldMiddlewareInterface;
+use GraphQL\Type\Definition\FieldDefinition;
+use TheCodingMachine\GraphQLite\QueryFieldDescriptor;
+
+/**
+ * Middleware in charge of hiding a field if it is annotated with @OnlyDebug and the DEBUG constant is not set
+ */
+class OnlyDebugFieldMiddleware implements FieldMiddlewareInterface
+{
+    public function process(QueryFieldDescriptor $queryFieldDescriptor, FieldHandlerInterface $fieldHandler): ?FieldDefinition
+    {
+        $annotations = $queryFieldDescriptor->getMiddlewareAnnotations();
+
+        /**
+         * @var OnlyDebug $onlyDebug
+         */
+        $onlyDebug = $annotations->getAnnotationByType(OnlyDebug::class);
+
+        if ($onlyDebug !== null && !DEBUG) {
+            // If the onlyDebug annotation is present, returns null.
+            // Returning null will hide the field.
+            return null;
+        }
+
+        // Otherwise, let's continue the middleware pipe without touching anything.
+        return $fieldHandler->handle($queryFieldDescriptor);
+    }
+}
+```
+
+The final thing we have to do is to register the middleware.
+
+- Assuming you are using the `SchemaFactory` to initialize GraphQLite, you can register the field middleware using:
+  ```php
+  $schemaFactory->addFieldMiddleware(new OnlyDebugFieldMiddleware());
+  ```
+- If you are using the Symfony bundle, you can register your field middleware services by tagging them with the `graphql.field_middleware` tag.

website/versioned_docs/version-4.0/fine-grained-security.md

@@ -0,0 +1,192 @@
+---
+id: version-4.0-fine-grained-security
+title: Fine grained security
+sidebar_label: Fine grained security
+original_id: fine-grained-security
+---
+
+If the [`@Logged` and `@Right` annotations](authentication_authorization.md#logged-and-right-annotations) are not 
+granular enough for your needs, you can use the advanced `@Security` annotation.
+
+Using the `@Security` annotation, you can write an *expression* that can contain custom logic. For instance:
+
+- Check that a user can access a given resource
+- Check that a user has one right or another right
+- ...
+
+## Using the @Security annotation
+
+The `@Security` annotation is very flexible: it allows you to pass an expression that can contains custom logic:
+
+```php
+use TheCodingMachine\GraphQLite\Annotations\Security;
+
+// ...
+
+/**
+ * @Query
+ * @Security("is_granted('ROLE_ADMIN') or is_granted('POST_SHOW', post)")
+ */
+public function getPost(Post $post): array
+{
+    // ...
+}
+```
+
+The *expression* defined in the `@Security` annotation must conform to [Symfony's Expression Language syntax](https://symfony.com/doc/4.4/components/expression_language/syntax.html)
+
+<div class="alert alert-info">
+    If you are a Symfony user, you might already be used to the <code>@Security</code> annotation. Most of the inspiration
+    of this annotation comes from Symfony. Warning though! GraphQLite's <code>@Security</code> annotation and 
+    Symfony's <code>@Security</code> annotation are slightly different. Especially, the two annotations do not live
+    in the same namespace!
+</div>
+
+## The `is_granted` function
+
+Use the `is_granted` function to check if a user has a special right.
+
+```php
+@Security("is_granted('ROLE_ADMIN')")
+```
+
+is similar to
+
+```php
+@Right("ROLE_ADMIN")
+```
+
+In addition, the `is_granted` function accepts a second optional parameter: the "scope" of the right.
+
+```php
+/**
+ * @Query
+ * @Security("is_granted('POST_SHOW', post)")
+ */
+public function getPost(Post $post): array
+{
+    // ...
+}
+```
+
+In the example above, the `getPost` method can be called only if the logged user has the 'POST_SHOW' permission on the
+`$post` object. You can notice that the `$post` object comes from the parameters.
+
+## Accessing method parameters
+
+All parameters passed to the method can be accessed in the `@Security` expression.
+
+```php
+/**
+ * @Query
+ * @Security("startDate < endDate", statusCode=400, message="End date must be after start date")
+ */
+public function getPosts(DateTimeImmutable $startDate, DateTimeImmutable $endDate): array
+{
+    // ...
+}
+```
+
+In the example above, we tweak a bit the Security annotation purpose to do simple input validation.
+
+## Setting HTTP code and error message
+
+You can use the `statusCode` and `message` attributes to set the HTTP code and GraphQL error message.
+
+```php
+/**
+ * @Query
+ * @Security("is_granted('POST_SHOW', post)", statusCode=404, message="Post not found (let's pretend the post does not exists!)")
+ */
+public function getPost(Post $post): array
+{
+    // ...
+}
+```
+
+Note: since a single GraphQL call contain many errors, 2 errors might have conflicting HTTP status code.
+The resulting status code is up to the GraphQL middleware you use. Most of the time, the status code with the 
+higher error code will be returned.
+
+## Setting a default value
+
+If you do not want an error to be thrown when the security condition is not met, you can use the `failWith` attribute
+to set a default value.
+
+```php
+/**
+ * @Field
+ * @Security("is_granted('CAN_SEE_MARGIN', this)", failWith=null)
+ */
+public function getMargin(): float
+{
+    // ...
+}
+```
+
+The `failWith` attribute behaves just like the [`@FailWith` annotation](authentication_authorization.md#not-throwing-errors)
+but for a given `@Security` annotation.
+
+You cannot use the `failWith` attribute along `statusCode` or `message` attributes.
+
+## Accessing the user
+
+You can use the `user` variable to access the currently logged user.
+You can use the `is_logged()` function to check if a user is logged or not.
+
+```php
+/**
+ * @Query
+ * @Security("is_logged() && user.age > 18")
+ */
+public function getNSFWImages(): array
+{
+    // ...
+}
+```
+
+## Accessing the current object
+
+You can use the `this` variable to access any (public) property / method of the current class.
+
+```php
+class Post {
+    /**
+     * @Query
+     * @Security("this.canAccess(post, user)")
+     */
+    public function getPost(Post $post): array
+    {
+        // ...
+    }
+   
+    public function canAccess(Post $post, User $user): bool
+    {
+        // Some custom logic here
+    }
+}
+```
+
+## Available scope
+
+The `@Security` annotation can be used in any query, mutation or field, so anywhere you have a `@Query`, `@Mutation`
+or `@Field` annotation.
+
+## How to restrict access to a given resource
+
+The `is_granted` method can be used to restrict access to a specific resource.
+
+```php
+@Security("is_granted('POST_SHOW', post)")
+```
+
+If you are wondering how to configure these fine-grained permissions, this is not something that GraphQLite handles 
+itself. Instead, this depends on the framework you are using.
+
+If you are using Symfony, you will [create a custom voter](https://symfony.com/doc/current/security/voters.html).
+
+If you are using Laravel, you will [create a Gate or a Policy](https://laravel.com/docs/6.x/authorization).
+
+If you are using another framework, you need to know that the `is_granted` function simply forwards the call to 
+the `isAllowed` method of the configured `AuthorizationSerice`. See [Connecting GraphQLite to your framework's security module
+](implementing-security.md) for more details

website/versioned_docs/version-4.0/implementing-security.md

@@ -0,0 +1,59 @@
+---
+id: version-4.0-implementing-security
+title: Connecting GraphQLite to your framework's security module
+sidebar_label: Connecting security to your framework
+original_id: implementing-security
+---
+
+<div class="alert alert-info">
+    This step is NOT necessary for users using GraphQLite through the Symfony Bundle or the Laravel package
+</div>
+
+GraphQLite needs to know if a user is logged or not, and what rights it has.
+But this is specific of the framework you use.
+
+To plug GraphQLite to your framework's security mechanism, you will have to provide two classes implementing: 
+
+* `TheCodingMachine\GraphQLite\Security\AuthenticationServiceInterface`
+* `TheCodingMachine\GraphQLite\Security\AuthorizationServiceInterface`
+
+Those two interfaces act as adapters between GraphQLite and your framework:
+
+```php
+interface AuthenticationServiceInterface
+{
+    /**
+     * Returns true if the "current" user is logged
+     */
+    public function isLogged(): bool;
+
+    /**
+     * Returns an object representing the current logged user.
+     * Can return null if the user is not logged.
+     */
+    public function getUser(): ?object;
+}
+``` 
+
+```php
+interface AuthorizationServiceInterface
+{
+    /**
+     * Returns true if the "current" user has access to the right "$right"
+     *
+     * @param mixed $subject The scope this right applies on. $subject is typically an object or a FQCN. Set $subject to "null" if the right is global.
+     */
+    public function isAllowed(string $right, $subject = null): bool;
+}
+```
+
+You need to write classes that implement these interfaces. Then, you must register those classes with GraphQLite.
+It you are [using the `SchemaFactory`](other_frameworks.md), you can register your classes using:
+
+```php
+// Configure an authentication service (to resolve the @Logged annotations).
+$schemaFactory->setAuthenticationService($myAuthenticationService);
+// Configure an authorization service (to resolve the @Right annotations).
+$schemaFactory->setAuthorizationService($myAuthorizationService);
+```
+

website/versioned_docs/version-4.0/inheritance-interfaces.md

@@ -0,0 +1,177 @@
+---
+id: version-4.0-inheritance-interfaces
+title: Inheritance and interfaces
+sidebar_label: Inheritance and interfaces
+original_id: inheritance-interfaces
+---
+
+## Modeling inheritance
+
+Some of your entities may extend other entities. GraphQLite will do its best to represent this hierarchy of objects in GraphQL using interfaces.
+
+Let's say you have two classes, `Contact` and `User` (which extends `Contact`):
+
+```php
+/**
+ * @Type
+ */
+class Contact
+{
+    // ...
+}
+
+/**
+ * @Type
+ */
+class User extends Contact
+{
+    // ...
+}
+```
+
+Now, let's assume you have a query that returns a contact:
+
+```php
+class ContactController
+{
+    /**
+     * @Query()
+     */
+    public function getContact(): Contact
+    {
+        // ...
+    }
+}
+```
+
+When writing your GraphQL query, you are able to use fragments to retrieve fields from the `User` type:
+
+```graphql
+contact {
+    name
+    ... User {
+       email
+    }
+}
+``` 
+
+Written in [GraphQL type language](https://graphql.org/learn/schema/#type-language), the representation of types
+would look like this:
+
+```graphql
+interface ContactInterface {
+    // List of fields declared in Contact class
+}
+
+type Contact implements ContactInterface {
+    // List of fields declared in Contact class
+}
+
+type User implements ContactInterface {
+    // List of fields declared in Contact and User classes
+}
+```
+
+Behind the scene, GraphQLite will detect that the `Contact` class is extended by the `User` class. 
+Because the class is extended, a GraphQL `ContactInterface` interface is created dynamically.
+
+The GraphQL `User` type will also automatically implement this `ContactInterface`. The interface contains all the fields
+available in the `Contact` type.
+
+## Mapping interfaces
+
+If you want to create a pure GraphQL interface, you can also add a `@Type` annotation on a PHP interface.
+
+```php
+/**
+ * @Type
+ */
+interface UserInterface
+{
+    /**
+     * @Field
+     */
+    public function getUserName(): string;
+}
+```
+
+This will automatically create a GraphQL interface whose description is:
+
+```graphql
+interface UserInterface {
+    userName: String!
+}
+```
+
+### Implementing interfaces
+
+You don't have to do anything special to implement an interface in your GraphQL types.
+Simply "implement" the interface in PHP and you are done!
+
+```php
+/**
+ * @Type
+ */
+class User implements UserInterface
+{
+    public function getUserName(): string;
+}
+```
+
+This will translate in GraphQL schema as:
+
+```graphql
+interface UserInterface {
+    userName: String!
+}
+
+type User implements UserInterface {
+    userName: String!
+}
+```
+
+Please note that you do not need to put the `@Field` annotation again in the implementing class.
+
+### Interfaces without an explicit implementing type
+
+You don't have to explicitly put a `@Type` annotation on the class implementing the interface (though this
+is usually a good idea).
+
+```php
+/**
+ * Look, this class has no @Type annotation
+ */
+class User implements UserInterface
+{
+    public function getUserName(): string;
+}
+```
+
+```php
+class UserController
+{
+    /**
+     * @Query()
+     */
+    public function getUser(): UserInterface // This will work!
+    {
+        // ...
+    }
+}
+```
+
+<div class="alert alert-info">If GraphQLite cannot find a proper GraphQL Object type implementing an interface, it
+will create an object type "on the fly".</div>
+
+In the example above, because the `User` class has no `@Type` annotations, GraphQLite will
+create a `UserImpl` type that implements `UserInterface`.
+
+```graphql
+interface UserInterface {
+    userName: String!
+}
+
+type UserImpl implements UserInterface {
+    userName: String!
+}
+```

website/versioned_docs/version-4.0/input_types.md

@@ -0,0 +1,239 @@
+---
+id: version-4.0-input-types
+title: Input types
+sidebar_label: Input types
+original_id: input-types
+---
+
+Let's admit you are developing an API that returns a list of cities around a location.
+
+Your GraphQL query might look like this:
+
+```php
+class MyController
+{
+    /**
+     * @Query
+     * @return City[]
+     */
+    public function getCities(Location $location, float $radius): array
+    {
+        // Some code that returns an array of cities.
+    }
+}
+
+// Class Location is a simple value-object.
+class Location
+{
+    private $latitude;
+    private $longitude;
+
+    public function __construct(float $latitude, float $longitude)
+    {
+        $this->latitude = $latitude;
+        $this->longitude = $longitude;
+    }
+
+    public function getLatitude(): float
+    {
+        return $this->latitude;
+    }
+
+    public function getLongitude(): float
+    {
+        return $this->longitude;
+    }
+}
+```
+
+If you try to run this code, you will get the following error:
+
+```
+CannotMapTypeException: cannot map class "Location" to a known GraphQL input type. Check your TypeMapper configuration.
+```
+
+You are running into this error because GraphQLite does not know how to handle the `Location` object.
+
+In GraphQL, an object passed in parameter of a query or mutation (or any field) is called an **Input Type**.
+
+In order to declare that type, in GraphQLite, we will declare a **Factory**.
+
+A **Factory** is a method that takes in parameter all the fields of the input type and return an object.
+
+Here is an example of factory:
+
+```
+class MyFactory
+{
+    /**
+     * The Factory annotation will create automatically a LocationInput input type in GraphQL.    
+     *
+     * @Factory()
+     */
+    public function createLocation(float $latitude, float $longitude): Location
+    {
+        return new Location($latitude, $longitude);
+    }
+}
+```
+
+and now, you can run query like this:
+
+```
+mutation {
+  getCities(location: {
+              latitude: 45.0,
+              longitude: 0.0,
+            },
+            radius: 42)
+  {
+    id,
+    name
+  }
+}
+```
+
+- Factories must be declared with the **@Factory** annotation.
+- The parameters of the factories are the field of the GraphQL input type
+
+A few important things to notice:
+
+- The container MUST contain the factory class. The identifier of the factory MUST be the fully qualified class name of the class that contains the factory.
+  This is usually already the case if you are using a container with auto-wiring capabilities
+- We recommend that you put the factories in the same directories as the types. 
+
+### Specifying the input type name
+
+The GraphQL input type name is derived from the return type of the factory.
+
+Given the factory below, the return type is "Location", therefore, the GraphQL input type will be named "LocationInput".
+
+```
+/**
+ * @Factory()
+ */
+public function createLocation(float $latitude, float $longitude): Location
+{
+    return new Location($latitude, $longitude);
+}
+```
+
+In case you want to override the input type name, you can use the "name" attribute of the @Factory annotation:
+
+```
+/**
+ * @Factory(name="MyNewInputName", default=true)
+ */
+```
+
+Note that you need to add the "default" attribute is you want your factory to be used by default (more on this in 
+the next chapter).
+
+Unless you want to have several factories for the same PHP class, the input type name will be completely transparent 
+to you, so there is no real reason to customize it.
+
+### Forcing an input type
+
+You can use the `@UseInputType` annotation to force an input type of a parameter.
+
+Let's say you want to force a parameter to be of type "ID", you can use this:
+
+```php
+/**
+ * @Factory()
+ * @UseInputType(for="$id", inputType="ID!")
+ */
+public function getProductById(string $id): Product
+{
+    return $this->productRepository->findById($id);
+}
+```
+
+### Declaring several input types for the same PHP class
+<small>Available in GraphQLite 4.0+</small>
+
+There are situations where a given PHP class might use one factory or another depending on the context.
+
+This is often the case when your objects map database entities.
+In these cases, you can use combine the use of `@UseInputType` and `@Factory` annotation to achieve your goal.
+
+Here is an annotated sample:
+
+```php
+/**
+ * This class contains 2 factories to create Product objects.
+ * The "getProduct" method is used by default to map "Product" classes.
+ * The "createProduct" method will generate another input type named "CreateProductInput"
+ */
+class ProductFactory
+{
+    // ...
+    
+    /**
+     * This factory will be used by default to map "Product" classes.
+     * @Factory(name="ProductRefInput", default=true)
+     */
+    public function getProduct(string $id): Product
+    {
+        return $this->productRepository->findById($id);
+    }
+    /**
+     * We specify a name for this input type explicitly.
+     * @Factory(name="CreateProductInput", default=false)
+     */
+    public function createProduct(string $name, string $type): Product
+    {
+        return new Product($name, $type);
+    }
+}
+
+class ProductController
+{
+    /**
+     * The "createProduct" factory will be used for this mutation.
+     * 
+     * @Mutation
+     * @UseInputType(for="$product", inputType="CreateProductInput!")
+     */
+    public function saveProduct(Product $product): Product
+    {
+        // ...
+    }
+    
+    /**
+     * The default "getProduct" factory will be used for this query.
+     *
+     * @Query
+     * @return Color[]
+     */
+    public function availableColors(Product $product): array
+    {
+        // ...
+    }
+}
+```
+
+### Ignoring some parameters
+<small>Available in GraphQLite 4.0+</small>
+
+GraphQLite will automatically map all your parameters to an input type.
+But sometimes, you might want to avoid exposing some of those parameters.
+
+Image your `getProductById` has an additional `lazyLoad` parameter. This parameter is interesting when you call
+directly the function in PHP because you can have some level of optimisation on your code. But it is not something that 
+you want to expose in the GraphQL API. Let's hide it! 
+
+```php
+/**
+ * @Factory()
+ * @HideParameter(for="$lazyLoad")
+ */
+public function getProductById(string $id, bool $lazyLoad = true): Product
+{
+    return $this->productRepository->findById($id, $lazyLoad);
+}
+```
+
+With the `@HideParameter` annotation, you can choose to remove from the GraphQL schema any argument.
+
+To be able to hide an argument, the argument must have a default value.

website/versioned_docs/version-4.0/internals.md

@@ -0,0 +1,153 @@
+---
+id: version-4.0-internals
+title: Internals
+sidebar_label: Internals
+original_id: internals
+---
+<script src="https://unpkg.com/mermaid@8.0.0/dist/mermaid.min.js"></script>
+
+## Mapping types
+
+The core of GraphQLite is its ability to map PHP types to GraphQL types. This mapping is performed by a series of
+"type mappers".
+
+GraphQLite contains 4 categories of type mappers:
+
+- **Parameter mappers**
+- **Root type mappers**
+- **Recursive (class) type mappers**
+- **(class) type mappers**
+
+
+<script>
+mermaid.initialize({
+  theme: 'forest',
+  // themeCSS: '.node rect { fill: red; }',
+  logLevel: 3,
+  flowchart: { curve: 'linear' },
+  gantt: { axisFormat: '%m/%d/%Y' },
+  sequence: { actorMargin: 50 },
+});
+</script>
+<div class="mermaid">
+  graph TD
+  classDef custom fill:#cfc,stroke:#7a7,stroke-width:2px,stroke-dasharray: 5, 5;
+  subgraph RootTypeMapperInterface
+    NullableTypeMapperAdapter-->CompoundTypeMapper
+    CompoundTypeMapper-->IteratorTypeMapper
+    IteratorTypeMapper-->YourCustomRootTypeMapper
+    YourCustomRootTypeMapper-->MyCLabsEnumTypeMapper
+    MyCLabsEnumTypeMapper-->BaseTypeMapper
+    BaseTypeMapper-->FinalRootTypeMapper
+  end
+  subgraph RecursiveTypeMapperInterface
+    BaseTypeMapper-->RecursiveTypeMapper
+  end
+  subgraph TypeMapperInterface
+    RecursiveTypeMapper-->YourCustomTypeMapper
+    YourCustomTypeMapper-->PorpaginasTypeMapper
+    PorpaginasTypeMapper-->GlobTypeMapper
+  end
+  class YourCustomRootTypeMapper,YourCustomTypeMapper custom;
+
+</div>
+
+## Root type mappers
+
+(Classes implementing the [`RootTypeMapperInterface`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Mappers/Root/RootTypeMapperInterface.php))
+
+These type mappers are the first type mappers called.
+
+They are responsible for:
+ 
+ - mapping scalar types (for instance mapping the "int" PHP type to GraphQL Integer type)
+ - detecting nullable/non-nullable types (for instance interpreting "?int" or "int|null")
+ - mapping list types (mapping a PHP array to a GraphQL list)
+ - mapping union types
+ - mapping enums
+
+Root type mappers have access to the *context* of a type: they can access the PHP DocBlock and read annotations.
+If you want to write a custom type mapper that needs access to annotations, it needs to be a "root type mapper".
+
+GraphQLite provides 6 classes implementing `RootTypeMapperInterface`:
+
+ - `NullableTypeMapperAdapter`: a type mapper in charge of making GraphQL types non-nullable if the PHP type is non-nullable
+ - `CompoundTypeMapper`: a type mapper in charge of union types
+ - `IteratorTypeMapper`: a type mapper in charge of iterable types (for instance: `MyIterator|User[]`)
+ - `MyCLabsEnumTypeMapper`: maps MyCLabs/enum types to GraphQL enum types
+ - `BaseTypeMapper`: maps scalar types and lists. Passes the control to the "recursive type mappers" if an object is encountered.
+ - `FinalRootTypeMapper`: the last type mapper of the chain, used to throw error if no other type mapper managed to handle the type.
+
+Type mappers are organized in a chain; each type-mapper is responsible for calling the next type mapper.
+
+<div class="mermaid">
+  graph TD
+  classDef custom fill:#cfc,stroke:#7a7,stroke-width:2px,stroke-dasharray: 5, 5;
+  subgraph RootTypeMapperInterface
+    NullableTypeMapperAdapter-->CompoundTypeMapper
+    CompoundTypeMapper-->IteratorTypeMapper
+    IteratorTypeMapper-->YourCustomRootTypeMapper
+    YourCustomRootTypeMapper-->MyCLabsEnumTypeMapper
+    MyCLabsEnumTypeMapper-->BaseTypeMapper
+    BaseTypeMapper-->FinalRootTypeMapper
+  end
+  class YourCustomRootTypeMapper custom;
+</div>
+
+
+## Class type mappers
+
+(Classes implementing the [`TypeMapperInterface`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Mappers/TypeMapperInterface.php))
+
+Class type mappers are mapping PHP classes to GraphQL object types.
+
+GraphQLite provide 3 default implementations:
+
+ - `CompositeTypeMapper`: a type mapper that delegates mapping to other type mappers using the Composite Design Pattern.
+ - `GlobTypeMapper`: scans classes in a directory for the `@Type` or `@ExtendType` annotation and maps those to GraphQL types
+ - `PorpaginasTypeMapper`: maps and class implementing the Porpaginas `Result` interface to a [special paginated type](pagination.md).
+
+### Registering a type mapper in Symfony
+
+If you are using the GraphQLite Symfony bundle, you can register a type mapper by tagging the service with the "graphql.type_mapper" tag.
+
+### Registering a type mapper using the SchemaFactory
+
+If you are using the `SchemaFactory` to bootstrap GraphQLite, you can register a type mapper using the `SchemaFactory::addTypeMapper` method.
+
+## Recursive type mappers
+
+(Classes implementing the [`RecursiveTypeMapperInterface`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Mappers/RecursiveTypeMapperInterface.php))
+
+There is only one implementation of the `RecursiveTypeMapperInterface`: the `RecursiveTypeMapper`.
+
+Standard "class type mappers" are mapping a given PHP class to a GraphQL type. But they do not handle class hierarchies.
+This is the role of the "recursive type mapper".
+
+Imagine that class "B" extends class "A" and class "A" maps to GraphQL type "AType".
+
+Since "B" *is a* "A", the "recursive type mapper" role is to make sure that "B" will also map to GraphQL type "AType". 
+
+## Parameter mapper middlewares
+
+"Parameter middlewares" are used to decide what argument should be injected into a parameter.
+
+Let's have a look at a simple query:
+
+```php
+/**
+ * @Query
+ * @return Product[]
+ */
+public function products(ResolveInfo $info): array
+```
+
+As you may know, [the `ResolveInfo` object injected in this query comes from Webonyx/GraphQL-PHP library](query_plan.md).
+GraphQLite knows that is must inject a `ResolveInfo` instance because it comes with a [`ResolveInfoParameterHandler`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Mappers/Parameters/ResolveInfoParameterHandler.php) class
+that implements the [`ParameterMiddlewareInterface`](https://github.com/thecodingmachine/graphqlite/blob/master/src/Mappers/Parameters/ParameterMiddlewareInterface.php)).
+
+You can register your own parameter middlewares using the `SchemaFactory::addParameterMiddleware()` method, or by tagging the
+service as "graphql.parameter_middleware" if you are using the Symfony bundle.
+
+<div class="alert alert-info">Use a parameter middleware if you want to inject an argument in a method and if this argument
+is not a GraphQL input type or if you want to alter the way input types are imported (for instance if you want to add a validation step)</div>

website/versioned_docs/version-4.0/laravel-package-advanced.md

@@ -0,0 +1,204 @@
+---
+id: version-4.0-laravel-package-advanced
+title: Laravel package: advanced usage
+sidebar_label: Laravel specific features
+original_id: laravel-package-advanced
+---
+
+The Laravel package comes with a number of features to ease the integration of GraphQLite in Laravel.
+
+## Support for Laravel validation rules
+
+The GraphQLite Laravel package comes with a special `@Validate` annotation to use Laravel validation rules in your 
+input types.
+
+```php
+use TheCodingMachine\GraphQLite\Laravel\Annotations\Validate;
+
+class MyController
+{
+    /**
+     * @Mutation
+     * @Validate(for="$email", rule="email|unique:users")
+     * @Validate(for="$password", rule="gte:8")
+     */
+    public function createUser(string $email, string $password): User
+    {
+        // ...
+    }
+}
+```
+
+You can use the `@Validate` annotation in any query / mutation / field / factory / decorator.
+
+If a validation fails to pass, the message will be printed in the "errors" section and you will get a HTTP 400 status code:
+
+```json
+{
+    "errors": [
+        {
+            "message": "The email must be a valid email address.",
+            "extensions": {
+                "argument": "email",
+                "category": "Validate"
+            }
+        },
+        {
+            "message": "The password must be greater than or equal 8 characters.",
+            "extensions": {
+                "argument": "password",
+                "category": "Validate"
+            }
+        }
+    ]
+}
+```
+
+You can use any validation rule described in [the Laravel documentation](https://laravel.com/docs/6.x/validation#available-validation-rules)
+
+## Support for pagination
+
+In your query, if you explicitly return an object that extends the `Illuminate\Pagination\LengthAwarePaginator` class,
+the query result will be wrapped in a "paginator" type.
+
+```php
+class MyController
+{
+    /**
+     * @Query
+     * @return Product[]
+     */
+    public function products(): Illuminate\Pagination\LengthAwarePaginator
+    {
+        return Product::paginate(15);
+    }
+}
+```
+
+Notice that:
+
+- the method return type MUST BE `Illuminate\Pagination\LengthAwarePaginator` or a class extending `Illuminate\Pagination\LengthAwarePaginator`
+- you MUST add a `@return` statement to help GraphQLite find the type of the list
+
+Once this is done, you can get plenty of useful information about this page:
+
+```
+products {
+    items {      # The items for the selected page
+        id
+        name
+    }
+    totalCount   # The total count of items.
+    lastPage     # Get the page number of the last available page.
+    firstItem    # Get the "index" of the first item being paginated.
+    lastItem     # Get the "index" of the last item being paginated.
+    hasMorePages # Determine if there are more items in the data source.
+    perPage      # Get the number of items shown per page.
+    hasPages     # Determine if there are enough items to split into multiple pages.
+    currentPage  # Determine the current page being paginated.
+    isEmpty      # Determine if the list of items is empty or not.
+    isNotEmpty   # Determine if the list of items is not empty.
+}
+```
+
+
+<div class="alert alert-warning">Be sure to type hint on the class (<code>Illuminate\Pagination\LengthAwarePaginator</code>)
+and not on the interface (<code>Illuminate\Contracts\Pagination\LengthAwarePaginator</code>). The interface
+itself is not iterable (it does not extend <code>Traversable</code>) and therefore, GraphQLite will refuse to
+iterate over it.</div>
+
+### Simple paginator
+
+Note: if you are using `simplePaginate` instead of `paginate`, you can type hint on the `Illuminate\Pagination\Paginator` class.
+
+```php
+class MyController
+{
+    /**
+     * @Query
+     * @return Product[]
+     */
+    public function products(): Illuminate\Pagination\Paginator
+    {
+        return Product::simplePaginate(15);
+    }
+}
+```
+
+The behaviour will be exactly the same except you will be missing the `totalCount` and `lastPage` fields.
+
+## Using GraphQLite with Eloquent efficiently
+
+In GraphQLite, you are supposed to put a `@Field` annotation on each getter.
+
+Eloquent uses PHP magic properties to expose your database records.
+Because Eloquent relies on magic properties, it is quite rare for an Eloquent model to have proper getters and setters.
+
+So we need to find a workaround. GraphQLite comes with a `@MagicField` annotation to help you
+working with magic properties.
+
+```php
+/**
+ * @Type()
+ * @MagicField(name="id" outputType="ID!")
+ * @MagicField(name="name" phpType="string")
+ * @MagicField(name="categories" phpType="Category[]")
+ */
+class Product extends Model
+{
+}
+```
+
+Please note that since the properties are "magic", they don't have a type. Therefore,
+you need to pass either the "outputType" attribute with the GraphQL type matching the property,
+or the "phpType" attribute with the PHP type matching the property.
+
+### Pitfalls to avoid with Eloquent
+
+When designing relationships in Eloquent, you write a method to expose that relationship this way:
+
+```php
+class User extends Model
+{
+    /**
+     * Get the phone record associated with the user.
+     */
+    public function phone()
+    {
+        return $this->hasOne('App\Phone');
+    }
+}
+```
+
+It would be tempting to put a `@Field` annotation on the `phone()` method, but this will not work. Indeed,
+the `phone()` method does not return a `App\Phone` object. It is the `phone` magic property that returns it.
+
+In short:
+
+<div class="alert alert-error">This does not work:
+<pre><code class="hljs css language-php">
+class User extends Model
+{
+    /**
+     * @Field
+     */
+    public function phone()
+    {
+        return $this->hasOne('App\Phone');
+    }
+}</code></pre>
+</div>
+
+<div class="alert alert-success">This works:
+<pre><code class="hljs css language-php">
+/**
+ * @MagicField(name="phone", phpType="App\\Phone")
+ */
+class User extends Model
+{
+    public function phone()
+    {
+        return $this->hasOne('App\Phone');
+    }
+}</code></pre>
+</div>

website/versioned_docs/version-4.0/laravel-package.md

@@ -0,0 +1,147 @@
+---
+id: version-4.0-laravel-package
+title: Getting started with Laravel
+sidebar_label: Laravel package
+original_id: laravel-package
+---
+
+The GraphQLite-Laravel package is compatible with **Laravel 5.7+** and **Laravel 6.x**.
+
+## Installation
+
+Open a terminal in your current project directory and run:
+
+```console
+$ composer require thecodingmachine/graphqlite-laravel
+```
+
+If you want to publish the configuration (in order to edit it), run:
+
+```console
+$ php artisan vendor:publish --provider=TheCodingMachine\GraphQLite\Laravel\Providers\GraphQLiteServiceProvider
+```
+
+You can then configure the library by editing `config/graphqlite.php`.
+
+**config/graphqlite.php**
+```php
+<?php
+
+use GraphQL\Error\Debug;
+
+return [
+    /*
+     |--------------------------------------------------------------------------
+     | GraphQLite Configuration
+     |--------------------------------------------------------------------------
+     |
+     | Use this configuration to customize the namespace of the controllers and
+     | types.
+     | These namespaces must be autoloadable from Composer.
+     | GraphQLite will find the path of the files based on composer.json settings.
+     |
+     | You can put a single namespace, or an array of namespaces.
+     |
+     */
+    'controllers' => 'App\\Http\\Controllers',
+    'types' => 'App\\',
+    'debug' => Debug::RETHROW_UNSAFE_EXCEPTIONS,
+    'uri' => env('GRAPHQLITE_URI', '/graphql'),
+    'middleware' => ['web'],
+    'guard' => ['web'],
+];
+```
+
+The debug parameters are detailed in the [documentation of the Webonyx GraphQL library](https://webonyx.github.io/graphql-php/error-handling/)
+which is used internally by GraphQLite.
+
+## Configuring CSRF protection
+
+<div class="alert alert-warning">By default, the <code>/graphql</code> route is placed under <code>web</code> middleware group which requires a 
+<a href="https://laravel.com/docs/6.x/csrf">CSRF token</a>.</div>
+
+You have 3 options:
+
+- Use the `api` middleware
+- Disable CSRF for GraphQL routes
+- or configure your GraphQL client to pass the `X-CSRF-TOKEN` with every GraphQL query
+
+### Use the `api` middleware
+
+If you plan to use graphql for server-to-server connection only, you should probably configure GraphQLite to use the 
+`api` middleware instead of the `web` middleware:
+
+**config/graphqlite.php**
+```php
+<?php
+return [
+    'middleware' => ['api'],
+    'guard' => ['api'],
+];
+```
+
+### Disable CSRF for the /graphql route 
+
+If you plan to use graphql from web browsers and if you want to explicitly allow access from external applications 
+(through CORS headers), you need to disable the CSRF token.
+
+Simply add `graphql` to `$except` in `app/Http/Middleware/VerifyCsrfToken.php`.
+
+### Configuring your GraphQL client
+
+If you are planning to use `graphql` only from your website domain, then the safest way is to keep CSRF enabled and
+configure your GraphQL JS client to pass the CSRF headers on any graphql request.
+
+The way you do this depends on the Javascript GraphQL client you are using.
+
+Assuming you are using [Apollo](https://www.apollographql.com/docs/link/links/http/), you need to be sure that Apollo passes the token
+back to Laravel on every request.
+
+**Sample Apollo client setup with CSRF support**
+```js
+import { ApolloClient, ApolloLink, InMemoryCache, HttpLink } from 'apollo-boost';
+
+const httpLink = new HttpLink({ uri: 'https://api.example.com/graphql' });
+
+const authLink = new ApolloLink((operation, forward) => {
+  // Retrieve the authorization token from local storage.
+  const token = localStorage.getItem('auth_token');
+  
+  // Get the XSRF-TOKEN that is set by Laravel on each request
+  var cookieValue = document.cookie.replace(/(?:(?:^|.*;\s*)XSRF-TOKEN\s*\=\s*([^;]*).*$)|^.*$/, "$1");
+
+  // Use the setContext method to set the X-CSRF-TOKEN header back.
+  operation.setContext({
+    headers: {
+      'X-CSRF-TOKEN': cookieValue
+    }
+  });
+
+  // Call the next link in the middleware chain.
+  return forward(operation);
+});
+
+const client = new ApolloClient({
+  link: authLink.concat(httpLink), // Chain it with the HttpLink
+  cache: new InMemoryCache()
+});
+```
+
+## Adding GraphQL DevTools
+
+GraphQLite does not include additional GraphQL tooling, such as the GraphiQL editor.
+To integrate a web UI to query your GraphQL endpoint with your Laravel installation, 
+we recommend installing [GraphQL Playground](https://github.com/mll-lab/laravel-graphql-playground)
+
+```console
+$ composer require mll-lab/laravel-graphql-playground
+```
+
+By default, the playground will be available at `/graphql-playground`.
+
+You can also use any external client with GraphQLite, make sure to point it to the URL defined in the config (`'/graphql'` by default).
+
+## Troubleshooting HTTP 419 errors
+
+If HTTP requests to GraphQL endpoint generate responses with the HTTP 419 status code, you have an issue with the configuration of your
+CSRF token. Please check again [the paragraph dedicated to CSRF configuration](#configuring-csrf-protection).

website/versioned_docs/version-4.0/migrating.md

@@ -0,0 +1,42 @@
+---
+id: version-4.0-migrating
+title: Migrating
+sidebar_label: Migrating
+original_id: migrating
+---
+
+## Migrating from v3.0 to v4.0
+
+If you are a "regular" GraphQLite user, migration to v4 should be straightforward:
+
+- Annotations are mostly untouched. The only annotation that is changed is the `@SourceField` annotation.
+    - Check your code for every places where you use the `@SourceField` annotation:
+    - The "id" attribute has been remove (`@SourceField(id=true)`). Instead, use `@SourceField(outputType="ID")`
+    - The "logged", "right" and "failWith" attributes have been removed (`@SourceField(logged=true)`).
+      Instead, use the annotations attribute with the same annotations you use for the `@Field` annotation: 
+      `@SourceField(annotations={@Logged, @FailWith(null)})`
+    - If you use magic property and were creating a getter for every magic property (to put a `@Field` annotation on it),
+      you can now replace this getter with a `@MagicField` annotation.
+- In GraphQLite v3, the default was to hide a field from the schema if a user has no access to it.
+  In GraphQLite v4, the default is to still show this field, but to throw an error if the user makes a query on it
+  (this way, the schema is the same for all users). If you want the old mode, use the new
+  [`@HideIfUnauthorized` annotation](annotations_reference.md#hideifunauthorized-annotation)
+- If you are using the Symfony bundle, the Laravel package or the Universal module, you must also upgrade those to 4.0.
+  These package will take care of the wiring for you. Apart for upgrading the packages, you have nothing to do.
+- If you are relying on the `SchemaFactory` to bootstrap GraphQLite, you have nothing to do.
+
+On the other hand, if you are a power user and if you are wiring GraphQLite services yourself (without using the 
+`SchemaFactory`) or if you implemented custom "TypeMappers", you will need to adapt your code:
+
+- The `FieldsBuilderFactory` is gone. Directly instantiate `FieldsBuilder` in v4.
+- The `CompositeTypeMapper` class has no more constructor arguments. Use the `addTypeMapper` method to register 
+  type mappers in it.
+- The `FieldsBuilder` now accept an extra argument: the `RootTypeMapper` that you need to instantiate accordingly. Take
+  a look at the `SchemaFactory` class for an example of proper configuration.
+- The `HydratorInterface` and all implementations are gone. When returning an input object from a TypeMapper, the object
+  must now implement the `ResolvableMutableInputInterface` (an input object type that contains its own resolver)
+
+Note: we strongly recommend to use the Symfony bundle, the Laravel package, the Universal module or the SchemaManager
+to bootstrap GraphQLite. Wiring directly GraphQLite classes (like the `FieldsBuilder`) into your container is not recommended,
+as the signature of the constructor of those classes may vary from one minor release to another.
+Use the `SchemaManager` instead.

website/versioned_docs/version-4.0/multiple_output_types.md

@@ -0,0 +1,127 @@
+---
+id: version-4.0-multiple_output_types
+title: Mapping multiple output types for the same class
+sidebar_label: Class with multiple output types
+original_id: multiple_output_types
+---
+<small>Available in GraphQLite 4.0+</small>
+
+In most cases, you have one PHP class and you want to map it to one GraphQL output type.
+
+But in very specific cases, you may want to use different GraphQL output type for the same class.
+For instance, depending on the context, you might want to prevent the user from accessing some fields of your object.
+
+To do so, you need to create 2 output types for the same PHP class. You typically do this using the "default" attribute of the `@Type` annotation.
+
+## Example
+
+Here is an example. Say we are manipulating products. When I query a `Product` details, I want to have access to all fields.
+But for some reason, I don't want to expose the price field of a product if I query the list of all products.  
+
+```php
+/**
+ * @Type()
+ */
+class Product
+{
+    // ...
+
+    /**
+     * @Field()
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * @Field()
+     */
+    public function getPrice(): ?float
+    {
+        return $this->price;
+    }
+}
+```
+
+The `Product` class is declaring a classic GraphQL output type named "Product".
+
+```php
+/**
+ * @Type(class=Product::class, name="LimitedProduct", default=false)
+ * @SourceField(name="name")
+ */
+class LimitedProductType
+{
+    // ...
+
+    /**
+     * @Field()
+     */
+    public function getName(Product $product): string
+    {
+        return $product->getName();
+    }
+}
+```
+
+
+The `LimitedProductType` also declares a ["external" type](external_type_declaration.md) mapping the `Product` class.
+But pay special attention to the `@Type` annotation.
+
+First of all, we specify `name="LimitedProduct"`. This is useful to avoid having colliding names with the "Product" GraphQL output type
+that is already declared.
+
+Then, we specify `default=false`. This means that by default, the `Product` class should not be mapped to the `LimitedProductType`.
+This type will only be used when we explicitly request it.
+
+Finally, we can write our requests:
+
+```php
+class ProductController
+{
+    /**
+     * This field will use the default type.
+     *
+     * @Field
+     */
+    public function getProduct(int $id): Product { /* ... */ } 
+    
+    /**
+     * Because we use the "outputType" attribute, this field will use the other type.
+     *
+     * @Field(outputType="[LimitedProduct!]!")
+     * @return Product[]
+     */
+    public function getProducts(): array { /* ... */ } 
+}
+``` 
+
+Notice how the "outputType" attribute is used in the `@Field` annotation to force the output type.
+
+Is a result, when the end user calls the `product` query, we will have the possibility to fetch the `name` and `price` fields,
+but if he calls the `products` query, each product in the list will have a `name` field but no `price` field. We managed
+to successfully expose a different set of fields based on the query context.
+
+## Extending a non-default type
+
+If you want to extend a type using the `@ExtendType` annotation and if this type is declared as non-default,
+you need to target the type by name instead of by class.
+
+So instead of writing:
+
+```php
+/**
+ * @ExtendType(class=Product::class)
+ */
+```
+
+you will write:
+
+```php
+/**
+ * @ExtendType(name="LimitedProduct")
+ */
+```
+
+Notice how we use the "name" attribute instead of the "class" attribute in the `@ExtendType` annotation.