docs: Update advanced user guide section

Author: matapatos

.gitignore

@@ -4,6 +4,7 @@ wp-content/
 *.cache
 /tests/coverage
 /coverage.xml
+docs/site/
 
 # Created by https://www.toptal.com/developers/gitignore/api/composer,sublimetext,linux
 # Edit at https://www.toptal.com/developers/gitignore?templates=composer,sublimetext,linux

…anced-user-guide/dependency-injection.md …user-guide/dependency-injection/index.mddocs/docs/advanced-user-guide/dependency-injection.md renamed to docs/docs/advanced-user-guide/dependency-injection/index.md docs/docs/advanced-user-guide/dependency-injection.md renamed to docs/docs/advanced-user-guide/dependency-injection/index.md

@@ -8,8 +8,9 @@ With dependency injection our endpoints do look much cleaner ✨🧹
 === "With dependency injection"
 
     ```php
+    <?php
     // We only need the ID. So we type $ID
-    $router->get('/posts/(?P<ID>[\d]+)', function ($ID) {
+    $router->get('/posts/(?P<ID>[\d]+)', function (int $ID) {
         return get_post($ID);
     });
 
@@ -23,6 +24,7 @@ With dependency injection our endpoints do look much cleaner ✨🧹
 === "No dependency injection"
 
     ```php
