Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Versions #76

Merged
merged 3 commits into from
Nov 21, 2024
Merged

Versions #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a8d914c
updated intro, file structure
bidi47 Nov 20, 2024
a2d294d
fixed linting
bidi47 Nov 20, 2024
3b79ed7
updated file structure page
bidi47 Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 38 additions & 41 deletions docs/book/v5/introduction/file-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

* `.github` - containes workflow files
* `.github` - contains GitHub 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
Expand All @@ -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
Expand All @@ -64,55 +53,63 @@ 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
* `doctrine`: database migrations and fixtures
* `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` 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`
60 changes: 13 additions & 47 deletions docs/book/v5/introduction/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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
```