Adding PHP 8 attribute samples to the documentation

Author: moufmouf

docs/CHANGELOG.md

@@ -4,6 +4,13 @@ title: Changelog
 sidebar_label: Changelog
 ---
 
+## 4.1
+
+New features:
+
+- All annotations can now be accessed as PHP 8 attributes
+
+
 ## 4.0
 
 This is a complete refactoring from 3.x. While existing annotations are kept compatible, the internals have completely

docs/annotations_reference.md

@@ -4,6 +4,9 @@ title: Annotations reference
 sidebar_label: Annotations reference
 ---
 
+Note: all annotations are available both in a Doctrine annotation format (`@Query`) and in PHP 8 attribute format (`#[Query]`).
+See [Doctrine annotations vs PHP 8 attributes](doctrine_annotations_attributes.md) for more details.
+
 ## @Query annotation
 
 The `@Query` annotation is used to declare a GraphQL query.
@@ -74,7 +77,7 @@ Attribute      | Compulsory | Type | Definition
 name           | *yes*       | string | The name of the field.
 [outputType](custom_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.
+annotations    | *no*       | array<Annotations>  | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here. Available in Doctrine annotations only (not available in the #SourceField PHP 8 attribute)
 
 **Note**: `outputType` and `phpType` are mutually exclusive.
 
@@ -89,7 +92,7 @@ Attribute      | Compulsory | Type | Definition
 name           | *yes*       | string | The name of the field.
 [outputType](custom_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.
+annotations    | *no*       | array<Annotations>  | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here. Available in Doctrine annotations only (not available in the #MagicField PHP 8 attribute)
 
 (*) **Note**: `outputType` and `phpType` are mutually exclusive. You MUST provide one of them.
 

docs/argument_resolving.md

@@ -15,9 +15,9 @@ 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[]
    */
+  #[Query]
   public function products(ResolveInfo $info): array  
   ```
   In the query above, the `$info` argument is filled with the Webonyx `ResolveInfo` class thanks to the 
@@ -58,14 +58,19 @@ If you plan to use annotations while resolving arguments, your annotation should
 
 For instance, if we want GraphQLite to inject a service in an argument, we can use `@Autowire(for="myService")`.
 
+For PHP 8 attributes, we only need to put declare the annotation can target parameters: `#[Attribute(Attribute::TARGET_PARAMETER)]`.
+
 The annotation looks like this:
 
 ```php
+use Attribute;
+
 /**
  * Use this annotation to autowire a service from the container into a given parameter of a field/query/mutation.
  *
  * @Annotation
  */
+#[Attribute(Attribute::TARGET_PARAMETER)]
 class Autowire implements ParameterAnnotationInterface
 {
     /**

docs/authentication_authorization.md

@@ -22,7 +22,30 @@ See <a href="implementing-security.md">Connecting GraphQLite to your framework's
 ## `@Logged` and `@Right` annotations
 
 GraphQLite exposes two annotations (`@Logged` and `@Right`) that you can use to restrict access to a resource.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```php
+namespace App\Controller;
 
+use TheCodingMachine\GraphQLite\Annotations\Query;
+use TheCodingMachine\GraphQLite\Annotations\Logged;
+use TheCodingMachine\GraphQLite\Annotations\Right;
+
+class UserController
+{
+    /**
+     * @return User[]
+     */
+    #[Query]
+    #[Logged]
+    #[Right("CAN_VIEW_USER_LIST")]
+    public function users(int $limit, int $offset): array
+    {
+        // ...
+    }
+}
+```
+<!--PHP 7+-->
 ```php
 namespace App\Controller;
 
@@ -44,6 +67,8 @@ class UserController
     }
 }
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
 
 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.
@@ -62,6 +87,28 @@ If you do not want an error to be thrown when a user attempts to query a field/q
 
 The `@FailWith` annotation contains the value that will be returned for users with insufficient rights.
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```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".
+     *
+     * @return User[]
+     */
+    #[Query]
+    #[Logged]
+    #[Right("CAN_VIEW_USER_LIST")]
+    #[FailWith(null)]
+    public function users(int $limit, int $offset): array
+    {
+        // ...
+    }
+}
+```
+<!--PHP 7+-->
 ```php
 class UserController
 {
@@ -81,11 +128,37 @@ class UserController
     }
 }
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Injecting the current user as a parameter
 
 Use the `@InjectUser` annotation to get an instance of the current user logged in.
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```php
+namespace App\Controller;
+
+use TheCodingMachine\GraphQLite\Annotations\Query;
+use TheCodingMachine\GraphQLite\Annotations\InjectUser;
+
+class ProductController
+{
+    /**
+     * @Query
+     * @return Product
+     */
+    public function product(
+            int $id,
+            #[InjectUser] 
+            User $user
+        ): Product
+    {
+        // ...
+    }
+}
+```
+<!--PHP 7+-->
 ```php
 namespace App\Controller;
 
@@ -105,6 +178,7 @@ class ProductController
     }
 }
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 The `@InjectUser` annotation can be used next to:
 
