From 21e057bd1063e7284dd19bae908cbbf112511ef4 Mon Sep 17 00:00:00 2001 From: alexmerlin Date: Wed, 8 May 2024 16:45:36 +0300 Subject: [PATCH 1/3] Documentation updates Signed-off-by: alexmerlin --- docs/book/v4/introduction/installation.md | 2 +- docs/book/v4/introduction/introduction.md | 37 +++++++------ docs/book/v4/tutorials/create-book-module.md | 55 +++++++++++--------- 3 files changed, 49 insertions(+), 45 deletions(-) diff --git a/docs/book/v4/introduction/installation.md b/docs/book/v4/introduction/installation.md index 3e6430e..13bbbbc 100644 --- a/docs/book/v4/introduction/installation.md +++ b/docs/book/v4/introduction/installation.md @@ -90,7 +90,7 @@ Sending a GET request to the [home page](http://0.0.0.0:8080/) should output the ## Running tests -The project has 2 types of tests : functional and unit tests, you can run both types at the same type by executing this command: +The project has 2 types of tests: functional and unit tests, you can run both types at the same type by executing this command: ```shell php vendor/bin/phpunit diff --git a/docs/book/v4/introduction/introduction.md b/docs/book/v4/introduction/introduction.md index 9bf0271..b91a68e 100644 --- a/docs/book/v4/introduction/introduction.md +++ b/docs/book/v4/introduction/introduction.md @@ -6,20 +6,19 @@ Here is a list of the core components: * Middleware Microframework (mezzio/mezzio) * Error Handler (dotkernel/dot-errorhandler) -* Problem Details (mezzio-problem-details) -* CORS (mezzio-cors) +* Problem Details (mezzio/mezzio-problem-details) +* CORS (mezzio/mezzio-cors) * Routing (mezzio/mezzio-fastroute) -* Authentication (mezzio-authentication) -* Authorization (mezzio-authorization) +* Authentication (mezzio/mezzio-authentication) +* Authorization (mezzio/mezzio-authorization) * Config Aggregator (laminas/laminas-config-aggregator) * Container (roave/psr-container-doctrine) -* Implicit Head, Options and Method Not Allowed * Annotations (dotkernel/dot-annotated-services) * Input Filter (laminas/laminas-inputfilter) -* Doctrine -* Hydrator (laminas/laminas-hydrator) +* Doctrine 2 ORM (doctrine/orm) +* Serializer/Deserializer (laminas/laminas-hydrator) * Paginator (laminas/laminas-paginator) -* HAL (mezzio-hal) +* HAL (mezzio/mezzio-hal) * CLI (dotkernel/dot-cli) * TwigRenderer (mezzio/mezzio-twigrenderer) * Fixtures (dotkernel/dot-data-fixtures) @@ -27,7 +26,7 @@ Here is a list of the core components: ## Doctrine 2 ORM -For the persistence in a relational database management system we chose Doctrine ORM (object-relational mapper) . +For the persistence in a relational database management system we chose Doctrine ORM (object-relational mapper). The benefit of Doctrine for the programmer is the ability to focus on the object-oriented business logic and worry about persistence only as a secondary priority. @@ -40,15 +39,15 @@ Our documentation is Postman based. We use the following files in which we store ## Hypertext Application Language -For our API payloads ( a value object for describing the API resource, its relational links and any embedded/child resources related to it ) we chose mezzio-hal. +For our API payloads (a value object for describing the API resource, its relational links and any embedded/child resources related to it) we chose mezzio-hal. ## CORS By using `MezzioCorsMiddlewareCorsMiddleware`, the CORS preflight will be recognized and the middleware will start to detect the proper CORS configuration. The Router is used to detect every allowed request method by executing a route match with all possible request methods. Therefore, for every preflight request, there is at least one Router request. -## OAuth 2 +## OAuth 2.0 -OAuth 2 is an authorization framework that enables applications to obtain limited access to user accounts on your DotKernel API. We are using mezzio/mezzio-authentication-oauth2 which provides OAuth2 authentication for Mezzio and PSR-7/PSR-15 applications by using league/oauth2-server package. +OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your DotKernel API. We are using mezzio/mezzio-authentication-oauth2 which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using league/oauth2-server package. ## Email @@ -66,7 +65,7 @@ You can further customize your api within the autoload directory where each conf ## Routing -Each Module has a `RoutesDelegator.php` file for managing existing routes inside that specific module. It also allows a quick way of adding new routes by providing the route path, Middlewares that the route will use and the route name. +Each module has a `RoutesDelegator.php` file for managing existing routes inside that specific module. It also allows a quick way of adding new routes by providing the route path, Middlewares that the route will use and the route name. You can allocate permissions per route name in order to restrict access for a user role to a specific route in `config/autoload/authorization.global.php`. @@ -76,17 +75,17 @@ For registering new commands first make sure your command class extends `Symfony ## File locker -Here you will also find our brand-new file locker configuration, so you can easily turn it on or off ( by default: `'enabled' => true` ) +Here you will also find our brand-new file locker configuration, so you can easily turn it on or off (by default: `'enabled' => true`). Note: The File Locker System will create a `command-{command-default-name}.lock` file which will not let another instance of the same command to run until the previous one has finished. ## PSR Standards -* PSR-3: Logger Interface – the application uses `LoggerInterface` for error logging -* PSR-4: Autoloader – the application locates classes using an autoloader -* PSR-7: HTTP message interfaces – the handlers return `ResponseInterface` -* PSR-11: Container interface – the application is container-based -* PSR-15: HTTP Server Request Handlers – the handlers implement `RequestHandlerInterface` +* [PSR-3](https://www.php-fig.org/psr/psr-3/): Logger Interface – the application uses `LoggerInterface` for error logging +* [PSR-4](https://www.php-fig.org/psr/psr-4): Autoloader – the application locates classes using an autoloader +* [PSR-7](https://www.php-fig.org/psr/psr-7): HTTP message interfaces – the handlers return `ResponseInterface` +* [PSR-11](https://www.php-fig.org/psr/psr-11): Container interface – the application is container-based +* [PSR-15](https://www.php-fig.org/psr/psr-15): HTTP Server Request Handlers – the handlers implement `RequestHandlerInterface` ## Tests diff --git a/docs/book/v4/tutorials/create-book-module.md b/docs/book/v4/tutorials/create-book-module.md index 32b753f..4dbc9d3 100644 --- a/docs/book/v4/tutorials/create-book-module.md +++ b/docs/book/v4/tutorials/create-book-module.md @@ -7,27 +7,27 @@ The below file structure is just an example, you can have multiple components su ```markdown . └── src/ -└── Book/ -└── src/ -├── Collection/ -│ └── BookCollection.php -├── Entity/ -│ └── Book.php -├── Handler/ -│ └── BookHandler.php -├── InputFilter/ -│ ├── Input/ -│ │ ├── AuthorInput.php -│ │ ├── NameInput.php -│ │ └── ReleaseDateInput.php -│ └── BookInputFilter.php -├── Repository/ -│ └── BookRepository.php -├── Service/ -│ ├── BookService.php -│ └── BookServiceInterface.php -├── ConfigProvider.php -└── RoutesDelegator.php + └── Book/ + └── src/ + ├── Collection/ + │ └── BookCollection.php + ├── Entity/ + │ └── Book.php + ├── Handler/ + │ └── BookHandler.php + ├── InputFilter/ + │ ├── Input/ + │ │ ├── AuthorInput.php + │ │ ├── NameInput.php + │ │ └── ReleaseDateInput.php + │ └── BookInputFilter.php + ├── Repository/ + │ └── BookRepository.php + ├── Service/ + │ ├── BookService.php + │ └── BookServiceInterface.php + ├── ConfigProvider.php + └── RoutesDelegator.php ``` * `src/Book/src/Collection/BookCollection.php` - a collection refers to a container for a group of related objects, typically used to manage sets of related entities fetched from a database @@ -532,9 +532,14 @@ class BookHandler implements RequestHandlerInterface Once you set up all the files as in the example above, you will need to do a few additional configurations: -* Register the namespace by adding this line `"Api\\Book\\": "src/Book/src/",` in `composer.json` under the `autoload.psr-4` key. -* Register the module by adding `Api\Book\ConfigProvider::class,` under `Api\User\ConfigProvider::class,`. -* Register the module's routes by adding `\Api\Book\RoutesDelegator::class,` under `\Api\User\RoutesDelegator::class,` in `src/App/src/ConfigProvider.php`. +* register the namespace by adding this line `"Api\\Book\\": "src/Book/src/",` in `composer.json` under the `autoload.psr-4` key +* register the module by adding `Api\Book\ConfigProvider::class,` under `Api\User\ConfigProvider::class,` +* register the module's routes by adding `\Api\Book\RoutesDelegator::class,` under `\Api\User\RoutesDelegator::class,` in `src/App/src/ConfigProvider.php` +* update Composer autoloader by running the command: + +```shell +composer dump-autoload +``` It should look like this: @@ -641,7 +646,7 @@ curl -X POST http://0.0.0.0:8080/book -d '{"name": "test", "author": "author name", "releaseDate": "2023-03-03"}' ``` -To list the books use : +To list the books use: ```shell curl http://0.0.0.0:8080/books From ec198d70211257e4a68afffe2bf9fb4eaba4a745 Mon Sep 17 00:00:00 2001 From: Alex Karajos Date: Thu, 9 May 2024 13:16:03 +0300 Subject: [PATCH 2/3] Removed PHPUnit badge The PHPUnit badge used the `actions/workflows/run-tests.yml` file to pull it's data. Since PHPUnit tests are run via Laminas' `.github/workflows/continuous-integration.yml` file, this information is no longer available. --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index f82fd80..e37aae3 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,6 @@ Based on Enrico Zimuel's [Zend Expressive API - Skeleton example](https://github [![GitHub license](https://img.shields.io/github/license/dotkernel/api)](https://github.com/dotkernel/api/blob/4.0/LICENSE.md) [![Build Static](https://github.com/dotkernel/api/actions/workflows/continuous-integration.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/api/actions/workflows/continuous-integration.yml) -[![Build Static](https://github.com/dotkernel/api/actions/workflows/run-tests.yml/badge.svg?branch=4.0)](https://github.com/dotkernel/api/actions/workflows/run-tests.yml) [![codecov](https://codecov.io/gh/dotkernel/api/graph/badge.svg?token=53FN78G5CK)](https://codecov.io/gh/dotkernel/api) [![Qodana](https://github.com/dotkernel/api/actions/workflows/qodana_code_quality.yml/badge.svg)](https://github.com/dotkernel/api/actions/workflows/qodana_code_quality.yml) From f8a862345b7acd75ddbf2462e9e3c1a75529647b Mon Sep 17 00:00:00 2001 From: Alex Karajos Date: Mon, 13 May 2024 07:51:33 +0300 Subject: [PATCH 3/3] Update mkdocs.yml --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index ec0644c..5e45327 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,7 @@ docs_dir: docs/book site_dir: docs/html extra: - project: "DotKernel API" + project: API current_version: v4 versions: - v4 @@ -18,7 +18,7 @@ nav: - Tutorials: - "Creating a book module": v4/tutorials/create-book-module.md site_name: api -site_description: "DotKernel API" +site_description: DotKernel API repo_url: "https://github.com/dotkernel/api" plugins: - search