From a8d914c59145f6bba297370ff988f2427a786c9e Mon Sep 17 00:00:00 2001 From: bidi Date: Wed, 20 Nov 2024 15:43:45 +0200 Subject: [PATCH 1/3] updated intro, file structure Signed-off-by: bidi --- docs/book/v5/introduction/file-structure.md | 79 ++++++++++----------- docs/book/v5/introduction/introduction.md | 60 ++++------------ 2 files changed, 51 insertions(+), 88 deletions(-) diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 5e295f3..1bce905 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/docs/book/v5/introduction/file-structure.md @@ -8,33 +8,22 @@ When using Dotkernel API the following structure is installed by default: ![Dotkernel API File Structure!](https://docs.dotkernel.org/img/api/file-structure-dk-api.png) -## Main directories - -* `bin` - executable files from CLI -* `config` - various configuration files -* `data` - should contain project-related data (AVOID storing sensitive data on VCS) -* `documentation` - should contain project-related documentation -* `log` - storage of log files generated by dot-error-log library -* `public` - publicly visible files. The webserver need to have this folder as www-document root folder. -* `src` - should contain the source code files -* `test` - should contain the test files - -## Special purpose folders +# Special purpose folders * `.github` - containes workflow files * `.laminas-ci` - contains laminas-ci workflow files -### `bin` directory +## `bin` folder -This directory contents are +This folder contents are -* `clear-config-cache.php` which removes the config cache file (`data/cache/config-cache.php` - available only when development mode is enabled). +* `clear-config-cache.php` - removes the config cache file (`data/cache/config-cache.php` - available only when development mode is enabled). * `cli.php` used to build console applications based on [laminas-cli](https://github.com/laminas/laminas-cli) -* `doctrine` used by the doctrine fixtures to populate the database tables +* `doctrine` - used by the doctrine fixtures to populate the database tables -### `config` directory +## `config` folder -This directory contains all application-related config files: +This folder contains all application-related config files: * `cli-config.php`: command line interface configuration used by migrations, fixtures, crons * `config.php`: registers ConfigProviders for installing packages @@ -44,9 +33,9 @@ This directory contains all application-related config files: * `pipeline.php`: contains a list of middlewares, in the order of their execution * `twig-cs-fixer.php`: configuration file for Twig code style checker/fixer -#### `config/autoload` directory +### `config/autoload` folder -This directory contains all service-related local and global config files: +This folder contains all service-related local and global config files: * `authorization.global.php`: configures access per route for user roles * `cli.global.php`: configures cli @@ -64,9 +53,9 @@ This directory contains all service-related local and global config files: * `response-header.global.php`: defines headers per route * `templates.global.php`: dotkernel/dot-twigrenderer config file -### `data` directory +## `data` folder -This directory is a storage for project data files and service caches. +This folder is a storage for project data files and service caches. It contains these folders: * `cache`: cache for e.g. Twig files @@ -74,45 +63,53 @@ It contains these folders: * `oauth`: encryption, private and public keys needed for authentication * `data/lock` - lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/) -> AVOID storing sensitive data on VCS. +> AVOID storing sensitive data on VCS! -### `log` directory +## `log` folder -This directory stores daily log files. +This folder stores daily log files. When you access the application from the browser, (if not already created) a new log file gets created in the format specified in the `config/autoload/error-handling.global.php` config file under the `stream` array key. -### `public` directory +## `public` folder -This directory contains all publicly available assets and serves as the entry point of the application: +This folder contains all publicly available assets and serves as the entry point of the application: * `uploads`: a folder that normally contains files uploaded via the application * `.htaccess`: server configuration file used by Apache web server; it enables the URL rewrite functionality * `index.php`: the application's main entry point * `robots.txt.dist`: a sample robots.txt file that allows/denies bot access to certain areas of your application; activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment -## `src` directory +## `src` folder This folder contains a separate folder for each Module. -Each Module folder, in turn, should contain following directories, unless they are empty: -* Handler - Action classes (similar to Controllers but can only perform one action) -* Entity - Used by database entities -* Service - Service classes -* Collection - Database entities collections -* Repository - Entity repository folder +These are the modules included by default: + +* `Admin` - contains functionality for managing users with `admin` role; note these are users save in the `admin` database table +* `App` - contains core functionality, from authentication, to rendering, to error reporting +* `User` - contains functionality for managing regular users + +### Module contents + +Each Module folder, in turn, should contain the following folders, unless they are empty: -> The above example is just some of the directories a project may include, but they should give you an idea about the recommended structure. +* `src/Handler` - Action classes (similar to Controllers but can only perform one action) +* `src/Entity` - Used by database entities +* `src/Service` - Service classes +* `src/Collection` - Database entities collections +* `src/Repository` - Entity repository folder -Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc. +The above example is just some of the folders a project may include, but they should give you an idea about the recommended structure. +Other classes the `src` folder may include are `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc. -The `src` directory normally also contains these files: +The `src` folder in each Module folder normally also contains these files: * `ConfigProvider.php` - Configuration data for the module * `OpenAPI.php` - Detailed descriptions for each endpoint in the OpenAPI format -* `RoutesDelegator.php` - Module specific route registrations Module main routes entry file +* `RoutesDelegator.php` - Module specific route registrations -## `templates` directory +### `templates` folder in Modules -This directory contains the template files, used for example to help render e-mail templates. +This folder contains the template files, used for example to help render e-mail templates. -> Dotkernel API uses twig as Templating Engine. All template files have the extension .html.twig +> Dotkernel API uses twig as Templating Engine. All template files have the extension `.html.twig` diff --git a/docs/book/v5/introduction/introduction.md b/docs/book/v5/introduction/introduction.md index 0e1360b..8e28003 100644 --- a/docs/book/v5/introduction/introduction.md +++ b/docs/book/v5/introduction/introduction.md @@ -1,28 +1,6 @@ # Introduction -Based on Enrico Zimuel’s Zend Expressive API – Skeleton example, Dotkernel API runs on Laminas and Mezzio components and implements standards like PSR-3, PSR-4, PSR-7, PSR-11 and PSR-15. - -Here is a list of the core components: - -* Middleware Microframework (mezzio/mezzio) -* Error Handler (dotkernel/dot-errorhandler) -* Problem Details (mezzio/mezzio-problem-details) -* CORS (mezzio/mezzio-cors) -* Routing (mezzio/mezzio-fastroute) -* Authentication (mezzio/mezzio-authentication) -* Authorization (mezzio/mezzio-authorization) -* Config Aggregator (laminas/laminas-config-aggregator) -* Container (roave/psr-container-doctrine) -* Dependency Injection (dotkernel/dot-dependency-injection) -* Input Filter (laminas/laminas-inputfilter) -* Doctrine 3 ORM (doctrine/orm) -* Serializer/Deserializer (laminas/laminas-hydrator) -* Paginator (laminas/laminas-paginator) -* HAL (mezzio/mezzio-hal) -* CLI (dotkernel/dot-cli) -* TwigRenderer (mezzio/mezzio-twigrenderer) -* Fixtures (dotkernel/dot-data-fixtures) -* UUID (ramsey/uuid-doctrine) +Below is a quick overview of features in Dotkernel API. ## Doctrine 3 ORM @@ -40,7 +18,7 @@ We use the following files in which we store information about every available e ## 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 use [mezzio/mezzio-hal](https://github.com/mezzio/mezzio-hal). ## CORS @@ -51,23 +29,23 @@ Therefore, for every preflight request, there is at least one Router request. ## OAuth 2.0 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. +We use [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) which provides OAuth 2.0 authentication for Mezzio and PSR-7/PSR-15 applications by using the [thephpleague/oauth2-server]https://github.com/thephpleague/oauth2-server package. ## Email It is not unlikely for an API to send emails depending on the use case. Here is another area where Dotkernel API shines. -Using `DotMailServiceMailService` provided by dotkernel/dot-mail you can easily send custom email templates. +Using `DotMailServiceMailService` provided by [dotkernel/dot-mail](https://github.com/dotkernel/dot-mail) you can easily send custom email templates. ## Configuration -From authorization at request route level to API keys for your application, you can find every configuration variable in the config directory. +From authorization at request route level to API keys for your application, you can find every configuration variable in the `config` directory. -Registering a new module can be done by including its ConfigProvider.php in config.php. +Registering a new module can be done by including its `ConfigProvider.php` in `config.php`. -Brand new middlewares should go into pipeline.php. Here you can edit the order in which they run and find more info about the currently included ones. +Brand new middlewares should go into `pipeline.php`. Here you can edit the order in which they run and find more info about the currently included ones. -You can further customize your api within the autoload directory where each configuration category has its own file. +You can further customize your api within the `autoload` directory that holds configuration files for each category. ## Routing @@ -83,37 +61,25 @@ Then you can enable it by registering it in `config/autoload/cli.global.php`. ## 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 file locker configuration, so you can easily enable and disable it (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](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 One of the best ways to ensure the quality of your product is to create and run functional and unit tests. -You can find factory-made tests in the `tests/AppTest/` folder, and you can also register your own. +You can find factory-made tests in the `test` folder, and you can also register your own. -We have 2 types of tests: functional and unit tests, you can run both types at the same type by executing this command: +We have 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 ``` -## Running unit tests +Alternatively, you can run each test category separately with these commands: ```shell vendor/bin/phpunit --testsuite=UnitTests --testdox --colors=always -``` - -## Running functional tests - -```shell vendor/bin/phpunit --testsuite=FunctionalTests --testdox --colors=always ``` From a2d294d3b4ec644db1249c1aa74e95efdbce9d5d Mon Sep 17 00:00:00 2001 From: bidi Date: Wed, 20 Nov 2024 15:45:37 +0200 Subject: [PATCH 2/3] fixed linting Signed-off-by: bidi --- docs/book/v5/introduction/file-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 1bce905..2977571 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/docs/book/v5/introduction/file-structure.md @@ -8,7 +8,7 @@ When using Dotkernel API the following structure is installed by default: ![Dotkernel API File Structure!](https://docs.dotkernel.org/img/api/file-structure-dk-api.png) -# Special purpose folders +## Special purpose folders * `.github` - containes workflow files * `.laminas-ci` - contains laminas-ci workflow files From 3b79ed710d20aed73ed3094221e795b465ff7722 Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 21 Nov 2024 14:26:44 +0200 Subject: [PATCH 3/3] updated file structure page Signed-off-by: bidi --- docs/book/v5/introduction/file-structure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 2977571..a290d6a 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/docs/book/v5/introduction/file-structure.md @@ -10,7 +10,7 @@ When using Dotkernel API the following structure is installed by default: ## Special purpose folders -* `.github` - containes workflow files +* `.github` - contains GitHub workflow files * `.laminas-ci` - contains laminas-ci workflow files ## `bin` folder @@ -63,7 +63,7 @@ It contains these folders: * `oauth`: encryption, private and public keys needed for authentication * `data/lock` - lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/) -> AVOID storing sensitive data on VCS! +> AVOID storing sensitive data on the repository! ## `log` folder