@@ -123,6 +197,29 @@ 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.
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```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.
+     *
+     * @return User[]
+     */
+    #[Query]
+    #[Logged]
+    #[Right("CAN_VIEW_USER_LIST")]
+    #[HideIfUnauthorized]
+    public function users(int $limit, int $offset): array
+    {
+        // ...
+    }
+}
+```
+<!--PHP 7+-->
 ```php
 class UserController
 {
@@ -143,6 +240,7 @@ class UserController
     }
 }
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 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).

docs/autowiring.md

@@ -17,6 +17,33 @@ the service instance.
 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).
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```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]
+    public function getName(
+            #[Autowire]
+            TranslatorInterface $translator
+        ): string
+    {
+        return $translator->trans('product_name_'.$this->id);
+    }
+}
+```
+<!--PHP 7+-->
 ```php
 namespace App\Entities;
 
@@ -43,6 +70,7 @@ class Product
     }
 }
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 When GraphQLite queries the name, it will automatically fetch the translator service.
 
@@ -59,10 +87,8 @@ with a particular service implementation. This makes your code tightly coupled a
 <div class="alert alert-error">
 Please don't do that:
 
-<pre><code>    /**
-     * @Field()
-     */
-    public function getName(MyTranslator $translator): string
+<pre><code>    #[Field]
+    public function getName(#[Autowire] MyTranslator $translator): string
     {
         // Your domain is suddenly tightly coupled to the MyTranslator class.
     }
@@ -74,10 +100,8 @@ 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
+<pre><code>    #[Field]
+    public function getName(#[Autowire] TranslatorInterface $translator): string
     {
         // Good. You can switch translator implementation any time.
     }
@@ -90,11 +114,18 @@ By type-hinting against an interface, your code remains testable and is decouple
 
 Optionally, you can specify the identifier of the service you want to fetch from the controller:
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```php
+#[Autowire(identifier: "translator")]
+```
+<!--PHP 7+-->
 ```php
 /**
  * @Autowire(for="$translator", identifier="translator")
  */
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 <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

docs/custom_types.md

@@ -8,21 +8,36 @@ In some special cases, you want to override the GraphQL return type that is attr
 
 For instance:
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```php
+#[Type(class: Product::class)]
+class ProductType
+{
+    #[Field]
+    public function getId(Product $source): string
+    {
+        return $source->getId();
+    }
+}
+```
+<!--PHP 7+-->
 ```php
 /**
  * @Type(class=Product::class)
  */
 class ProductType
 {
     /**
-     * @Field(name="id")
+     * @Field
      */
     public function getId(Product $source): string
     {
         return $source->getId();
     }
 }
 ```
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 In the example above, GraphQLite will generate a GraphQL schema with a field `id` of type `string`:
 
@@ -37,11 +52,18 @@ is an `ID` or not.
 
 You can help GraphQLite by manually specifying the output type to use:
 
+<!--DOCUSAURUS_CODE_TABS-->
+<!--PHP 8+-->
+```php
+    #[Field(outputType: "ID")]
+``` 
+<!--PHP 7+-->
 ```php
     /**
      * @Field(name="id", outputType="ID")
      */
 ``` 
+<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Usage