Overhaul

docs/book/v7/how-to/authorization.md

@@ -1,5 +1,11 @@
 # Authorization Guards
 
+## Summary
+
+This guide explains how [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) and [dot-rbac](https://github.com/dotkernel/dot-rbac) restrict access to parts of Dotkernel Admin, and how the `authorization.global.php` and `authorization-guards.global.php` files define roles, permissions and route-level access rules.
+
+## Details
+
 The packages responsible for restricting access to certain parts of the application are [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) and [dot-rbac](https://github.com/dotkernel/dot-rbac).
 These packages work together to create an infrastructure that is customizable and diversified to manage user access to the platform by specifying the type of role the user has.
 
@@ -41,3 +47,17 @@ These permissions must first be declared in the `authorization.global.php` (dot-
         'admin::admin-edit'              => ['authenticated'],
     ]
 ```
+
+## FAQ
+
+**Q: Which packages handle authorization in Dotkernel Admin?**
+
+A: `dot-rbac-guard` and `dot-rbac` work together to restrict access to parts of the application based on the user's role.
+
+**Q: Where are roles and their permissions defined?**
+
+A: Roles and the permissions they grant are defined in the `authorization.global.php` configuration file.
+
+**Q: Where do I configure which permissions a route requires?**
+
+A: Route-level access is configured in `authorization-guards.global.php`, using permissions that are already declared in `authorization.global.php`.

docs/book/v7/how-to/creating-fixtures.md

@@ -1,5 +1,11 @@
 # Fixtures
 
+## Summary
+
+This page explains how to seed the database with initial values using `dotkernel/dot-data-fixtures`, and how to list or execute fixtures with the Doctrine CLI command.
+
+## Details
+
 > Fixtures are used to seed the database with initial values and should only be executed ONCE each, after migrating the database.
 
 Seeding the database is done with the help of our custom package `dotkernel/dot-data-fixtures` built on top of `doctrine/data-fixtures`.
@@ -30,3 +36,17 @@ php ./bin/doctrine fixtures:execute --class=AdminLoader
 Fixtures can and should be ordered to ensure database consistency.
 More on ordering fixtures can be found here:
 https://www.doctrine-project.org/projects/doctrine-data-fixtures/en/latest/how-to/fixture-ordering.html#fixture-ordering
+
+## FAQ
+
+**Q: How many times should a fixture be executed?**
+
+A: Each fixture should only be executed ONCE, and only after the database has been migrated.
+
+**Q: How do I see which fixtures are available?**
+
+A: Run `php ./bin/doctrine fixtures:list` to list all available fixtures in their order of execution.
+
+**Q: Can I execute a single fixture instead of all of them?**
+
+A: Yes, run `php ./bin/doctrine fixtures:execute --class=AdminLoader`, replacing `AdminLoader` with the class name of the fixture you want to run.

docs/book/v7/how-to/creating-migrations.md

@@ -1,5 +1,11 @@
 # Creating migrations
 
+## Summary
+
+This page explains how to generate a new database migration file and how to add schema changes to its `up` and `down` methods.
+
+## Details
+
 Migrations are used to create and/or edit the database structure.
 To generate a new migration file, use this command:
 
@@ -27,3 +33,13 @@ And its opposite in `public function down`:
 ```shell
 $this->addSql('ALTER TABLE admin DROP test');
 ```
+
+## FAQ
+
+**Q: How do I generate a new migration file?**
+
+A: Run `php ./vendor/bin/doctrine-migrations migrations:generate`, which creates a new PHP file under `src/Core/src/App/src/Migration/`.
+
+**Q: What is the difference between `up` and `down`?**
+
+A: The `up` method contains the queries that are executed when the migration runs, and the `down` method contains the optional queries that undo those changes.

docs/book/v7/how-to/csrf.md

@@ -1,5 +1,11 @@
 # CSRF protection in forms
 
+## Summary
+
+This page explains how to add CSRF protection to a form by creating a CSRF field, validating it in the InputFilter, rendering it in the template, and testing the result.
+
+## Details
+
 A Cross-Site Request Forgery (CSRF) attack is a type of security vulnerability that tricks a user into performing actions on a web application in which they are authenticated, without their knowledge or consent.
 
 Web applications can protect users against these types of attacks by implementing CSRF tokens in their forms, which are known only to the application that generated them and must be included when submitting forms.
@@ -54,7 +60,8 @@ Open the template that renders your form and add the following code somewhere be
 
 ## Test the implementation
 
-Access your form from the browser and view its source. You should see a new hidden field, called `exampleCsrf` (or however you named it).
+Access your form from the browser and view its source.
+You should see a new hidden field, called `exampleCsrf` (or however you named it).
 After filling out the form, submitting it should work as before.
 
 To make sure that the new CSRF field works as expected, you can inspect the form using your browser's `Developer tools` and modify its value in any way.
@@ -71,3 +78,21 @@ Submitting a form that has been rendered for longer than this value will result
 > Invalid CSRF.
 
 You can modify the value of `timeout` in each form, but the default value should work in most cases.
+
+## FAQ
+
+**Q: What is a CSRF token used for?**
+
+A: It protects users against Cross-Site Request Forgery attacks by ensuring that a form submission was generated by the application itself and not forged by an attacker.
+
+**Q: What steps are required to implement CSRF protection?**
+
+A: You need to create the CSRF field in the form, validate it in the InputFilter, and render it in the template between the form's opening and closing tags.
+
+**Q: What happens if the CSRF token is missing or invalid?**
+
+A: The form submission fails validation, showing an error such as "This field is required and cannot be empty" or "Invalid CSRF."
+
+**Q: How long is a CSRF token valid?**
+
+A: By default, a token is valid for **3600** seconds, controlled by the `timeout` option, which you can adjust per form.

docs/book/v7/how-to/dependency-injection.md

@@ -1,5 +1,11 @@
 # Dependency Injection
 
+## Summary
+
+This page explains how Dotkernel Admin uses the `dot-dependency-injection` package to perform constructor injection via the `#[Inject]` attribute, and how to register a class in the `ConfigProvider` so its dependencies are resolved.
+
+## Details
+
 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.
 
@@ -53,3 +59,21 @@ When your object is instantiated from the container, it will automatically have
 
 > Dependencies injection is available to any object within Dotkernel Admin.
 > For example, you can inject dependencies in a service, a handler and so on, simply by registering them in the `ConfigProvider`.
+
+## FAQ
+
+**Q: Which type of dependency injection does Dotkernel Admin support?**
+
+A: Through the `dot-dependency-injection` package, Dotkernel Admin focuses only on constructor injection.
+
+**Q: How does `dot-dependency-injection` know which dependencies to inject?**
+
+A: It reads the `#[Inject]` attribute added to a class's constructor, where each dependency is listed as a separate parameter.
+
+**Q: How do I register a class so its dependencies get resolved?**
+
+A: Register the class under `factories` in the module's `ConfigProvider`, using `Dot\DependencyInjection\Factory\AttributedServiceFactory::class`.
+
+**Q: Can I inject a configuration value instead of a service?**
+
+A: Yes, specify the configuration key path using dot notation, for example `config.example`.

docs/book/v7/how-to/npm_commands.md

@@ -1,5 +1,11 @@
 # NPM Commands
 
+## Summary
+
+This page lists the NPM commands used to install front-end dependencies, watch assets for changes, and build production-ready assets.
+
+## Details
+
 To install dependencies into the `node_modules` directory run this command.
 
 ```shell
@@ -20,3 +26,21 @@ After all updates are done, this command compiles the assets locally, minifies t
 ```shell
 npm run prod
 ```
+
+## FAQ
+
+**Q: How do I install front-end dependencies?**
+
+A: Run `npm install` to install dependencies into the `node_modules` directory.
+
+**Q: What should I do if `npm install` fails?**
+
+A: This is usually caused by npm user permissions; the recommended fix is to install npm through `Node Version Manager`.
+
+**Q: How do I get assets to recompile automatically while developing?**
+
+A: Run `npm run watch`, which compiles the components and then monitors files for changes, recompiling them as needed.
+
+**Q: How do I prepare assets for production?**
+
+A: Run `npm run prod` to compile and minify the assets locally, making them ready for production.

docs/book/v7/installation/composer.md

@@ -1,6 +1,13 @@
 # Composer Installation of Packages
 
-Composer is required to install Dotkernel Admin. You can install Composer from the [official site](https://getcomposer.org/).
+## Summary
+
+This page walks through installing Composer dependencies, answering the setup script's configuration prompts, and enabling or disabling development mode.
+
+## Details
+
+Composer is required to install Dotkernel Admin.
+You can install Composer from the [official site](https://getcomposer.org/).
 
 > First, make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
 
@@ -71,3 +78,17 @@ You can check if you have development mode enabled by running:
 ```shell
 composer development-status
 ```
+
+## FAQ
+
+**Q: How do I install the project's PHP dependencies?**
+
+A: Run `composer install` from the command line, using the CLI to ensure interactivity for proper configuration.
+
+**Q: Why should I select `[0] Do not inject` during setup?**
+
+A: Dotkernel includes its own `ConfigProvider`, which already contains the prompted configurations, so injecting an extra one is unnecessary.
+
+**Q: How do I check whether development mode is enabled?**
+
+A: Run `composer development-status`; use `composer development-enable` or `composer development-disable` to toggle it.

docs/book/v7/installation/configuration-files.md

@@ -1,5 +1,9 @@
 # Configuration Files
 
+## Summary
+
+This page explains which configuration keys to fill in for the application to send mail, including the `from` address and optional CC recipients.
+
 ## Mail
 
 > If you intend to send emails from your Frontend, make sure to fill in SMTP connection params.
@@ -17,3 +21,17 @@ Under `message_options` key:
 > **Please add at least one email address in order for a contact message to reach someone**
 
 Also feel free to add as many CCs as you require under the `dot_mail` => `default` => `message_options` => `cc` key.
+
+## FAQ
+
+**Q: Where do I configure mail credentials for the application?**
+
+A: Add valid credentials to `config/autoload/mail.global.php`, filling in the `from` and `from_name` keys under `message_options`.
+
+**Q: How do I set up an in-memory database for tests?**
+
+A: Duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`; this is optional and only needed to run or create tests.
+
+**Q: Can I add multiple CC recipients for outgoing mail?**
+
+A: Yes, add as many as you require under the `dot_mail` => `default` => `message_options` => `cc` key.

docs/book/v7/installation/doctrine-orm.md

@@ -1,5 +1,11 @@
 # Doctrine ORM
 
+## Summary
+
+This page covers setting up the database connection, creating and running migrations, and executing fixtures to populate the admin tables.
+
+## Details
+
 This step saves the database connection credentials in an Admin configuration file.
 We do not cover the creation steps of the database itself.
 
@@ -115,3 +121,21 @@ Fixtures have been loaded.
     ' <' `\ ._/'\
        `   \     \
 ```
+
+## FAQ
+
+**Q: Which database engines are supported?**
+
+A: You can create a **MariaDB** or **PostgreSQL** database, and its collation should be set to `utf8mb4_general_ci`.
+
+**Q: Where do I put my database connection credentials?**
+
+A: Fill them out in `config/autoload/local.php`, under `$databases['mariadb']` (or `$databases['postgresql']` if using PostgreSQL).
+
+**Q: How do I create and run a migration?**
+
+A: Run `php ./vendor/bin/doctrine-migrations diff` to generate the migration file, then `php ./vendor/bin/doctrine-migrations migrate` to apply it.
+
+**Q: How do I populate the admin tables with default data?**
+
+A: Run `php ./bin/doctrine fixtures:execute` to load the fixtures.

docs/book/v7/installation/getting-started.md

@@ -1,5 +1,9 @@
 # Clone the project
 
+## Summary
+
+This page explains how to clone the Dotkernel Admin repository into an empty directory and verify that the files were downloaded correctly.
+
 ## Recommended development environment
 
 > If you are using Windows on your machine, you can use WSL2 as a development environment.
@@ -26,3 +30,13 @@ Resolving deltas: 100% (3359/3359), done.
 ```
 
 You can already open the project in your preferred IDE to double-check the files were copied correctly.
+
+## FAQ
+
+**Q: What command do I use to clone Dotkernel Admin?**
+
+A: Run `git clone https://github.com/dotkernel/admin.git .` inside an empty directory.
+
+**Q: What development environment is recommended on Windows?**
+
+A: Use WSL2, following the guide linked in this page's "Recommended development environment" section.

docs/book/v7/installation/installation-intro.md

@@ -1,5 +1,11 @@
 # Introduction
 
+## Summary
+
+This page introduces the installation tutorial, outlining the tasks covered on the way to a fully functional Dotkernel Admin installation.
+
+## Details
+
 In this tutorial, we will install Dotkernel Admin from scratch.
 We will focus on these tasks:
 
@@ -9,3 +15,13 @@ We will focus on these tasks:
 - Run the project.
 
 By the end of this tutorial you will have a fully functional Dotkernel Admin on your selected environment and can begin coding.
+
+## FAQ
+
+**Q: What does this installation tutorial cover?**
+
+A: It highlights the required third-party tools, provides installation commands with expected responses, configures the development environment, and runs the project.
+
+**Q: What can I expect once I finish the tutorial?**
+
+A: A fully functional Dotkernel Admin installation on your selected environment, ready for you to begin coding.

docs/book/v7/installation/manage-geolite2.md

@@ -1,5 +1,11 @@
 # Manage the GeoLite2 databases
 
+## Summary
+
+This page explains how to download or update GeoLite2 databases individually or all at once, and how to get help for the synchronizer command.
+
+## Details
+
 You can download/update a specific GeoLite2 database, by running the following command where `{DATABASE}` can be `asn`, `city`, `country`:
 
 ```shell
@@ -29,3 +35,17 @@ php ./bin/cli.php help geoip:synchronize
 ```
 
 > If you set up the synchronizer command as a cronjob, you can add the `-q|--quiet` option, and it will output data only if an error has occurred.
+
+## FAQ
+
+**Q: How do I update a single GeoLite2 database?**
+
+A: Run `php ./bin/cli.php geoip:synchronize -d {DATABASE}`, replacing `{DATABASE}` with `asn`, `city` or `country`.
+
+**Q: How do I update all GeoLite2 databases at once?**
+
+A: Run `php ./bin/cli.php geoip:synchronize` without the `-d` option.
+
+**Q: How do I reduce command output when running the synchronizer as a cronjob?**
+
+A: Add the `-q|--quiet` option so it only outputs data when an error occurs.