updated file structure, psr pages

bidi47 · bidi47 · commit 4adcaf9b7f3e · 2024-11-19T23:40:29.000+02:00
Signed-off-by: bidi &lt;bidi@apidemia.com&gt;
diff --git a/docs/book/v5/core-features/content-validation.md b/docs/book/v5/core-features/content-validation.md
@@ -1,6 +1,6 @@
 # Content Negotiation
 
-> Introduced in Dotkernel API 4.5.0
+> Introduced in Dotkernel API 5.0.0
 
 **Content Negotiation** is performed by an application in order :
 
diff --git a/docs/book/v5/core-features/dependency-injection.md b/docs/book/v5/core-features/dependency-injection.md
@@ -1,12 +1,12 @@
 # Dependency Injection
 
-> Introduced in Dotkernel API 5.0.0
-
 Dependency injection is a design pattern used in software development to implement inversion of control.
 In simpler terms, it's the act of providing dependencies for an object during instantiation.
 
 In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter injection and property injection.
 
+> Introduced in Dotkernel API 5.0.0
+
 Dotkernel API, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection.
 
 ## Usage
diff --git a/docs/book/v5/core-features/error-reporting.md b/docs/book/v5/core-features/error-reporting.md
@@ -1,7 +1,5 @@
 # Error reporting endpoint
 
-> Backward incompatibility introduced in Dotkernel API 4.1.0
-
 The error reporting endpoint was designed to allow the **frontend developers** of your API to report any bugs they encounter in a secure way that is fully under your control.
 To prevent unauthorized usage, the endpoint is protected by a token in the request's header.
 
diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md
@@ -24,38 +24,95 @@ When using Dotkernel API the following structure is installed by default:
 * `.github`  - containes workflow files
 * `.laminas-ci` - contains laminas-ci workflow files
 
+### `bin` directory
+
+This directory contents are
+
+* `clear-config-cache.php` which 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
+
+### `config` directory
+
+This directory 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
+* `container.php`: main service container that provides access to all registered services
+* `development.config.php.dist`: activates debug mode; gets symlinked as `development.config.php` when enabling development mode 
+* `migrations.php`: configuration for database migration, like migration file location and table to save the migration log 
+* `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
+
+This directory contains all service-related local and global config files:
+
+* `authorization.global.php`: configures access per route for user roles
+* `cli.global.php`: configures cli
+* `content-negotiation.global.php`: configures request and response formats
+* `cors.local.php.dist`: configures Cross-Origin Resource Sharing, like call origin, headers, cookies
+* `dependencies.global.php`: config file to set global dependencies that should be accessible by all modules
+* `development.local.php.dist`: gets symlinked as `development.local.php` when enabling development mode - activates error handlers
+* `doctrine.global.php`: configuration used by Object–relational mapping
+* `error-handling.global.php`: configures and activates error logs
+* `local.php.dist`: local config file where you can overwrite application name and URL
+* `local.test.php.dist`: local configuration for functional tests
+* `mail.local.php.dist`: mail configuration; e.g. sendmail vs smtp, message configuration, mail logging
+* `mezzio.global.php`: Mezzio core config file
+* `mezzio-tooling-factories.global.php`: add or remove factory definitions
+* `response-header.global.php`: defines headers per route
+* `templates.global.php`: dotkernel/dot-twigrenderer config file
+
+### `data` directory
+
+This directory 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.
+
+### `log` directory
+
+This directory 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
+
+This directory 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
 
-This directory contains all source code related to the Module. It should contain following directories, if they’re not empty:
+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 - For database entities
+* Entity - Used by 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.
+> The above example is just some of the directories a project may include, but they should give you an idea about the recommended structure.
 
 Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc.
 
-The `src` directory should also contain 2 files:
+The `src` directory normally also contains these files:
 
-* `ConfigProvider.php` - Provides configuration data
-* `RoutesDelegator.php` - Module main routes entry file
+* `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
 
 ## `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
