diff --git a/docs/book/v6/tutorials/create-book-module-via-dot-maker.md b/docs/book/v6/tutorials/create-book-module-via-dot-maker.md index b097d2f..d6b3786 100644 --- a/docs/book/v6/tutorials/create-book-module-via-dot-maker.md +++ b/docs/book/v6/tutorials/create-book-module-via-dot-maker.md @@ -180,7 +180,7 @@ class Book extends AbstractEntity public function getArrayCopy(): array { return [ - 'uuid' => $this->getUuid()->toString(), + 'uuid' => $this->uuid->toString(), 'name' => $this->getName(), 'author' => $this->getAuthor(), 'releaseDate' => $this->getReleaseDate(), diff --git a/docs/book/v6/tutorials/create-book-module.md b/docs/book/v6/tutorials/create-book-module.md index 3042463..8bd4670 100644 --- a/docs/book/v6/tutorials/create-book-module.md +++ b/docs/book/v6/tutorials/create-book-module.md @@ -154,7 +154,7 @@ class Book extends AbstractEntity public function getArrayCopy(): array { return [ - 'uuid' => $this->getUuid()->toString(), + 'uuid' => $this->uuid->toString(), 'name' => $this->getName(), 'author' => $this->getAuthor(), 'releaseDate' => $this->getReleaseDate(), diff --git a/docs/book/v7/commands/display-available-endpoints.md b/docs/book/v7/commands/display-available-endpoints.md index 3c08725..2c58b88 100644 --- a/docs/book/v7/commands/display-available-endpoints.md +++ b/docs/book/v7/commands/display-available-endpoints.md @@ -21,10 +21,10 @@ The output should be similar to the following: | GET | admin::view-account | /admin/account | | PATCH | admin::update-account | /admin/account | | GET | admin::list-role | /admin/role | -| GET | admin::view-role | /admin/role/{uuid} | -| DELETE | admin::delete-admin | /admin/{uuid} | -| GET | admin::view-admin | /admin/{uuid} | -| PATCH | admin::update-admin | /admin/{uuid} | +| GET | admin::view-role | /admin/role/{id} | +| DELETE | admin::delete-admin | /admin/{id} | +| GET | admin::view-admin | /admin/{id} | +| PATCH | admin::update-admin | /admin/{id} | | POST | app::create-error-report | /error-report | | POST | security::token | /security/token | | GET | user::list-user | /user | @@ -43,15 +43,15 @@ The output should be similar to the following: | GET | user::check-account-reset-password | /user/account/reset-password/{hash} | | PATCH | user::update-account-reset-password | /user/account/reset-password/{hash} | | GET | user::list-role | /user/role | -| GET | user::view-role | /user/role/{uuid} | -| DELETE | user::delete-user | /user/{uuid} | -| GET | user::view-user | /user/{uuid} | -| PATCH | user::update-user | /user/{uuid} | -| PATCH | user::activate-user | /user/{uuid}/activate | -| DELETE | user::delete-user-avatar | /user/{uuid}/avatar | -| GET | user::view-user-avatar | /user/{uuid}/avatar | -| POST | user::create-user-avatar | /user/{uuid}/avatar | -| PATCH | user::deactivate-user | /user/{uuid}/deactivate | +| GET | user::view-role | /user/role/{id} | +| DELETE | user::delete-user | /user/{id} | +| GET | user::view-user | /user/{id} | +| PATCH | user::update-user | /user/{id} | +| PATCH | user::activate-user | /user/{id}/activate | +| DELETE | user::delete-user-avatar | /user/{id}/avatar | +| GET | user::view-user-avatar | /user/{id}/avatar | +| POST | user::create-user-avatar | /user/{id}/avatar | +| PATCH | user::deactivate-user | /user/{id}/deactivate | +------+----------------+-------------------------------------+-------------------------------------+ ``` diff --git a/docs/book/v7/extended-features/route-grouping.md b/docs/book/v7/extended-features/route-grouping.md index 68a7404..48eba07 100644 --- a/docs/book/v7/extended-features/route-grouping.md +++ b/docs/book/v7/extended-features/route-grouping.md @@ -15,7 +15,7 @@ Along with the features from `mezzio/mezzio-fastroute`, the new `dot-router` pac Here we have an example from `src/User/src/RoutesDelegator.php` with the new grouping method: ```php -$routeCollector->group('/user/' . $uuid) +$routeCollector->group('/user/' . $id) ->delete('', DeleteUserResourceHandler::class, 'user::delete-user') ->get('', GetUserResourceHandler::class, 'user::view-user') ->patch('', PatchUserResourceHandler::class, 'user::update-user'); diff --git a/docs/book/v7/openapi/initialized-components.md b/docs/book/v7/openapi/initialized-components.md index 638aa66..2b4fde9 100644 --- a/docs/book/v7/openapi/initialized-components.md +++ b/docs/book/v7/openapi/initialized-components.md @@ -103,7 +103,7 @@ use OpenApi\Attributes as OA; #[OA\Schema( schema: 'UserRole', properties: [ - new OA\Property(property: 'uuid', type: 'string', example: '1234abcd-abcd-4321-12ab-123456abcdef'), + new OA\Property(property: 'id', type: 'string', example: '1234abcd-abcd-4321-12ab-123456abcdef'), new OA\Property(property: 'name', type: 'string', example: UserRole::ROLE_USER), new OA\Property( property: '_links', @@ -132,7 +132,7 @@ Then, when generating the documentation file, `OpenAPI` will transform it into t ```yaml UserRole: properties: - uuid: + id: type: string example: 1234abcd-abcd-4321-12ab-123456abcdef name: diff --git a/docs/book/v7/openapi/write-documentation.md b/docs/book/v7/openapi/write-documentation.md index 386631b..b9e490e 100644 --- a/docs/book/v7/openapi/write-documentation.md +++ b/docs/book/v7/openapi/write-documentation.md @@ -30,7 +30,7 @@ If you need help, take a look at the existing definitions found in Dotkernel API Defines a `DELETE` HTTP request. It should specify at least the following parameters: -- `path`: the route to the resource (example: `/resource/{uuid}` - where `uuid` is a path parameter defined below) +- `path`: the route to the resource (example: `/resource/{id}` - where `id` is a path parameter defined below) - `description`: verbose description of the endpoint's purpose - `summary`: short description of the endpoint's purpose - `security`: an array of security scheme(s) to be used—omit if the endpoint is not protected @@ -42,7 +42,7 @@ Defines a `DELETE` HTTP request. It should specify at least the following parame Defines a `GET` HTTP request. It should specify at least the following parameters: -- `path`: the route to a single or collection of resources (example: `/resource/{uuid}` for a single resource or `/resource` for a collection of resources) +- `path`: the route to a single or collection of resources (example: `/resource/{id}` for a single resource or `/resource` for a collection of resources) - `description`: verbose description of the endpoint's purpose - `summary`: short description of the endpoint's purpose - `security`: an array of security scheme(s) to be used—omit if the endpoint is not protected @@ -54,7 +54,7 @@ Defines a `GET` HTTP request. It should specify at least the following parameter Defines a `PATCH` HTTP request. It should specify at least the following parameters: -- `path`: the route to the resource (example: `/resource/{uuid}` - where `uuid` is a path parameter defined below) +- `path`: the route to the resource (example: `/resource/{id}` - where `id` is a path parameter defined below) - `description`: verbose description of the endpoint's purpose - `summary`: short description of the endpoint's purpose - `security`: an array of security scheme(s) to be used—omit if the endpoint is not protected @@ -67,7 +67,7 @@ Defines a `PATCH` HTTP request. It should specify at least the following paramet Defines a `POST` HTTP request. It should specify at least the following parameters: -- `path`: the route to the resource (example: `/resource/{uuid}` - where `uuid` is a path parameter defined below) +- `path`: the route to the resource (example: `/resource/{id}` - where `id` is a path parameter defined below) - `description`: verbose description of the endpoint's purpose - `summary`: short description of the endpoint's purpose - `security`: an array of security scheme(s) to be used—omit if the endpoint is not protected @@ -80,7 +80,7 @@ Defines a `POST` HTTP request. It should specify at least the following paramete Defines a `PUT` HTTP request. It should specify at least the following parameters: -- `path`: the route to the resource (example: `/resource/{uuid}` - where `uuid` is a path parameter defined below) +- `path`: the route to the resource (example: `/resource/{id}` - where `id` is a path parameter defined below) - `description`: verbose description of the endpoint's purpose - `summary`: short description of the endpoint's purpose - `security`: an array of security scheme(s) to be used—omit if the endpoint is not protected diff --git a/docs/book/v7/tutorials/api-evolution.md b/docs/book/v7/tutorials/api-evolution.md index f8114ce..556dd92 100644 --- a/docs/book/v7/tutorials/api-evolution.md +++ b/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. diff --git a/docs/book/v7/tutorials/create-book-module-via-dot-maker.md b/docs/book/v7/tutorials/create-book-module-via-dot-maker.md index 0ae7129..5dfbc2a 100644 --- a/docs/book/v7/tutorials/create-book-module-via-dot-maker.md +++ b/docs/book/v7/tutorials/create-book-module-via-dot-maker.md @@ -110,6 +110,7 @@ namespace Core\Book\Entity; use Core\App\Entity\AbstractEntity; use Core\App\Entity\TimestampsTrait; +use Core\App\Entity\UuidIdentifierTrait; use Core\Book\Repository\BookRepository; use DateTimeImmutable; use Doctrine\ORM\Mapping as ORM; @@ -120,6 +121,7 @@ use Doctrine\ORM\Mapping as ORM; class Book extends AbstractEntity { use TimestampsTrait; + use UuidIdentifierTrait; #[ORM\Column(name: "name", type: "string", length: 100)] protected string $name; @@ -175,13 +177,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 [ - 'uuid' => $this->getUuid()->toString(), - 'name' => $this->getName(), - 'author' => $this->getAuthor(), - 'releaseDate' => $this->getReleaseDate(), + 'id' => $this->id->toString(), + 'name' => $this->name, + 'author' => $this->author, + 'releaseDate' => $this->releaseDate, + 'created' => $this->created, + 'updated' => $this->updated, ]; } } @@ -306,6 +320,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 + */ class CreateBookInputFilter extends AbstractInputFilter { public function __construct() @@ -428,5 +450,5 @@ To fetch a book, `curl` one of the links found in the output of the **list books The link should have the following format: ```shell -curl http://0.0.0.0:8080/book/{uuid} +curl http://0.0.0.0:8080/book/{id} ``` diff --git a/docs/book/v7/tutorials/create-book-module.md b/docs/book/v7/tutorials/create-book-module.md index 4892194..a017027 100644 --- a/docs/book/v7/tutorials/create-book-module.md +++ b/docs/book/v7/tutorials/create-book-module.md @@ -86,6 +86,7 @@ namespace Core\Book\Entity; use Core\App\Entity\AbstractEntity; use Core\App\Entity\TimestampsTrait; +use Core\App\Entity\UuidIdentifierTrait; use Core\Book\Repository\BookRepository; use DateTimeImmutable; use Doctrine\ORM\Mapping as ORM; @@ -96,6 +97,7 @@ use Doctrine\ORM\Mapping as ORM; class Book extends AbstractEntity { use TimestampsTrait; + use UuidIdentifierTrait; #[ORM\Column(name: "name", type: "string", length: 100)] protected string $name; @@ -151,13 +153,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 [ - 'uuid' => $this->getUuid()->toString(), - 'name' => $this->getName(), - 'author' => $this->getAuthor(), - 'releaseDate' => $this->getReleaseDate(), + 'id' => $this->id->toString(), + 'name' => $this->name, + 'author' => $this->author, + 'releaseDate' => $this->releaseDate, + 'created' => $this->created, + 'updated' => $this->updated, ]; } } @@ -181,6 +195,10 @@ use Dot\DependencyInjection\Attribute\Entity; #[Entity(name: Book::class)] class BookRepository extends AbstractRepository { + /** + * @param array $params + * @param array $filters + */ public function getBooks(array $params, array $filters = []): QueryBuilder { return $this @@ -214,6 +232,9 @@ interface BookServiceInterface public function saveBook(array $data): Book; + /** + * @param array $params + */ public function getBooks(array $params = []): QueryBuilder; } @@ -253,6 +274,7 @@ class BookService implements BookServiceInterface /** * @throws Exception + * @param array $data */ public function saveBook(array $data): Book { @@ -267,6 +289,9 @@ class BookService implements BookServiceInterface return $book; } + /** + * @param array $params + */ public function getBooks(array $params = []): QueryBuilder { $filters = $params['filters'] ?? []; @@ -289,7 +314,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 +440,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 + */ class CreateBookInputFilter extends AbstractInputFilter { public function __construct() @@ -619,6 +652,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>, + * factories: array, + * aliases: array, + * } + */ class ConfigProvider { public function __invoke(): array @@ -650,6 +691,9 @@ class ConfigProvider ]; } + /** + * @return MetadataType[] + */ private function getHalConfig(): array { return [ @@ -688,13 +732,13 @@ class RoutesDelegator */ public function __invoke(ContainerInterface $container, string $serviceName, callable $callback): Application { - $uuid = ConfigProvider::REGEXP_UUID; + $id = ConfigProvider::REGEXP_UUID; /** @var RouteCollectorInterface $routeCollector */ $routeCollector = $container->get(RouteCollectorInterface::class); $routeCollector->post('/book', PostBookResourceHandler::class, 'book::create-book'); - $routeCollector->get('/book/' . $uuid, GetBookResourceHandler::class, 'book::view-book'); + $routeCollector->get('/book/' . $id, GetBookResourceHandler::class, 'book::view-book'); $routeCollector->get('/book', GetBookCollectionHandler::class, 'book::list-books'); return $callback(); @@ -718,13 +762,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, + * }, + * }, + * } + * @phpstan-type DependenciesType array{ + * factories: array, + * } + */ class ConfigProvider { public function __invoke(): array { return [ - 'dependencies' => $this->getDependencies(), - 'doctrine' => $this->getDoctrineConfig(), + 'dependencies' => $this->getDependencies(), + 'doctrine' => $this->getDoctrineConfig(), + 'resultCacheLifetime' => 600, ]; } @@ -777,7 +839,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 @@ -830,5 +892,5 @@ To fetch a book, `curl` one of the links found in the output of the **list books The link should have the following format: ```shell -curl http://0.0.0.0:8080/book/{uuid} +curl http://0.0.0.0:8080/book/{id} ``` diff --git a/docs/book/v7/tutorials/find-user-by-identity.md b/docs/book/v7/tutorials/find-user-by-identity.md index fd822e7..05edebb 100644 --- a/docs/book/v7/tutorials/find-user-by-identity.md +++ b/docs/book/v7/tutorials/find-user-by-identity.md @@ -28,9 +28,9 @@ This command will list all available endpoints, which looks like this: ............................................................................. | GET | user.my-avatar.view | /user/my-avatar | | GET | user.role.list | /user/role | -| GET | user.role.view | /user/role/{uuid} | -| PATCH | user.update | /user/{uuid} | -| GET | user.view | /user/{uuid} | +| GET | user.role.view | /user/role/{id} | +| PATCH | user.update | /user/{id} | +| GET | user.view | /user/{id} | +--------+---------------------------------+--------------------------------+ ``` @@ -45,7 +45,7 @@ The endpoint we're focusing on is the last one, `user.view`, so let's take a clo If we search for the route name `user.view` we will find its definition in the `src/User/src/RoutesDelegator.php` class, where all user-related endpoints are found. ```php -$app->get('/user/' . $uuid, UserHandler::class, 'user.view'); +$app->get('/user/' . $id, UserHandler::class, 'user.view'); ``` Our route points to `get` method from `UserHandler` so let's navigate to that method. @@ -53,13 +53,13 @@ Our route points to `get` method from `UserHandler` so let's navigate to that me ```php public function get(ServerRequestInterface $request): ResponseInterface { - $user = $this->userService->findOneBy(['uuid' => $request->getAttribute('uuid')]); + $user = $this->userService->findOneBy(['id' => $request->getAttribute('id')]); return $this->createResponse($request, $user); } ``` -As we can see, the method will query the database for the user based on its uuid taken from the endpoint. +As we can see, the method will query the database for the user based on its id taken from the endpoint. We now have an understanding of how things work, and we can start to implement our own endpoint.