+    <?php
     // Unable to fetch a dynamic parameter. Have to work with the $request argument
     $router->get('/posts/(?P<ID>[\d]+)', function ($request) {
         return get_post($request->get('ID'));

docs/docs/advanced-user-guide/dependency-injection/injectables.md

@@ -0,0 +1,60 @@
+A common scenario while creating API's is the need to share resources or logic across multiple endpoints or handlers.
+This is where *injectables* can be useful.
+
+```php hl_lines="5 12"
+<?php
+use Attributes\Validation\Validatable;
+use Attributes\Wp\FastEndpoints\Options\Inject;
+
+$router->inject('user', function (): WP_User {
+    if (! is_user_logged_in()) {
+        return new WpError(401, "Ups! You need to login first");
+    }
+    return wp_get_current_user();
+});
+
+$router->get('/posts', function (#[Inject] WP_User $user) {
+    // Your logic
+}));
+
+$router->get('/user', function (#[Inject] WP_User $user) {
+    // Your logic
+});
+```
+
+#### Function names
+
+If an injectable is not found, FastEndpoints will try to look-up for a function with the same property name or specified
+injectable name.
+
+```php hl_lines="4"
+<?php
+function hello_world() { return "Hello world!"; }
+
+$router->get('/hello', function (#[Inject('hello_world')] string $hello) {
+    return $hello;
+}));
+```
+
+#### How it resolves injectables?
+
+Each injectable is only resolved once while handling a request. For instance, if the same injectable is used in both
+the permission callback and the endpoint, it will first be resolved during the permission callback and then re-use the
+cached value for subsequent calls.
+
+```php hl_lines="9 12"
+<?php
+$router->inject('nextNumber', function (): int {
+    global $nextNumber;
+    $randomNumber = ($randomNumber ?: 0) + 1;
+    return $randomNumber;
+});
+
+$router->get('/posts', function (#[Inject] int $nextNumber) {
+    // $nextNumber will be 1
+}))
+->permission(function(#[Inject] int $nextNumber) {
+    // $nextNumber will be 1
+    return true;
+});
+```

docs/docs/advanced-user-guide/dependency-injection/request-payload.md

@@ -0,0 +1,168 @@
+As you might be already familiar WP-FastEndpoints allows you to fetch request data via function arguments, and optionally
+you can validate that data via type-hinting.
+
+### Built-in type-hints
+
+By default, when you rely on built-in PHP types, DateTime, DateTimeInterface or when no type-hint is used,
+WP-FastEndpoints will look for the data in the url or in the query parameters, in this order. However, if desired this
+behaviour can be changed via *#[Attributes]*.
+
+=== "Looks-up for URL or query parameter"
+
+    ```php
+    <?php
+    $router->get('/posts', function (int $ID) {
+        // Your logic
+    });
+    ```
+
+=== "Looks-up for a header"
+
+    ```php hl_lines="4"
+    <?php
+    use Attributes\Wp\FastEndpoints\Options\Header;
+
+    $router->get('/user', function (#[Header('Authorization')] string $token) {
+        // Your logic
+    });
+    ```
+
+The following is a list of all those type-hints:
+
+- bool
+- int
+- float
+- string
+- callable
+- array
+- object
+- [*DateTime*](https://www.php.net/manual/en/class.datetime.php)
+- [*DateTimeInterface*](https://www.php.net/manual/en/class.datetimeinterface.php)
+
+### Custom classes
+
+For more complex types of data structures we can rely on custom classes. If you know how to write a class you know how
+to validate a request in WP-FastEndpoints.
+
+By default, when you rely on type-hints from custom classes WP-FastEndpoints will look for the data either in the
+JSON or body of the current request. However, as with built-in type-hints, this behaviour can be changed via *#[Attributes]*.
+
+```php
+<?php
+class HelloWorld {
+    public string $name;
+}
+```
+
+=== "Looks-up for JSON or body parameters"
+
+    ```php
+    <?php
+    $router->post('/hello', function (HelloWorld $hello) {
+        // Your logic
+    });
+    ```
+
+=== "Looks-up for URL or query parameters"
+
+    ```php hl_lines="5"
+    <?php
+    use Attributes\Wp\FastEndpoints\Options\Url;    
+    use Attributes\Wp\FastEndpoints\Options\Query;
+
+    $router->post('/hello', function (#[Url, Query] HelloWorld $hello) {
+        // Your logic
+    });
+    ```
+
+#### How to type-hint arrays?
+
+Unfortunately, PHP doesn't provide a way to properly type-hint array's. Dictionaries aren't an issue because custom classes
+can be used, but for sequenced arrays is a bit more tricky.
+
+To solve this issue, WP-FastEndpoints assumes that any [*ArrayObject*](https://www.php.net/manual/en/class.arrayobject.php)
+child class should be considered a *typed-hint* array. However, to actually type-hint that array a property name `$type`
+with a type-hint needs to be specified in the class. Otherwise, an array of `mixed` is assumed.
+
+```php hl_lines="3"
+<?php
+class HelloArr extends ArrayObject {
+    public Hello $type;
+}
+
+$router->get('/say-hello', function (HelloArr $allHellos) {
+    foreach ($allHellos as $hello) {
+        echo "Hello $hello->name!";   
+    }
+});
+```
+
+!!! tip
+    [attributes-php/validation](https://packagist.org/packages/Attributes-PHP/validation) provides some typed-arrays,
+    like: 1) [*BoolArr*](https://github.com/Attributes-PHP/validation/blob/main/src/Types/BoolArr.php),
+    2) [*IntArr*](https://github.com/Attributes-PHP/validation/blob/main/src/Types/IntArr.php),
+    3) [*StrArr*](https://github.com/Attributes-PHP/validation/blob/main/src/Types/StrArr.php) and
+    [others](https://github.com/Attributes-PHP/validation/tree/main/src/Types).
+
+### Special classes
+
+When an argument has a type-hint it usually means that the request payload should follow that class structure. However,
+there are three special classes which don't follow this pattern:
+
+- [*WP_REST_Request*](https://developer.wordpress.org/reference/classes/wp_rest_request/) - Can be used to retrieve the
+  current request
+- [*WP_REST_Response*](https://developer.wordpress.org/reference/classes/wp_rest_response/) - Can be used to retrieve
+  the response to be sent to the client, in case of a success. You could change the response HTTP status code or the data 
+  which is sent to the client (wouldn't recommend the last one though).
+- [*Endpoint*](https://github.com/Attributes-PHP/wp-fastendpoints/blob/main/src/Endpoint.php#L44) - The current endpoint
+  instance. You shouldn't ever need this one.
+
+=== "Get current request"
+
+    ```php
+    <?php
+    $router->get('/request', function (WP_REST_Request $request) {
+        return $request->get_params();
+    });
+    ```
+
+=== "Change HTTP status code of a response"
+
+    ```php
+    <?php
+    $router->get('/response/204', function (WP_REST_Response $response) {
+        $response->set_status(204);
+    });
+    ```
+
+### Required vs optional properties
+
+Until now, we have seen most how to specify required properties from a request payload. In case your property is optional
+you can rely on default values for that, like the following.
+
+=== "Required property"
+
+    ```php hl_lines="2"
+    <?php
+    $router->get('/required', function (int $id) {
+        return $id;
+    });
+    ```
+
+=== "Optional property"
+
+    ```php hl_lines="2"
+    <?php
+    $router->get('/optional', function (int $id = 0) {
+        return $id;
+    });
+    ```
+
+=== "Optional payload"
+
+    ```php hl_lines="2"
+    <?php
+    $router->get('/payload/optional', function (?HelloWorld $hello = null) {
+        return $hello ? $hello->name : "No payload";
+    });
+    ```

docs/docs/advanced-user-guide/index.md

@@ -1,6 +1,4 @@
-The [Quick Start](/wp-fastendpoints/quick-start/) should be able to get you a feel of
-the main features of WP-FastEndpoints.
+The [Quick Start](/wp-fastendpoints/quick-start/) should be able to get you a feel of the main features of WP-FastEndpoints.
 
-However, it's possible that the solution for your use case might not be in the Quick Start
-tutorial. In the next sections we will take a look at further functionalities that
-WP-FastEndpoints provides.
+However, it's possible what you are looking for might not be available in the Quick Start guide.
+In the next sections we will take a look at further functionalities that WP-FastEndpoints provides.

docs/docs/advanced-user-guide/middlewares.md

@@ -43,5 +43,5 @@ $router->get('/test', function () {
 ## Responses
 
 If you need you can also take advantage of either WP_Error and WP_REST_Response to send
-a direct response to the client. See [Responses page](/wp-fastendpoints/advanced-user-guide/responses)
+a direct response to the client. See [Responses page](/advanced-user-guide/responses)
 for more info

docs/docs/advanced-user-guide/request-life-cycle.md

@@ -1,29 +1,29 @@
 In WP-FastEndpoints an endpoint can have multiple optional handlers attached to:
 
 1. Permission handlers via `hasCap(...)` or `permission(...)` - Used to check for user permissions
-2. Middlewares
-       1. Request Payload Schema Middleware via `schema(...)` - Validates the request payload
-       2. Response Schema Middleware via `returns(...)` - Makes sure that the proper response is sent to the client
-       3. Custom middlewares via `middleware(...)` - Any other custom logic that you might want to run
+2. Middlewares via `middleware(...)`
+       1. Running before the handler being called and/or
+       2. Running after the handler being called
 
 ## Permission handlers
 
 When a request is received the first handlers to run are the permissions handlers. Permission handlers are called
-by WordPress via [`permission_callback`](https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/#callbacks).
+by WordPress via [*`permission_callback`*](https://developer.wordpress.org/rest-api/extending-the-rest-api/routes-and-endpoints/#callbacks).
 
 In contrast to WordPress, you can have one or multiple permission handlers attached to the same endpoint.
 
 ???+ note
-    In the background all permission handlers are wrapped into one callable which is later on used as
+    In the background all permission handlers are wrapped into one callable which is later on used as the
     `permission_callback` by the endpoint
 
 These handlers will then be called in the same order as they were attached. For instance:
 
 ```php
+<?php
 $router->get('/test', function () {return true;})
-->hasCap('read')                # Called first
-->hasCap('edit_posts')          # Called second if the first one was successful
-->permission('__return_true')   # Called last if both the first and second were successful
+    ->hasCap('read')              # Called first
+    ->hasCap('edit_posts')        # Called second if the first one was successful
+    ->permission('__return_true') # Called last if both the first and second were successful
 ```
 
 ## Middlewares
@@ -32,7 +32,7 @@ If all the permission handlers are successful the next set of handlers that run
 implement the `onRequest` function.
 
 Remember that a middleware can implement `onRequest` and/or `onResponse` functions. The first one, runs before
-the main endpoint handler and the later one should run after the main endpoint handler.
+the main endpoint handler and the later one runs after the main endpoint handler.
 
 !!! warning
     Please bear in mind that if either a [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) or
@@ -45,6 +45,7 @@ the main endpoint handler and the later one should run after the main endpoint h
 Same as with the permission handlers, middlewares are called with the same order that they were attached.
 
 ```php
+<?php
 class OnRequestMiddleware extends \Attributes\Wp\FastEndpoints\Contracts\Middleware
 {
     public function onRequest(/* Type what you need */){
@@ -53,23 +54,26 @@ class OnRequestMiddleware extends \Attributes\Wp\FastEndpoints\Contracts\Middlew
 }
 
 $router->post('/test', function () {return true;})
-->middleware(OnRequestMiddleware()) # Called first
-->schema('Basics/Bool');            # Called second
+    ->middleware(OnRequestMiddleware())    # Called first
+    ->middleware(DoSomethingMiddleware()); # Called second
 ```
 
 ### onResponse
 
-Likewise, middlewares implementing onResponse functions will be triggered in the same order as they were attached.
+Likewise, middlewares implementing `onResponse` functions will be triggered in the same order as they were attached.
 
 ```php
+<?php
+use Attributes\Validation\Types\IntArr;
+
 class OnResponseMiddleware extends \Attributes\Wp\FastEndpoints\Contracts\Middleware
 {
     public function onResponse(/* Type what you need */){
         return;
     }
 }
 
-$router->post('/test', function () {return true;})
-->returns('Basics/Bool')                # Called first
-->middleware(OnResponseMiddleware());   # Called second
+$router->post('/test', function () {return [1,2,3];})
+    ->returns(IntArr::class)              # Called first
+    ->middleware(OnResponseMiddleware()); # Called second
 ```