updated Book tutorial

Signed-off-by: bidi <[email protected]>

Author: bidi47

docs/book/v7/tutorials/api-evolution.md

@@ -4,20 +4,20 @@ API evolution: Updating an API while keeping it compatible for existing consumer
 
 ## How it works
 
-In Dotkernel API we can mark an entire endpoint or a single method as deprecated using attributes on handlers.
+In Dotkernel API we can mark an endpoint as deprecated using attributes on handlers.
 We use response headers to inform the consumers about the future changes by using two new headers:
 
 - `Link` - it's a link to the official documentation pointing out the changes that will take place.
 - `Sunset` - this header is a date, indicating when the deprecated resource will potentially become unresponsive.
 
-**Both headers are independent, you can use them separately.**
+**The above headers are independent, so you can use them separately.**
 
-> Make sure you have the `DeprecationMiddleware:class` piped in your `pipeline` list.
+> Make sure you have the `DeprecationMiddleware:class` added to your `pipeline` list.
 > In our case it's `config/pipeline.php`.
 
-## Marking an entire endpoint as deprecated
+## Marking an endpoint as deprecated
 
-When you want to mark an entire resource as deprecated, you have to use the `ResourceDeprecation` attribute.
+When you want to mark a resource as deprecated, you have to use the `ResourceDeprecation` attribute.
 
 ```php
 ...
@@ -33,7 +33,7 @@ class HomeHandler implements RequestHandlerInterface
 }
 ```
 
-In the example above, the `ResourceDeprecation` attribute is attached to the class, marking the entire `/` (home) endpoint as deprecated starting from `2038-01-01`.
+In the example above, the `ResourceDeprecation` attribute is attached to the class, marking the `/` (home) endpoint as deprecated starting from `2038-01-01`.
 
 Running the following curl will print out the response headers where we can see the **Sunset** and **Link** headers.
 
@@ -62,4 +62,4 @@ Vary: Origin
 
 > Deprecations can only be attached to handler classes that implement `RequestHandlerInterface`.
 
-> The `rel` and `type` arguments are optional, they default to `sunset` and `text/html` if no value was provided and are `Link` related parts.
+> The `rel` and `type` arguments are optional, they default to `sunset` and `text/html` if no value is provided and are `Link` related parts.

docs/book/v7/tutorials/create-book-module-via-dot-maker.md

@@ -175,13 +175,25 @@ class Book extends AbstractEntity
         return $this;
     }
 
+    /**
+     * @return array{
+     *     id: non-empty-string,
+     *     name: non-empty-string,
+     *     author: non-empty-string,
+     *     releaseDate: DateTimeImmutable|null,
+     *     created: DateTimeImmutable|null,
+     *     updated: DateTimeImmutable|null,
+     * }
+     */
     public function getArrayCopy(): array
     {
         return [
             'id'          => $this->id->toString(),
             'name'        => $this->getName(),
             'author'      => $this->getAuthor(),
             'releaseDate' => $this->getReleaseDate(),
+            'created'     => $this->created,
+            'updated'     => $this->updated,
         ];
     }
 }
@@ -306,6 +318,14 @@ use Api\Book\InputFilter\Input\NameInput;
 use Api\Book\InputFilter\Input\ReleaseDateInput;
 use Core\App\InputFilter\AbstractInputFilter;
 
+/**
+ * @phpstan-type CreateBookDataType array{
+ *     name: non-empty-string,
+ *     author: non-empty-string,
+ *     name: DateTimeImmutable|null,
+ * }
+ * @extends AbstractInputFilter<CreateBookDataType>
+ */
 class CreateBookInputFilter extends AbstractInputFilter
 {
     public function __construct()

docs/book/v7/tutorials/create-book-module.md

@@ -151,13 +151,25 @@ class Book extends AbstractEntity
         return $this;
     }
 
+    /**
+     * @return array{
+     *     id: non-empty-string,
+     *     name: non-empty-string,
+     *     author: non-empty-string,
+     *     releaseDate: DateTimeImmutable|null,
+     *     created: DateTimeImmutable|null,
+     *     updated: DateTimeImmutable|null,
+     * }
+     */
     public function getArrayCopy(): array
     {
         return [
             'id'          => $this->id->toString(),
             'name'        => $this->getName(),
             'author'      => $this->getAuthor(),
             'releaseDate' => $this->getReleaseDate(),
+            'created'     => $this->created,
+            'updated'     => $this->updated,
         ];
     }
 }
