From 87844ba40618e841d9c0b5faa0a822ade6df68b6 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 18 Sep 2026 18:03:15 +0300 Subject: [PATCH 1/2] added summary, faq Signed-off-by: bidi --- docs/book/v7/how-to/authorization.md | 20 ++++++++++++++++ docs/book/v7/how-to/creating-fixtures.md | 20 ++++++++++++++++ docs/book/v7/how-to/creating-migrations.md | 16 +++++++++++++ docs/book/v7/how-to/csrf.md | 24 +++++++++++++++++++ docs/book/v7/how-to/dependency-injection.md | 24 +++++++++++++++++++ docs/book/v7/how-to/npm_commands.md | 24 +++++++++++++++++++ docs/book/v7/installation/composer.md | 20 ++++++++++++++++ .../v7/installation/configuration-files.md | 18 ++++++++++++++ docs/book/v7/installation/doctrine-orm.md | 24 +++++++++++++++++++ docs/book/v7/installation/getting-started.md | 14 +++++++++++ .../v7/installation/installation-intro.md | 16 +++++++++++++ docs/book/v7/installation/manage-geolite2.md | 20 ++++++++++++++++ .../v7/installation/test-the-installation.md | 24 +++++++++++++++++++ docs/book/v7/introduction/file-structure.md | 24 +++++++++++++++++++ docs/book/v7/introduction/introduction.md | 16 +++++++++++++ docs/book/v7/introduction/packages.md | 20 ++++++++++++++++ .../v7/introduction/server-requirements.md | 20 ++++++++++++++++ docs/book/v7/security/2fa-with-totp.md | 20 ++++++++++++++++ docs/book/v7/security/basic-security.md | 24 +++++++++++++++++++ .../create-book-module-via-dot-maker.md | 24 +++++++++++++++++++ docs/book/v7/tutorials/install-dot-totp.md | 24 +++++++++++++++++++ docs/book/v7/upgrading/UPGRADE-7.0.md | 16 +++++++++++++ docs/book/v7/upgrading/upgrading.md | 20 ++++++++++++++++ 23 files changed, 472 insertions(+) diff --git a/docs/book/v7/how-to/authorization.md b/docs/book/v7/how-to/authorization.md index 5ebb0a8..dd898b2 100644 --- a/docs/book/v7/how-to/authorization.md +++ b/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`. diff --git a/docs/book/v7/how-to/creating-fixtures.md b/docs/book/v7/how-to/creating-fixtures.md index 6e949e3..928f99c 100644 --- a/docs/book/v7/how-to/creating-fixtures.md +++ b/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. diff --git a/docs/book/v7/how-to/creating-migrations.md b/docs/book/v7/how-to/creating-migrations.md index 12ddb09..fe919d0 100644 --- a/docs/book/v7/how-to/creating-migrations.md +++ b/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. diff --git a/docs/book/v7/how-to/csrf.md b/docs/book/v7/how-to/csrf.md index 02376b0..3dfb7c3 100644 --- a/docs/book/v7/how-to/csrf.md +++ b/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. @@ -71,3 +77,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. diff --git a/docs/book/v7/how-to/dependency-injection.md b/docs/book/v7/how-to/dependency-injection.md index 8ad4ee5..30ebb55 100644 --- a/docs/book/v7/how-to/dependency-injection.md +++ b/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`. diff --git a/docs/book/v7/how-to/npm_commands.md b/docs/book/v7/how-to/npm_commands.md index 460a4b5..705bc54 100644 --- a/docs/book/v7/how-to/npm_commands.md +++ b/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. diff --git a/docs/book/v7/installation/composer.md b/docs/book/v7/installation/composer.md index 80272f4..77b43a8 100644 --- a/docs/book/v7/installation/composer.md +++ b/docs/book/v7/installation/composer.md @@ -1,5 +1,11 @@ # Composer Installation of Packages +## 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 +77,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. diff --git a/docs/book/v7/installation/configuration-files.md b/docs/book/v7/installation/configuration-files.md index 6237e33..f432cd8 100644 --- a/docs/book/v7/installation/configuration-files.md +++ b/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. diff --git a/docs/book/v7/installation/doctrine-orm.md b/docs/book/v7/installation/doctrine-orm.md index daf9290..cb4d9b6 100644 --- a/docs/book/v7/installation/doctrine-orm.md +++ b/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. diff --git a/docs/book/v7/installation/getting-started.md b/docs/book/v7/installation/getting-started.md index 931f1d8..21cce96 100644 --- a/docs/book/v7/installation/getting-started.md +++ b/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. diff --git a/docs/book/v7/installation/installation-intro.md b/docs/book/v7/installation/installation-intro.md index b5ddcda..d7faf6c 100644 --- a/docs/book/v7/installation/installation-intro.md +++ b/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. diff --git a/docs/book/v7/installation/manage-geolite2.md b/docs/book/v7/installation/manage-geolite2.md index b033949..591afca 100644 --- a/docs/book/v7/installation/manage-geolite2.md +++ b/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. diff --git a/docs/book/v7/installation/test-the-installation.md b/docs/book/v7/installation/test-the-installation.md index 9d2afad..56ad245 100644 --- a/docs/book/v7/installation/test-the-installation.md +++ b/docs/book/v7/installation/test-the-installation.md @@ -1,5 +1,11 @@ # Running the application +## Summary + +This page explains how to run the application in WSL, troubleshoot common startup issues, and locate the default admin credentials created by the fixtures. + +## Details + > **Do not enable dev mode in production** We recommend running your applications in WSL: @@ -43,3 +49,21 @@ return [ ``` > Do not change this in `local.php.dist` as well because this value should remain `true` on production. + +## FAQ + +**Q: What are the default admin credentials after running the fixtures?** + +A: **User**: `admin`, **Password**: `dotadmin`. Make sure to change these before going to production. + +**Q: What should I do if I get a server error 500?** + +A: Check the folder permissions; see the linked common permission issues FAQ for guidance. + +**Q: What should I do if I get exceptions about missing services?** + +A: Run `sudo php ./bin/clear-config-cache.php` to clear the config cache. + +**Q: Why doesn't `session.cookie_secure` work locally?** + +A: It does not work in local development, so you must set it to `false` in `local.php` (never in `local.php.dist`, since it must remain `true` in production). diff --git a/docs/book/v7/introduction/file-structure.md b/docs/book/v7/introduction/file-structure.md index 7f78872..aa43150 100644 --- a/docs/book/v7/introduction/file-structure.md +++ b/docs/book/v7/introduction/file-structure.md @@ -1,5 +1,11 @@ # File structure +## Summary + +This page describes the default folder and file layout of Dotkernel Admin, including the purpose of `bin`, `config`, `data`, `log`, `public` and `src`, along with the Core module's submodule structure. + +## Details + Dotkernel Admin follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standards. It is considered good practice to standardize the file structure of projects. @@ -138,3 +144,21 @@ Each submodule folder should contain: 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 `DBAL`, `Enum`, `Command`, `Factory` etc. + +## FAQ + +**Q: What standard does Dotkernel Admin's file structure follow?** + +A: It follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standard. + +**Q: Where do application configuration files live?** + +A: In the `config` folder, with service-related local and global config files under `config/autoload`. + +**Q: What does each Module folder typically contain?** + +A: Folders such as `src/Handler`, `src/InputFilter` and `src/Service`, plus a `ConfigProvider.php` and a `RoutesDelegator.php`. + +**Q: What is the Core module used for?** + +A: It is a common codebase shared across the applications in your project, containing submodules such as `Admin`, `App`, `Security`, `Setting` and `User`, each typically with `src/Entity`, `src/Repository` and a `ConfigProvider.php`. diff --git a/docs/book/v7/introduction/introduction.md b/docs/book/v7/introduction/introduction.md index e3f69c9..15039b3 100644 --- a/docs/book/v7/introduction/introduction.md +++ b/docs/book/v7/introduction/introduction.md @@ -1,5 +1,11 @@ # Introduction +## Summary + +This page introduces Dotkernel Admin as a skeleton application for building administration sites, and points to a live demo. + +## Details + Dotkernel Admin is an application (skeleton) intended for quickly setting up an administration site for your platform. It's a fast and reliable way to manage records in your database with a simple table-based approach, and also to build reports and graphs to monitor your platform. The many graphical components at your disposal ensure an intuitive user experience. @@ -7,3 +13,13 @@ The many graphical components at your disposal ensure an intuitive user experien > Check out our [demo](https://admin7.dotkernel.net/). > > Submit user `admin` and password `dotadmin` to authenticate yourself. + +## FAQ + +**Q: What is Dotkernel Admin?** + +A: It's an application (skeleton) intended for quickly setting up an administration site for your platform, with a simple table-based approach to managing database records and building reports and graphs. + +**Q: How can I try Dotkernel Admin before installing it?** + +A: Visit the [demo](https://admin7.dotkernel.net/) and log in with user `admin` and password `dotadmin`. diff --git a/docs/book/v7/introduction/packages.md b/docs/book/v7/introduction/packages.md index e7810ca..454f255 100644 --- a/docs/book/v7/introduction/packages.md +++ b/docs/book/v7/introduction/packages.md @@ -1,5 +1,11 @@ # Packages +## Summary + +This page lists the main Composer packages Dotkernel Admin depends on, covering Doctrine, Dotkernel, Laminas and Mezzio components. + +## Details + * `doctrine/dbal`:`^4.4` - Powerful PHP database abstraction layer (DBAL) with many features for database schema introspection and management. * `doctrine/orm`:`^3.6` - Object-Relational-Mapper for PHP * `dotkernel/dot-authorization`:`^3.8` - Authorization base package defining interfaces for authorization services to be used with Dotkernel applications @@ -35,3 +41,17 @@ * `ramsey/uuid-doctrine`:`^2.1` - Use ramsey/uuid as a Doctrine field type * `roave/psr-container-doctrine`:`^6.1` - Doctrine Factories for PSR-11 Containers * `symfony/filesystem`:`^8.0` - Provides basic utilities for the filesystem + +## FAQ + +**Q: What ORM does Dotkernel Admin use?** + +A: `doctrine/orm`, together with `doctrine/dbal` for database schema introspection and management. + +**Q: Which framework underpins Dotkernel Admin?** + +A: `mezzio/mezzio`, a PSR-15 middleware microframework, along with several Mezzio and Laminas components. + +**Q: Which Dotkernel packages handle authorization?** + +A: `dotkernel/dot-authorization` and `dotkernel/dot-rbac-guard` define and enforce role-based access to the application. diff --git a/docs/book/v7/introduction/server-requirements.md b/docs/book/v7/introduction/server-requirements.md index 0304cfb..90e9e59 100644 --- a/docs/book/v7/introduction/server-requirements.md +++ b/docs/book/v7/introduction/server-requirements.md @@ -1,5 +1,11 @@ # Server Requirements +## Summary + +This page lists the recommended webserver, PHP version, required settings, supported RDBMS engines and recommended PHP extensions for running Dotkernel Admin. + +## Details + For production, we highly recommend a *nix based system. ## Webserver @@ -44,3 +50,17 @@ Both mod_php and FCGI (FPM) are supported. * `zlib`, `zip`, `bz2` - if compressing files * `curl` (required if APIs are used) * `sqlite3` - for tests + +## FAQ + +**Q: What is the minimum required PHP version?** + +A: PHP 8.2 or above, supported through either mod_php or FCGI (FPM). + +**Q: Which databases are supported?** + +A: MariaDB (10.7, 10.11 LTS, 11.4 LTS, 11.8 LTS) and PostgreSQL (13 and above); MySQL is not supported because it lacks UUID support. + +**Q: What webserver modules are required?** + +A: On Apache, `mod_rewrite` and `.htaccess` support (`AllowOverride All`); on Nginx, the provided `.htaccess` file must be converted into Nginx configuration instructions. diff --git a/docs/book/v7/security/2fa-with-totp.md b/docs/book/v7/security/2fa-with-totp.md index 7b54fa4..fb21073 100644 --- a/docs/book/v7/security/2fa-with-totp.md +++ b/docs/book/v7/security/2fa-with-totp.md @@ -1,5 +1,11 @@ # Time-based One-Time Password (TOTP) +## Summary + +This page explains what TOTP is, how the 2FA flow works in Dotkernel Admin via [dot-totp](https://github.com/dotkernel/dot-totp), and where to go next to install it. + +## Details + A **Time-based One-Time Password (TOTP)** is a security algorithm used as part of **two-factor authentication (2FA)** to protect against account attacks. The mechanism is integrated into [dot-totp](https://github.com/dotkernel/dot-totp) to enhance security by requiring both a **password** and **an additional one-time code**. @@ -14,3 +20,17 @@ Below is a simplified flow for the 2FA with a TOTP mechanism. ## Next Steps [Install 2FA with dot-totp](https://docs.dotkernel.org/admin-documentation/v7/tutorials/install-dot-totp/). + +## FAQ + +**Q: What is a Time-based One-Time Password (TOTP)?** + +A: It's a security algorithm used as part of two-factor authentication (2FA) that generates temporary, unique 6-digit codes changing every 30 seconds, to protect against account attacks. + +**Q: What does TOTP add on top of a password?** + +A: It requires an additional one-time code generated by an Authenticator app, in addition to the regular password. + +**Q: Where do I go to install TOTP in Dotkernel Admin?** + +A: See [Install 2FA with dot-totp](https://docs.dotkernel.org/admin-documentation/v7/tutorials/install-dot-totp/). diff --git a/docs/book/v7/security/basic-security.md b/docs/book/v7/security/basic-security.md index d0b8813..e9322c3 100644 --- a/docs/book/v7/security/basic-security.md +++ b/docs/book/v7/security/basic-security.md @@ -1,5 +1,11 @@ # Basic Security +## Summary + +This page covers the security tools Dotkernel Admin ships with, including form validation, CSRF protection, RBAC, session and cookie settings, demo credentials, dependency management, and general production considerations. + +## Details + Dotkernel Admin provides all necessary tools to implement safe applications; however, you will need to manually make use of some of them. This section will go over the provided tools and any steps you need to follow to use them successfully, as well as a few general considerations. @@ -69,3 +75,21 @@ composer development-status if you are using a public repository, consider keeping it in your custom applications to ensure code quality. > Read more about using [Laminas Continuous Integration](https://getlaminas.org/blog/2024-08-05-using-laminas-continuous-integration.html). + +## FAQ + +**Q: Does Dotkernel Admin protect forms against CSRF attacks by default?** + +A: Yes, all shipped forms use CSRF token creation and validation; you must implement this yourself for any new forms you create. + +**Q: How is access control handled?** + +A: Through [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) and [dot-rbac](https://github.com/dotkernel/dot-rbac); update their configuration whenever you add new routes or roles. + +**Q: What should I do about the demo admin account before going live?** + +A: Make sure to change or remove the demo account, since it ships with a public identity and password. + +**Q: Where should sensitive data like API keys be stored?** + +A: In `*.local.php` configuration files, which are ignored by VCS by default; never put sensitive data in `*.global.php` or `*.php.dist` files. diff --git a/docs/book/v7/tutorials/create-book-module-via-dot-maker.md b/docs/book/v7/tutorials/create-book-module-via-dot-maker.md index 457dab0..5a294fd 100644 --- a/docs/book/v7/tutorials/create-book-module-via-dot-maker.md +++ b/docs/book/v7/tutorials/create-book-module-via-dot-maker.md @@ -1,5 +1,11 @@ # Implementing a book module in Dotkernel Admin using DotMaker +## Summary + +This tutorial uses `dotkernel/dot-maker` to scaffold a complete `Book` module in Dotkernel Admin, from folder structure and file contents to migrations, authorization and route verification. + +## Details + The `dotkernel/dot-maker` library can be used to programmatically generate project files and directories. It can be added to your Admin installation by following the [official documentation](https://docs.dotkernel.org/dot-maker/). @@ -965,4 +971,22 @@ The module should now be accessible via the `Book` section of the `Admin` main m New book entities can be added via the new "Create book" modal accessible from the `+` button on the management page. +## FAQ + +**Q: What tool generates the files for the book module?** + +A: The `dotkernel/dot-maker` library, which programmatically generates project files and directories. + +**Q: How do I create the database table for the new `Book` entity?** + +A: Generate a migration by running `php ./vendor/bin/doctrine-migrations diff`, then apply it with `php ./vendor/bin/doctrine-migrations migrate`. + +**Q: How do I make the new endpoints accessible?** + +A: Configure access to them by appending the new routes to the `guards.options.rules` key in `config/autoload/authorization-guards.global.php`. + +**Q: How do I verify the module works after implementing it?** + +A: Check that the `Book` section appears in the `Admin` main menu, linking to `/list-book`, and that new book entities can be added via the "Create book" modal. + Once selected with the checkbox, existing entries can be edited via the `-` button , or deleted via the "trash" icon. diff --git a/docs/book/v7/tutorials/install-dot-totp.md b/docs/book/v7/tutorials/install-dot-totp.md index ff2ce4e..1ee2179 100644 --- a/docs/book/v7/tutorials/install-dot-totp.md +++ b/docs/book/v7/tutorials/install-dot-totp.md @@ -1,5 +1,11 @@ # Installing dot-totp into Dotkernel Admin +## Summary + +This tutorial walks through installing the `dot-totp` package, adding the required files, wiring routes and configuration, and activating 2FA on an admin account. + +## Details + If you haven't already, install [Dotkernel Admin](https://github.com/dotkernel/admin). > The installation steps listed below should work similarly in any middleware-based application. @@ -89,3 +95,21 @@ Alternatively, you can submit a recovery code. That's it! You are now logged in securely. + +## FAQ + +**Q: How do I add `dot-totp` to my project?** + +A: Run `composer require dotkernel/dot-totp`, then add the files listed in this tutorial, following the Dotkernel file structure. + +**Q: What do I need to migrate after adding the `TotpTrait`?** + +A: Migrate the new columns `totpSecret`, `totp_enabled` and `recovery_codes` in the entity that uses the trait. + +**Q: How does a user activate 2FA on their account?** + +A: They click 'Enable TOTP' from their profile, scan the QR code with an Authenticator app, and enter the 6-digit code it generates. + +**Q: What happens if a user loses access to their Authenticator app?** + +A: They can log in using one of the recovery codes generated during activation; each recovery code is usable only once. diff --git a/docs/book/v7/upgrading/UPGRADE-7.0.md b/docs/book/v7/upgrading/UPGRADE-7.0.md index ecc174a..efde743 100644 --- a/docs/book/v7/upgrading/UPGRADE-7.0.md +++ b/docs/book/v7/upgrading/UPGRADE-7.0.md @@ -1,8 +1,24 @@ # Upgrading from 6.x to 7.0 +## Summary + +This page lists the notable pull requests that make up the 6.x to 7.0 upgrade of Dotkernel Admin. + +## Details + > You can find a complete list in [Changelog](https://github.com/dotkernel/admin/blob/7.0/CHANGELOG.md) * Bumped dependencies https://github.com/dotkernel/admin/pull/401 * Core Sync and update codebase https://github.com/dotkernel/admin/pull/403 * Updated readme, oss https://github.com/dotkernel/admin/pull/397 * Core sync https://github.com/dotkernel/admin/pull/398 + +## FAQ + +**Q: Where can I find the complete list of changes for the 7.0 upgrade?** + +A: In the [Changelog](https://github.com/dotkernel/admin/blob/7.0/CHANGELOG.md). + +**Q: What kind of changes were included in the 6.x to 7.0 upgrade?** + +A: Dependency bumps, Core sync and codebase updates, and readme/OSS updates, tracked via their respective pull requests. diff --git a/docs/book/v7/upgrading/upgrading.md b/docs/book/v7/upgrading/upgrading.md index 23901af..d5726b1 100644 --- a/docs/book/v7/upgrading/upgrading.md +++ b/docs/book/v7/upgrading/upgrading.md @@ -1,5 +1,11 @@ # Upgrades +## Summary + +This page explains that Dotkernel Admin has no automatic upgrade path, and describes the manual procedure for tracking and applying releases. + +## Details + Dotkernel Admin does not provide an automatic upgrade path. Instead, the recommended procedure is to manually implement each modification listed in [releases](https://github.com/dotkernel/admin/releases). Additionally, release info can also be accessed as an [RSS](https://github.com/dotkernel/admin/releases.atom) feed. @@ -17,3 +23,17 @@ This allows you to track your Admin's version and keep your project up to date w ## Version to version upgrading Starting from [version 6.2](UPGRADE-7.0.md) the upgrading procedure is detailed version to version. + +## FAQ + +**Q: Does Dotkernel Admin provide an automatic upgrade path?** + +A: No, upgrades must be implemented manually by following the modifications listed in each [release](https://github.com/dotkernel/admin/releases). + +**Q: How do I track which version of Dotkernel Admin I'm on?** + +A: Use the `CHANGELOG.md` file created when you clone the project, and keep it updated by copying each release's info into it. + +**Q: Where can I find version-to-version upgrade details?** + +A: Starting from [version 6.2](UPGRADE-7.0.md), the upgrading procedure is documented version to version. From 918c2266ece21a539f9af44c06d46ec8fb41bd6a Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 18 Sep 2026 18:07:11 +0300 Subject: [PATCH 2/2] linting fixes Signed-off-by: bidi --- docs/book/v7/how-to/csrf.md | 3 ++- docs/book/v7/installation/composer.md | 3 ++- docs/book/v7/installation/test-the-installation.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/book/v7/how-to/csrf.md b/docs/book/v7/how-to/csrf.md index 3dfb7c3..be6f5a4 100644 --- a/docs/book/v7/how-to/csrf.md +++ b/docs/book/v7/how-to/csrf.md @@ -60,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. diff --git a/docs/book/v7/installation/composer.md b/docs/book/v7/installation/composer.md index 77b43a8..56611ec 100644 --- a/docs/book/v7/installation/composer.md +++ b/docs/book/v7/installation/composer.md @@ -6,7 +6,8 @@ This page walks through installing Composer dependencies, answering the setup sc ## Details -Composer is required to install Dotkernel Admin. You can install Composer from the [official site](https://getcomposer.org/). +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. diff --git a/docs/book/v7/installation/test-the-installation.md b/docs/book/v7/installation/test-the-installation.md index 56ad245..bba92b0 100644 --- a/docs/book/v7/installation/test-the-installation.md +++ b/docs/book/v7/installation/test-the-installation.md @@ -54,7 +54,8 @@ return [ **Q: What are the default admin credentials after running the fixtures?** -A: **User**: `admin`, **Password**: `dotadmin`. Make sure to change these before going to production. +A: **User**: `admin`, **Password**: `dotadmin`. +Make sure to change these before going to production. **Q: What should I do if I get a server error 500?**