New documentation files.

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

Author: alexmerlin

.github/workflows/docs-build.yml

@@ -0,0 +1,16 @@
+name: docs-build
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build Docs
+        uses: dotkernel/documentation-theme/github-actions/docs@main
+        env:
+          DEPLOY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

api-doc/customize.md

@@ -0,0 +1 @@
+# ../../README.md

api-doc/intro.md

@@ -0,0 +1,20 @@
+## Comparison between api-tools and Dotkernel API
+
+|                    | API-TOOLS(APIGILITY)                           | DOTKERNEL API                                                            |
+|--------------------|------------------------------------------------|--------------------------------------------------------------------------|
+| URL                | [api-tools](https://api-tools.getlaminas.org/) | [Dotkernel API](https://www.dotkernel.org)                               |
+| YEAR               | 2012                                           | 2018                                                                     |
+| PHP VERSION        | <= 8.2                                         | >= 8.1                                                                   |
+| ARHITECTURE        | MVC, Event Driven                              | Middleware                                                               |
+| OSS Lifecycle      | Archived                                       | ![](https://img.shields.io/osslifecycle/dotkernel/api?style=flat&label=) |
+| STYLE              | REST, RPC                                      | REST                                                                     |
+| VERSIONING         | Yes                                            | No                                                                       |
+| DOCUMENTATION      | Swagger (Automated)                            | Postman (Manual)                                                         |
+| LICENSE            | BSD-3                                          | MIT                                                                      |
+| DEFAULT DB LAYER   | laminas-db                                     | doctrine-orm                                                             |
+| AUTHORIZATION      | ACL                                            | RBAC-guard                                                               |
+| AUTHENTICATION     | HTTP Basic/Digest <br/> OAuth2.0               | OAuth2.0                                                                 |
+| CI/CD              | Yes                                            | Yes                                                                      |
+| Unit Tests         | Yes                                            | Yes                                                                      |
+| Endpoint Generator | Yes                                            | No                                                                       |
+| PSR                | PSR-7                                          | PSR-7, PSR-15                                                            |

api-doc/swagger.md

@@ -0,0 +1,54 @@
+# File structure
+
+It is a good practice to standardize the file structure of projects. This way it’s easier to keep a clean overview of multiple projects, and less time is wasted trying to find the correct class.
+
+When using DotKernel API the following structure is recommended:
+
+## Main directories
+
+* `src` - should contain the source code files
+* `templates` - should contain the page templates and layouts
+* `data` - should contain project-related data (AVOID storing sensitive data on VCS)
+* `docs` - should contain project-related documentation
+
+These directories reside in one of the following directories:
+
+* if the Module is a composer package where the directories above are stored in the package’s root path, eg.: `/vendor/my-name/my-project-name/`
+* if the Module is an extension/component for the project, eg.: `/src/MyProjectName`
+
+## The `src` directory
+
+This directory contains all source code related to the Module. It should contain following directories, if they’re not empty:
+
+* Handler - Action classes (similar to Controllers but can only perform one action)
+* Entity - For database entities
+* Service - Service classes
+* Collection - Database entities collections
+* Repository - Entity repository folder
+
+> The above example is just some of the directories a project may include, but these should give you an idea of how the structure should look like.
+
+Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc.
+
+The `src` directory should also contain 2 files:
+
+* `ConfigProvider.php` - Provides configuration data
+* `RoutesDelegator.php` - Module main routes entry file
+
+## The `templates` directory
+
+This directory 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
+
+## The `data` directory
+
+This directory contains project-related data (such as cache, file uploads)
+
+We recommend using the following directory structure:
+
+* `data/cache` - location where caches are stored
+* `data/oauth` - encryption, private and public keys needed for authentication.
+* `data/lock` - folder where lock files generated by commands are stored, if enabled
+* `data/doctrine/fixtures` - folder for doctrine data fixtures
+* `data/doctrine/migrations` - folder for doctrine migrations

api-primer/content-negotiation.md

@@ -0,0 +1,7 @@
+# Clone the project
+
+Using your terminal, navigate inside the directory you want to download the project files into. Make sure that the directory is empty before proceeding to the download process. Once there, run the following command:
+
+```shell
+git clone https://github.com/dotkernel/api.git .
+```

api-primer/content-validation.md

@@ -0,0 +1,109 @@
+# Installation
+
+## Install dependencies
+
+```shell
+composer install
+```
+
+## Development mode
+
+If you're installing the project for development, make sure you have development mode enabled, by running:
+
+```shell
+composer development-enable
+```
+
+You can disable development mode by running:
+
+```shell
+composer development-disable
+```
+
+You can check if you have development mode enabled by running:
+
+```shell
+composer development-status
+```
+
+## Prepare config files
+
+* duplicate `config/autoload/cors.local.php.dist` as `config/autoload/cors.local.php` <- if your API will be consumed by another application, make sure configure the `allowed_origins`
+* duplicate `config/autoload/local.php.dist` as `config/autoload/local.php`
+* duplicate `config/autoload/mail.local.php.dist` as `config/autoload/mail.local.php` <- if your API will send emails, make sure you fill in SMTP connection params
+* **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php` <- this creates a new in-memory database that your tests will run on.
+
+## Setup database
+
+Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`.
+
+## Running migrations
+
+* create a new MySQL database - set collation to `utf8mb4_general_ci`
+* run the database migrations by using the following command:
+
+```shell
+php vendor/bin/doctrine-migrations migrate
+```
+
+This command will prompt you to confirm that you want to run it.
+
+> WARNING! You are about to execute a migration in database "..." that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
+
+Hit `Enter` to confirm the operation.
+
+## Executing fixtures
+
+**Fixtures are used to seed the database with initial values and should be executed after migrating the database.**
+
+To list all the fixtures, run:
+
+```shell
+php bin/doctrine fixtures:list
+```
+
+This will output all the fixtures in the order of execution.
+
+To execute all fixtures, run:
+
+```shell
+php bin/doctrine fixtures:execute
+```
+
+To execute a specific fixture, run:
+
+```shell
+php bin/doctrine fixtures:execute --class=FixtureClassName
+```
+
+More details on how fixtures work can be found here: https://github.com/dotkernel/dot-data-fixtures#creating-fixtures
+
+## Test the installation
+
+```shell
+php -S 0.0.0.0:8080 -t public
+```
+
+Sending a GET request to the [home page](http://0.0.0.0:8080/) should output the following message:
+
+> {"message": "Welcome to DotKernel API!"}
+
+## 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:
+
+```shell
+php vendor/bin/phpunit
+```
+
+## Running unit tests
+
+```shell
+vendor/bin/phpunit --testsuite=UnitTests --testdox --colors=always
+```
+
+## Running functional tests
+
+```shell
+vendor/bin/phpunit --testsuite=FunctionalTests --testdox --colors=always
+```

api-primer/error-reporting.md

@@ -0,0 +1,110 @@
+# 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)
+* Annotations (dotkernel/dot-annotated-services)
+* Input Filter (laminas/laminas-inputfilter)
+* Doctrine 2 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)
+
+## Doctrine 2 ORM
+
+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.
+
+## Documentation
+
+Our documentation is Postman based. We use the following files in which we store information about every available endpoint ready to be tested:
+
+* documentation/DotKernel_API.postman_collection.json
+* documentation/DotKernel_API.postman_environment.json
+
+## 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.
+
+## 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.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.
+
+## 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.
+
+## Configuration
+
+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.
+
+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.
+
+## 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.
+
+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`.
+
+## Commands
+
+For registering new commands first make sure your command class extends `SymfonyComponentConsoleCommandCommand`. 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`).
+
+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.
+
+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
+
+```shell
+vendor/bin/phpunit --testsuite=UnitTests --testdox --colors=always
+```
+
+## Running functional tests
+
+```shell
+vendor/bin/phpunit --testsuite=FunctionalTests --testdox --colors=always
+```

api-primer/halprimer.md

@@ -0,0 +1,30 @@
+# Packages
+
+* `dotkernel/dot-annotated-services` - Dependency injection component using class attributes.
+* `dotkernel/dot-cache` - Cache component extending symfony-cache
+* `dotkernel/dot-cli` - Component for creating console applications based on laminas-cli
+* `dotkernel/dot-data-fixtures` - Provides a CLI interface for listing & executing doctrine data fixtures
+* `dotkernel/dot-errorhandler` - Logging Error Handler for Middleware Applications
+* `dotkernel/dot-mail` - Mail component based on laminas-mail
+* `dotkernel/dot-response-header` - Middleware for setting custom response headers.
+* `laminas/laminas-component-installer` - Composer plugin for injecting modules and configuration providers into application configuration
+* `laminas/laminas-config` - Provides a nested object property based user interface for accessing this configuration data within application code
+* `laminas/laminas-config-aggregator` - Lightweight library for collecting and merging configuration from different sources
+* `laminas/laminas-http` - Provides an easy interface for performing Hyper-Text Transfer Protocol (HTTP) requests
+* `laminas/laminas-hydrator` - Serialize objects to arrays, and vice versa
+* `laminas/laminas-inputfilter` - Normalize and validate input sets from the web, APIs, the CLI, and more, including files
+* `laminas/laminas-paginator` - Paginate collections of data from arbitrary sources
+* `laminas/laminas-stdlib` - SPL extensions, array utilities, error handlers, and more
+* `laminas/laminas-text` - Create FIGlets and text-based tables
+* `mezzio/mezzio` - PSR-15 Middleware Microframework
+* `mezzio/mezzio-authentication-oauth2` - OAuth2 (server) authentication middleware for Mezzio and PSR-7 applications
+* `mezzio/mezzio-authorization-acl` - laminas-permissions-acl adapter for mezzio-authorization
+* `mezzio/mezzio-authorization-rbac` - mezzio authorization rbac adapter for laminas/laminas-permissions-rbac
+* `mezzio/mezzio-cors` - CORS component for Mezzio and other PSR-15 middleware runners
+* `mezzio/mezzio-fastroute` - FastRoute integration for Mezzio
+* `mezzio/mezzio-hal` - Hypertext Application Language implementation for PHP and PSR-7
+* `mezzio/mezzio-problem-details` - Problem Details for PSR-7 HTTP APIs addressing the RFC 7807 standard
+* `mezzio/mezzio-twigrenderer` - Twig integration for Mezzio
+* `ramsey/uuid-doctrine` - Use ramsey/uuid as a Doctrine field type
+* `roave/psr-container-doctrine` - Doctrine Factories for PSR-11 Containers
+* `symfony/filesystem` - Provides basic utilities for the filesystem

api-primer/http-negotiation.md

@@ -0,0 +1,35 @@
+# Server Requirements
+
+For production, we highly recommend a *nix based system.
+
+## Webserver
+
+* Apache >= 2.2 **or** Nginx
+* mod_rewrite
+* .htaccess support `(AllowOverride All)`
+
+## PHP >= 8.2
+
+Both mod_php and FCGI (FPM) are supported.
+
+## Required Settings and Modules & Extensions
+
+* memory_limit >= 128M
+* upload_max_filesize and post_max_size >= 100M (depending on your data)
+* mbstring
+* CLI SAPI (for Cron Jobs)
+* Composer (added to $PATH)
+
+## RDBMS
+
+* MySQL / MariaDB >= 5.5.3
+
+## Recommended extensions
+
+* opcache
+* pdo_mysql or mysqli (if using MySQL or MariaDB as RDBMS)
+* dom - if working with markup files structure (html, xml, etc)
+* simplexml - working with xml files
+* gd, exif - if working with images
+* zlib, zip, bz2 - if compessing files
+* curl (required if APIs are used)