-
-## `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/doctrine` - fixtures and migrations
-* `data/lock` - lock files generated by `dotkernel/dot-cli`  [See more](https://docs.dotkernel.org/dot-cli/v3/lock-files/)
diff --git a/docs/book/v5/introduction/psr.md b/docs/book/v5/introduction/psr.md
@@ -4,24 +4,35 @@ Some of the PSRs on this list are at the core of Dotkernel API, but several othe
 Below is the full list of PSRs present in Dotkernel API and their purpose.
 
 * PSR-3: [Logger Interface](https://www.php-fig.org/psr/psr-3/)
-    * Interface for logging libraries.
+    * Interface for logging libraries
+    * Interfaces implemented in [php-fig/log](https://github.com/php-fig/log)
 * PSR-4: [Autoloader](https://www.php-fig.org/psr/psr-4/)
-    * Autoloading classes from file paths.
+    * Autoloading classes from file paths
+    * Interfaces implemented in [laminas/laminas-loader](https://github.com/laminas/laminas-loader)
 * PSR-6: [Caching Interface](https://www.php-fig.org/psr/psr-6/)
-    * Interface for caching systems to improve the performance of any project.
+    * Interface for caching systems to improve the performance of any project
+    * Interfaces implemented in [php-fig/cache](https://github.com/php-fig/cache)
 * PSR-7: [HTTP message interfaces](https://www.php-fig.org/psr/psr-7/)
-    * Interfaces for representing HTTP messages and URIs for use with HTTP messages.
+    * Interfaces for representing HTTP messages and URIs for use with HTTP messages
+    * Interfaces implemented in [php-fig/http-message](https://github.com/php-fig/http-message)
 * PSR-11: [Container interface](https://www.php-fig.org/psr/psr-11/)
-    * Interface for dependency injection containers.
+    * Interface for dependency injection containers
+    * Interfaces implemented in [php-fig/container](https://github.com/php-fig/container)
 * PSR-13: [Link definition interfaces](https://www.php-fig.org/psr/psr-13/)
-    * Way of representing a hypermedia link independently of the serialization format.
+    * Way of representing a hypermedia link independently of the serialization format
+    * Interfaces implemented in [php-fig/link](https://github.com/php-fig/link)
 * PSR-14: [Event Dispatcher](https://www.php-fig.org/psr/psr-14/)
-    * Mechanism for event-based extension and collaboration.
+    * Mechanism for event-based extension and collaboration
+    * Interfaces implemented in [php-fig/event-dispatcher](https://github.com/php-fig/event-dispatcher)
 * PSR-15: [HTTP Server Request Handlers](https://www.php-fig.org/psr/psr-15/)
-    * Interfaces for HTTP server request handlers and HTTP server middleware components that use HTTP messages.
+    * Interfaces for HTTP server request handlers and HTTP server middleware components that use HTTP messages
+    * Interfaces implemented in [php-fig/http-server-handler](https://github.com/php-fig/http-server-handler) and [php-fig/http-server-middleware](https://github.com/php-fig/http-server-middleware)
 * PSR-17: [HTTP Factories](https://www.php-fig.org/psr/psr-17/)
-    * Standard for factories that create PSR-7 compliant HTTP objects.
+    * Standard for factories that create PSR-7 compliant HTTP objects
+    * Interfaces implemented in [php-fig/http-factory](https://github.com/php-fig/http-factory)
 * PSR-18: [HTTP Client](https://www.php-fig.org/psr/psr-18/)
-    * Interface for sending HTTP requests and receiving HTTP responses.
+    * Interface for sending HTTP requests and receiving HTTP responses
+    * Interfaces implemented in [php-fig/http-client](https://github.com/php-fig/http-client)
 * PSR-20: [Clock](https://www.php-fig.org/psr/psr-20/)
-    * Interface for reading the system clock.
+    * Interface for reading the system clock
+    * Interfaces implemented in [php-fig/clock](https://github.com/php-fig/clock)