@@ -181,6 +193,10 @@ use Dot\DependencyInjection\Attribute\Entity;
 #[Entity(name: Book::class)]
 class BookRepository extends AbstractRepository
 {
+    /**
+     * @param array<non-empty-string, mixed> $params
+     * @param array<non-empty-string, mixed> $filters
+     */
     public function getBooks(array $params, array $filters = []): QueryBuilder
     {
         return $this
@@ -214,6 +230,9 @@ interface BookServiceInterface
 
     public function saveBook(array $data): Book;
 
+    /**
+     * @param array<non-empty-string, mixed> $params
+     */
     public function getBooks(array $params = []): QueryBuilder;
 }
 
@@ -253,6 +272,7 @@ class BookService implements BookServiceInterface
 
     /**
      * @throws Exception
+     * @param array<non-empty-string, mixed> $data
      */
     public function saveBook(array $data): Book
     {
@@ -267,6 +287,9 @@ class BookService implements BookServiceInterface
         return $book;
     }
 
+    /**
+     * @param array<non-empty-string, mixed> $params
+     */
     public function getBooks(array $params = []): QueryBuilder
     {
         $filters = $params['filters'] ?? [];
@@ -289,7 +312,7 @@ class BookService implements BookServiceInterface
 
 ```
 
-When creating or updating a book, we will need some validators, so we will create input filters that will be used to validate the data received in the request
+When creating or updating a book, we will need some validators, so we will create input filters that will be used to validate the data received in the request.
 
 * `src/Book/src/InputFilter/Input/AuthorInput.php`
 
@@ -415,6 +438,14 @@ use Api\Book\InputFilter\Input\NameInput;
 use Api\Book\InputFilter\Input\ReleaseDateInput;
 use Core\App\InputFilter\AbstractInputFilter;
 
+/**
+ * @phpstan-type CreateBookDataType array{
+ *     name: non-empty-string,
+ *     author: non-empty-string,
+ *     name: DateTimeImmutable|null,
+ * }
+ * @extends AbstractInputFilter<CreateBookDataType>
+ */
 class CreateBookInputFilter extends AbstractInputFilter
 {
     public function __construct()
@@ -619,6 +650,14 @@ use Dot\DependencyInjection\Factory\AttributedServiceFactory;
 use Mezzio\Application;
 use Mezzio\Hal\Metadata\MetadataMap;
 
+/**
+ * @phpstan-import-type MetadataType from AppConfigProvider
+ * @phpstan-type DependenciesType array{
+ *      delegators: array<class-string, array<class-string>>,
+ *      factories: array<class-string, class-string>,
+ *      aliases: array<class-string, class-string>,
+ * }
+ */
 class ConfigProvider
 {
     public function __invoke(): array
@@ -650,6 +689,9 @@ class ConfigProvider
         ];
     }
 
+    /**
+     * @return MetadataType[]
+     */
     private function getHalConfig(): array
     {
         return [
@@ -718,13 +760,31 @@ use Core\Book\Repository\BookRepository;
 use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 use Dot\DependencyInjection\Factory\AttributedRepositoryFactory;
 
+/**
+ * @phpstan-type ConfigType array{
+ *      dependencies: DependenciesType,
+ *      doctrine: DoctrineConfigType,
+ *      resultCacheLifetime: int,
+ * }
+ * @phpstan-type DoctrineConfigType array{
+ *      driver: array{
+ *          orm_default: array{
+ *              class: class-string<MappingDriver>,
+ *          },
+ *      },
+ * }
+ * @phpstan-type DependenciesType array{
+ *       factories: array<class-string|non-empty-string, class-string|non-empty-string>,
+ * }
+ */
 class ConfigProvider
 {
     public function __invoke(): array
     {
         return [
-            'dependencies' => $this->getDependencies(),
-            'doctrine'     => $this->getDoctrineConfig(),
+            'dependencies'        => $this->getDependencies(),
+            'doctrine'            => $this->getDoctrineConfig(),
+            'resultCacheLifetime' => 600,
         ];
     }
 
@@ -777,7 +837,7 @@ Open `config/autoload/authorization.global.php` and append the below route names
 * `book::view-book`
 * `book::create-book`
 
-> Make sure you read and understand the rbac [documentation](https://docs.dotkernel.org/dot-rbac-guard/v4/configuration/).
+> Make sure you read and understand the [rbac documentation](https://docs.dotkernel.org/dot-rbac-guard/v4/configuration/).
 
 ## Migrations