From ee200f662ad24f55931f0527b9fcdda40d9f4479 Mon Sep 17 00:00:00 2001 From: nati Date: Tue, 8 Jul 2025 15:26:25 +0300 Subject: [PATCH 1/8] Added documentation for v6 of admin Signed-off-by: nati --- docs/book/v6/how-to/authorization.md | 42 ++++++ docs/book/v6/how-to/creating-fixtures.md | 32 +++++ docs/book/v6/how-to/creating-migrations.md | 29 +++++ docs/book/v6/how-to/csrf.md | 79 +++++++++++ docs/book/v6/how-to/dependency-injection.md | 56 ++++++++ docs/book/v6/how-to/npm_commands.md | 22 ++++ docs/book/v6/installation/composer.md | 71 ++++++++++ .../v6/installation/configuration-files.md | 27 ++++ docs/book/v6/installation/doctrine-orm.md | 89 +++++++++++++ docs/book/v6/installation/getting-started.md | 28 ++++ .../v6/installation/installation-intro.md | 11 ++ docs/book/v6/installation/manage-geolite2.md | 31 +++++ .../v6/installation/test-the-installation.md | 43 ++++++ docs/book/v6/introduction/file-structure.md | 123 ++++++++++++++++++ docs/book/v6/introduction/introduction.md | 9 ++ docs/book/v6/introduction/packages.md | 27 ++++ .../v6/introduction/server-requirements.md | 50 +++++++ 17 files changed, 769 insertions(+) create mode 100644 docs/book/v6/how-to/authorization.md create mode 100644 docs/book/v6/how-to/creating-fixtures.md create mode 100644 docs/book/v6/how-to/creating-migrations.md create mode 100644 docs/book/v6/how-to/csrf.md create mode 100644 docs/book/v6/how-to/dependency-injection.md create mode 100644 docs/book/v6/how-to/npm_commands.md create mode 100644 docs/book/v6/installation/composer.md create mode 100644 docs/book/v6/installation/configuration-files.md create mode 100644 docs/book/v6/installation/doctrine-orm.md create mode 100644 docs/book/v6/installation/getting-started.md create mode 100644 docs/book/v6/installation/installation-intro.md create mode 100644 docs/book/v6/installation/manage-geolite2.md create mode 100644 docs/book/v6/installation/test-the-installation.md create mode 100644 docs/book/v6/introduction/file-structure.md create mode 100644 docs/book/v6/introduction/introduction.md create mode 100644 docs/book/v6/introduction/packages.md create mode 100644 docs/book/v6/introduction/server-requirements.md diff --git a/docs/book/v6/how-to/authorization.md b/docs/book/v6/how-to/authorization.md new file mode 100644 index 0000000..626a984 --- /dev/null +++ b/docs/book/v6/how-to/authorization.md @@ -0,0 +1,42 @@ +# Authorization Guards + +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. + +The `authorization.global.php` file provides multiple configurations specifying multiple roles as well as the types of permissions to which these roles have access. + +```php +//example of a flat RBAC model that specifies two types of roles as well as their permission + 'roles' => [ + 'admin' => [ + 'permissions' => [ + 'authenticated', + 'edit', + 'delete', + //etc.. + ] + ], + 'user' => [ + 'permissions' => [ + 'authenticated', + //etc.. + ] + ] + ] +``` + +The `authorization-guards.global.php` file defines which permissions are required to access specific route handlers. These permissions must first be declared in the authorization.global.php (dot-rbac) configuration file. + +```php +// Example configuration granting access to route handlers based on permissions. + 'rules' => [ + 'admin::admin-login-form' => [], + 'admin::admin-login' => [], + 'admin::admin-create-form' => ['authenticated'], + 'admin::admin-create' => ['authenticated'], + 'admin::admin-delete-form' => ['authenticated'], + 'admin::admin-delete' => ['authenticated'], + 'admin::admin-edit-form' => ['authenticated'], + 'admin::admin-edit' => ['authenticated'], + ] +``` diff --git a/docs/book/v6/how-to/creating-fixtures.md b/docs/book/v6/how-to/creating-fixtures.md new file mode 100644 index 0000000..2f5057e --- /dev/null +++ b/docs/book/v6/how-to/creating-fixtures.md @@ -0,0 +1,32 @@ +# Fixtures + +> 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`. +See below on how to use our CLI command for listing and executing Doctrine data fixtures. + +## Working with fixtures + +You can find an example of a fixtures class in `src/Core/src/App/src/Fixture/AdminLoader.php`. + +To list all the available fixtures by order of execution run: + +```shell +php bin/doctrine fixtures:list +``` + +To execute all fixtures run: + +```shell +php bin/doctrine fixtures:execute +``` + +To execute a specific fixture, use its class name, like in this example: + +```shell +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 diff --git a/docs/book/v6/how-to/creating-migrations.md b/docs/book/v6/how-to/creating-migrations.md new file mode 100644 index 0000000..cfc3407 --- /dev/null +++ b/docs/book/v6/how-to/creating-migrations.md @@ -0,0 +1,29 @@ +# Creating migrations + +Migrations are used to create and/or edit the database structure. +To generate a new migration file, use this command: + +```shell +php vendor/bin/doctrine-migrations migrations:generate +``` + +It creates a PHP file like this one `src/Core/src/App/src/Migration/Version20240627134952.php` that can then be edited in the IDE. +You can add new queries in: + +- `public function up` - these are executed when the migration is run. +- `public function down` - these are optional queries that undo the above changes. + +## Example + +This example creates a new column named `test`. +Add this in `public function up`: + +```shell +$this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL'); +``` + +And its opposite in `public function down`: + +```shell +$this->addSql('ALTER TABLE admin DROP test'); +``` diff --git a/docs/book/v6/how-to/csrf.md b/docs/book/v6/how-to/csrf.md new file mode 100644 index 0000000..78c0343 --- /dev/null +++ b/docs/book/v6/how-to/csrf.md @@ -0,0 +1,79 @@ +# CSRF protection in forms + +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. With each visit, a new +CSRF token is added to the form so tokens are not reusable between forms. Missing to provide a valid CSRF token will +result in a form validation error. + +## Implement CSRF protection + +Implementing CSRF protection requires three steps: + +- create new field using [laminas/laminas-form](https://github.com/laminas/laminas-form)'s [CSRF](https://github.com/laminas/laminas-form/blob/3.21.x/src/Element/Csrf.php) element +- validate new field using [laminas/laminas-session](https://github.com/laminas/laminas-session)'s +[CSRF](https://github.com/laminas/laminas-session/blob/2.22.x/src/Validator/Csrf.php) validator +- render field using [laminas/laminas-form](https://github.com/laminas/laminas-form)'s [FormElement](https://github.com/laminas/laminas-form/blob/3.21.x/src/View/Helper/FormElement.php) helper + +### Create field + +Open the form's PHP class and append the following code to the method that initializes the fields (usually `init`): + +```php +$this->add( + (new Csrf('exampleCsrf')) + ->setOptions([ + 'csrf_options' => ['timeout' => 3600, 'session' => new Container()], + ]) + ->setAttribute('required', true) +); +``` + +where `exampleCsrf` should be a suggestive name that describes the purpose of the field (example: `forgotPasswordCsrf`). + +### Validate field + +Open the InputFilter that validates the form fields and append the following code to the method that initializes the +fields (usually `init`): + +```php +$this->add(new CsrfInput('exampleCsrf')); +``` + +where `exampleCsrf` must match the CSRF field's name in the form. + +> Don't forget to modify both occurrences in this file. + +> Make sure that you validate the form using its `isValid` method in the handler/controller where it is submitted. + +### Render field + +Open the template that renders your form and add the following code somewhere between the form's opening and closing +tags: + +```text +{{ formElement(form.get('exampleCsrf')) }} +``` + +## 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). After filling out the form, submitting it should work as before. + +In order 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. Submitting a filled out form should result in a validation error: + +> This field is required and cannot be empty. + + +### Timeout + +Note the `timeout` option in your PHP form's `exampleCsrf` field, with its default value set to **3600**. This +represents the value in seconds for how long the token is valid. Submitting a form that has been rendered for longer +than this value will result in a validation error: + +> Invalid CSRF. + +You can modify the value of `timeout` in each form, but the default value should work in most cases. diff --git a/docs/book/v6/how-to/dependency-injection.md b/docs/book/v6/how-to/dependency-injection.md new file mode 100644 index 0000000..50c53f1 --- /dev/null +++ b/docs/book/v6/how-to/dependency-injection.md @@ -0,0 +1,56 @@ +# Dependency Injection + +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. + +Dotkernel Admin, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection. + +## Usage + +**Dotkernel Admin** comes out of the box with the [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all the functionality injecting dependencies into any object you want. + +`dot-dependency-injection` determines the dependencies by looking at the `#[Inject]` attribute, added to the constructor of a class. +Each dependency is specified as a separate parameter of the `#[Inject]` attribute. + +For our example we will inject `RouterInterface` and `AuthenticationServiceInterface` dependencies into `GetAccountLogoutHandler`. + +```php +use Dot\DependencyInjection\Attribute\Inject; + +class GetAccountLogoutHandler implements RequestHandlerInterface +{ + #[Inject( + RouterInterface::class, + AuthenticationServiceInterface::class, + )] + public function __construct( + protected RouterInterface $router, + protected AuthenticationServiceInterface $authenticationService, + ) { + } +} +``` + +> If your class needs the value of a specific configuration key, you can specify the path using dot notation: `config.example` + +The next step is to register the class in the `ConfigProvider` under `factories` using +`Dot\DependencyInjection\Factory\AttributedServiceFactory::class`. + +```php +public function getDependencies(): array +{ + return [ + 'factories' => [ + GetAccountLogoutHandler::class => AttributedServiceFactory::class, + ] + ]; +} +``` + +That's it. +When your object is instantiated from the container, it will automatically have its dependencies resolved. + +> 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`. diff --git a/docs/book/v6/how-to/npm_commands.md b/docs/book/v6/how-to/npm_commands.md new file mode 100644 index 0000000..f03d9cf --- /dev/null +++ b/docs/book/v6/how-to/npm_commands.md @@ -0,0 +1,22 @@ +# NPM Commands + +To install dependencies into the `node_modules` directory run this command. + +```shell +npm install +``` + +> If `npm install` fails, this could be caused by user permissions of npm. +> The recommended way to install npm is through `Node Version Manager`. + +The watch command compiles the components then monitors the files for changes and recompiles them. + +```shell +npm run watch +``` + +After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. + +```shell +npm run prod +``` diff --git a/docs/book/v6/installation/composer.md b/docs/book/v6/installation/composer.md new file mode 100644 index 0000000..75ae8b4 --- /dev/null +++ b/docs/book/v6/installation/composer.md @@ -0,0 +1,71 @@ +# Composer Installation of Packages + +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. + +## Install dependencies + +Run this command in the command prompt. + +> Use the **CLI** in order to ensure interactivity for proper configuration. + +```shell +composer install +``` + +You should see this text below, along with a long list of packages to be installed instead of the `[...]`. +In this example there are 171 packages, though the number can change in future updates. +You will find the packages in the `vendor` folder. + +```shell +No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information. +Loading composer repositories with package information +Updating dependencies +Lock file operations: 171 installs, 0 updates, 0 removals +[...] +Writing lock file +Installing dependencies from lock file (including require-dev) +Package operations: 171 installs, 0 updates, 0 removals +[...] +``` + +The setup script prompts for some configuration settings, for example the lines below: + +```shell +Please select which config file you wish to inject 'Laminas\Validator\ConfigProvider' into: + [0] Do not inject + [1] config/config.php + Make your selection (default is 1): +``` + +Type `0` to select `[0] Do not inject`. + +> We choose `0` because Dotkernel includes its own ConfigProvider which already contains the prompted configurations. +> If you choose `[1] config/config.php`, an extra `ConfigProvider` will be injected. + +The next question is: + +`Remember this option for other packages of the same type? (y/N)` + +Type `y` here, and hit `enter` to complete this stage. + +## 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 +``` diff --git a/docs/book/v6/installation/configuration-files.md b/docs/book/v6/installation/configuration-files.md new file mode 100644 index 0000000..e4afb67 --- /dev/null +++ b/docs/book/v6/installation/configuration-files.md @@ -0,0 +1,27 @@ +# Configuration Files + +## Mail + +> If you intend to send emails from your Frontend, make sure to fill in SMTP connection params. +> This will be covered in the next section. + +> **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. +> +If you want your application to send mail, add valid credentials to the following keys in `config/autoload/mail.global.php` + +Under `message_options` key: + +- `from` - email address that will send emails (required) +- `from_name` - organization name for signing sent emails (optional) + +Under `smtp_options` key: + +- `host` - hostname or IP address of the mail server (required) +- `connection_config` - add the `username` and `password` keys (required) + +In `config/autoload/local.php` edit the key `contact` => `message_receivers` => `to` with *string* values for emails that should receive contact messages. + +> **Please add at least 1 email address in order for contact message to reach someone** + +Also feel free to add as many CCs as you require under the `contact` => `message_receivers` => `cc` key. diff --git a/docs/book/v6/installation/doctrine-orm.md b/docs/book/v6/installation/doctrine-orm.md new file mode 100644 index 0000000..b5df8a4 --- /dev/null +++ b/docs/book/v6/installation/doctrine-orm.md @@ -0,0 +1,89 @@ +# Doctrine ORM + +This step saves the database connection credentials in an Admin configuration file. +We do not cover the creation steps of the database itself. + +## Setup database + +Create a new MySQL database and set its collation to `utf8mb4_general_ci`. + +Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`. +Below is the item you need to focus on. + +> `my_database`, `my_user`, `my_password` are provided only as an example. + +```php +$databases = [ + 'default' => [ + 'host' => 'localhost', + 'dbname' => 'my_database', + 'user' => 'my_user', + 'password' => 'my_password', + 'port' => 3306, + 'driver' => 'pdo_mysql', + 'charset' => 'utf8mb4', + 'collate' => 'utf8mb4_general_ci', + ], + // you can add more database connections into this array +]; +``` + +## Running migrations + +Run the database migrations by using the following command: + +```shell +php vendor/bin/doctrine-migrations migrate +``` + +Note: If you have already run the migrations, you may get this message. +You should double-check to make sure the new migrations are ok to run. + +```shell +WARNING! You have x previously executed migrations in the database that are not registered migrations. + {migration list} +Are you sure you wish to continue? (y/n) +``` + +When using an empty database, you will get this confirmation message instead. + +```shell +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) +``` + +Again, submit `y` to run all the migrations in chronological order. +Each migration will be logged in the `migrations` table to prevent running the same migration more than once, which is often not desirable. + +If everything ran correctly, you will get this confirmation. + +```shell +[OK] Successfully migrated to version: Core\App\Migration\Version20250407142911 +``` + +> The migration name `Version20250407142911` may differ in future Admin updates. + +## Fixtures + +Run this command to populate the admin tables with the default values: + +```shell +php bin/doctrine fixtures:execute +``` + +You should see our galloping horse in the command line. + +```shell +Executing Core\App\Fixture\AdminRoleLoader +Executing Core\App\Fixture\OAuthClientLoader +Executing Core\App\Fixture\OAuthScopeLoader +Executing Core\App\Fixture\UserRoleLoader +Executing Core\App\Fixture\AdminLoader +Executing Core\App\Fixture\UserLoader +Fixtures have been loaded. + .'' + ._.-.___.' (`\ + //( ( `' + '/ )\ ).__. ) + ' <' `\ ._/'\ + ` \ \ +``` diff --git a/docs/book/v6/installation/getting-started.md b/docs/book/v6/installation/getting-started.md new file mode 100644 index 0000000..bf4ce37 --- /dev/null +++ b/docs/book/v6/installation/getting-started.md @@ -0,0 +1,28 @@ +# Clone the project + +## Recommended development environment + +> If you are using Windows as OS on your machine, you can use WSL2 as development environment. +> Read more here: [PHP-Mariadb-on-WLS2](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/) + +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/admin.git . +``` + +If everything ran correctly, you can expect to see an output like this, though the numbers may differ. + +```shell +Cloning into '.'... +remote: Enumerating objects: 6538, done. +remote: Counting objects: 100% (1652/1652), done. +remote: Compressing objects: 100% (785/785), done. +remote: Total 6538 (delta 804), reused 1417 (delta 748), pack-reused 4886 (from 1) +Receiving objects: 100% (6538/6538), 11.84 MiB | 16.52 MiB/s, done. +Resolving deltas: 100% (3359/3359), done. +``` + +You can already open the project in your preferred IDE to double-check the files were copied correctly. diff --git a/docs/book/v6/installation/installation-intro.md b/docs/book/v6/installation/installation-intro.md new file mode 100644 index 0000000..b6f2e1b --- /dev/null +++ b/docs/book/v6/installation/installation-intro.md @@ -0,0 +1,11 @@ +# Introduction + +In this tutorial, we will install Dotkernel Admin from scratch. +We will focus on these tasks: + +- Highlight 3rd party tools required for the installation. +- Provide all the relevant commands with expected responses. +- Configure the development environment. +- 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. diff --git a/docs/book/v6/installation/manage-geolite2.md b/docs/book/v6/installation/manage-geolite2.md new file mode 100644 index 0000000..576b665 --- /dev/null +++ b/docs/book/v6/installation/manage-geolite2.md @@ -0,0 +1,31 @@ +# Manage the GeoLite2 databases + +You can download/update a specific GeoLite2 database, by running the following command where `{DATABASE}` can be `asn`, `city`, `country`: + +```shell +php bin/cli.php geoip:synchronize -d {DATABASE} +``` + +You can download/update all GeoLite2 databases at once, by running the following command: + +```shell +php bin/cli.php geoip:synchronize +``` + +The output should be similar to the below, displaying per row: `database identifier`: `previous build datetime` -> `current build datetime`. + +```shell +asn: n/a -> 2024-11-01 02:29:44 +city: n/a -> 2024-11-01 02:29:31 +country: n/a -> 2024-11-01 02:25:09 +``` + +> `n/a` will be replaced by the older version of the GeoLite2 databases when you run the command again. + +Get help for this command by running: + +```shell +php bin/cli.php help geoip:synchronize +``` + +**Tip**: 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. diff --git a/docs/book/v6/installation/test-the-installation.md b/docs/book/v6/installation/test-the-installation.md new file mode 100644 index 0000000..b37d7d6 --- /dev/null +++ b/docs/book/v6/installation/test-the-installation.md @@ -0,0 +1,43 @@ +# Running the application + +> **Do not enable dev mode in production** + +We recommend running your applications in WSL: + +- Make sure you have [WSL](https://github.com/dotkernel/development/blob/main/wsl/README.md) installed on your system. +- Currently we provide a distro implementations for [AlmaLinux9](https://github.com/dotkernel/development/blob/main/wsl/os/almalinux9/README.md). +- Install the application in a virtualhost as recommended by the chosen distro. +- Set `$baseUrl` in **config/autoload/local.php** to the address of the virtualhost. +- Run the application by opening the virtualhost address in your browser. + +You should see the `Dotkernel admin` login page. + +> If you are getting exceptions or errors regarding some missing services, try running the following command: + +```shell +sudo php bin/clear-config-cache.php +``` + +> If `config-cache.php` is present that config will be loaded regardless of the `ConfigAggregator::ENABLE_CACHE` in `config/autoload/mezzio.global.php` + +If you ran the fixtures you will have an admin user in the database with the following credentials: + +- **User**: `admin` +- **Password**: `dotadmin` + +> **Production only**: Make sure you modify the default admin credentials. + +> **Development only**: `session.cookie_secure` does not work locally so make sure you modify your `local.php`, as per the following: + +```php +# other code + +return [ + # other configurations... + 'session_config' => [ + 'cookie_secure' => false, + ], +]; +``` + +Do not change this in `local.php.dist` as well because this value should remain `true` on production. diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md new file mode 100644 index 0000000..6ff45e7 --- /dev/null +++ b/docs/book/v6/introduction/file-structure.md @@ -0,0 +1,123 @@ +# File structure + +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. + +When using Dotkernel Admin the following structure is installed by default: + +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/file-structure-dk-admin.jpg) + +## Special purpose folders + +* `.github` - Contains GitHub workflow files +* `.laminas-ci` - Contains laminas-ci workflow files + +## `bin` folder + +This folder contents are + +* `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 + +## `config` folder + +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 +* `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` folder + +This folder contains all service-related local and global config files: + +* `app.global.php` - Configures basic app variables +* `authentication.global.php` - Defines the Admin identity +* `authorization.global.php` - Configures permissions for user roles +* `authorization-guards.global.php` - Configures access per route for user roles +* `cli.global.php` - Configures cli +* `cors.global.php` - 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 +* `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.global.php` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging +* `mezzio.global.php` - Mezzio core config file +* `navigation.global.php` - Configures the top menu +* `session.global.php` - Configures the session +* `templates.global.php` - dotkernel/dot-twigrenderer config file + +## `data` folder + +This folder is a storage for project data files and service caches. +It contains these folders: + +* `cache` - Cache for e.g. Twig files +* `geoip` - Holds the GeoLite2 databases +* `lock` - Contains lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/) + +> AVOID storing sensitive data on the repository! + +## `log` folder + +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` folder + +This folder contains all publicly available assets and serves as the entry point of the application: + +* `css` and `js` - Contains the css and js file(s) generated by the webpack (npm) from the assets folder +* `fonts` and `images` - Contain the font and image file(s) copied by the webpack (npm) from the assets folder +* `uploads` - a folder that normally contains admin avatar images +* `.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` folder + +This folder contains a separate folder for each Module. + +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 +* `Core` – Contains the shared logic and base infrastructure used across multiple modules +* `Dashboard` – Contains the structure and rendering logic of the main admin dashboard, including layout, widgets, and default admin landing page +* `Page` - Contains reusable UI components and layout elements such as dropdowns, modal popups, error displays, and tooltips for the admin interface +* `Setting` - Contains functionality for saving and reading display settings +* `User` - Contains functionality for managing users; note these are users save in the `user` database table + + +### Module contents + +Each Module folder, in turn, should contain the following folders, unless they are empty: + +* `src/Entity` - Used by database entities +* `src/Handler` - Action classes +* `src/InputFilter` - Validation rules for inputs +* `src/Repository` - Entity repository folder +* `src/Service` - Service classes + +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 `Adapter`, `Factory`, `Form`, `Delegator` etc. + +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 + +### `templates` folder for modules + +This folder contains the template files, used for example to help render e-mail templates. + +> `twig` is used as Templating Engine. +> All template files have the extension `.html.twig`. diff --git a/docs/book/v6/introduction/introduction.md b/docs/book/v6/introduction/introduction.md new file mode 100644 index 0000000..9d780dc --- /dev/null +++ b/docs/book/v6/introduction/introduction.md @@ -0,0 +1,9 @@ +# Introduction + +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. + +> Check out our [demo](https://admin6.dotkernel.net/). +> +> Submit user `admin` and password `dotadmin` to authenticate yourself. diff --git a/docs/book/v6/introduction/packages.md b/docs/book/v6/introduction/packages.md new file mode 100644 index 0000000..aad5246 --- /dev/null +++ b/docs/book/v6/introduction/packages.md @@ -0,0 +1,27 @@ +# Packages + +* `dotkernel/dot-cache` - Provides caching based on symfony/cache +* `dotkernel/dot-cli` - Build console applications based on laminas-cli +* `dotkernel/dot-data-fixtures` - Provides a CLI interface for listing & executing doctrine data fixtures +* `dotkernel/dot-dependency-injection` - Dependency injection component using class attributes +* `dotkernel/dot-errorhandler` - Logging Error Handler for Middleware Applications +* `dotkernel/dot-flashmessenger` - Provides session messages between redirects +* `dotkernel/dot-geoip` - Retrieve information about an IP address based on maxmind/GeoIP2-php +* `dotkernel/dot-helpers` - Helper/Utility classes based on mezzio/mezzio-helpers +* `dotkernel/dot-mail` - Mail component based on laminas-mail +* `dotkernel/dot-navigation` - Allows you to easily define and parse menus inside templates, configuration based approach +* `dotkernel/dot-rbac-guard` - Defines authorization guards that authorize users for accessing certain parts of an application based on various criteria +* `dotkernel/dot-router` - Dotkernel component to build complex routes, based on mezzio/mezzio-fastroute +* `dotkernel/dot-session` - Dotkernel session component extending and customizing laminas-session +* `dotkernel/dot-twigrenderer` - Dotkernel component providing twig extensions and customizations +* `friendsofphp/proxy-manager-lts` - Fork of ocramius/proxy-manager +* `laminas/laminas-component-installer` - Composer plugin for injecting modules and configuration providers into application configuration +* `laminas/laminas-config-aggregator` - Lightweight library for collecting and merging configuration from different sources +* `mezzio/mezzio` - PSR-15 Middleware Microframework +* `mezzio-authentication-oauth2` - Middleware for Mezzio and PSR-7 applications providing an OAuth2 server for authentication. +* `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 +* `ramsey/uuid` - Library for generating and working with universally unique identifiers (UUIDs). +* `ramsey/uuid-doctrine` - Use ramsey/uuid as a Doctrine field type +* `roave/psr-container-doctrine` - Doctrine Factories for PSR-11 Containers diff --git a/docs/book/v6/introduction/server-requirements.md b/docs/book/v6/introduction/server-requirements.md new file mode 100644 index 0000000..26435fd --- /dev/null +++ b/docs/book/v6/introduction/server-requirements.md @@ -0,0 +1,50 @@ +# Server Requirements + +For production, we highly recommend a *nix based system. + +## Webserver + +### Apache >= 2.2 + +* mod_rewrite +* .htaccess support `(AllowOverride All)` + +> The repository includes a default `.htaccess` file in the `public` folder. + +### Nginx + +You need to convert the provided Apache related `.htaccess` file into Nginx configuration instructions. + +## 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 + +* Tested with MariaDB 10.11 LTS and MariaDB 11.4 LTS +* Tested with MySQL 8.4 LTS + +> For MySQL 8.4 LTS be sure you have the below line in my.cnf + +```text +mysql_native_password=ON +``` + +## 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) +* sqlite3 - for tests From f48706d0d6b37bec8efa021f3f9dd20eab3b8f9f Mon Sep 17 00:00:00 2001 From: nati Date: Wed, 9 Jul 2025 13:07:47 +0300 Subject: [PATCH 2/8] Fix linting errors in documentation Signed-off-by: nati --- docs/book/v6/how-to/csrf.md | 1 - .../v6/installation/configuration-files.md | 2 +- docs/book/v6/introduction/file-structure.md | 1 - mkdocs.yml | 24 ++++++++++++++++++- 4 files changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/book/v6/how-to/csrf.md b/docs/book/v6/how-to/csrf.md index 78c0343..307181e 100644 --- a/docs/book/v6/how-to/csrf.md +++ b/docs/book/v6/how-to/csrf.md @@ -67,7 +67,6 @@ In order to make sure that the new CSRF field works as expected, you can inspect > This field is required and cannot be empty. - ### Timeout Note the `timeout` option in your PHP form's `exampleCsrf` field, with its default value set to **3600**. This diff --git a/docs/book/v6/installation/configuration-files.md b/docs/book/v6/installation/configuration-files.md index e4afb67..63d3062 100644 --- a/docs/book/v6/installation/configuration-files.md +++ b/docs/book/v6/installation/configuration-files.md @@ -7,7 +7,7 @@ > **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. -> + If you want your application to send mail, add valid credentials to the following keys in `config/autoload/mail.global.php` Under `message_options` key: diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md index 6ff45e7..6b74f24 100644 --- a/docs/book/v6/introduction/file-structure.md +++ b/docs/book/v6/introduction/file-structure.md @@ -95,7 +95,6 @@ These are the modules included by default: * `Setting` - Contains functionality for saving and reading display settings * `User` - Contains functionality for managing users; note these are users save in the `user` database table - ### Module contents Each Module folder, in turn, should contain the following folders, unless they are empty: diff --git a/mkdocs.yml b/mkdocs.yml index 48205b3..9b21473 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,9 +2,10 @@ docs_dir: docs/book site_dir: docs/html extra: project: Admin - current_version: v5 + current_version: v6 versions: - v5 + - v6 nav: - Home: index.md - v5: @@ -28,6 +29,27 @@ nav: - "Use NPM Commands": v5/how-to/npm_commands.md - "Inject Dependencies": v5/how-to/dependency-injection.md - "Set Up CSRF": v5/how-to/csrf.md + - v6: + - Introduction: v6/introduction/introduction.md + - Overview: + - "Server Requirements": v6/introduction/server-requirements.md + - "File Structure": v6/introduction/file-structure.md + - "Packages": v6/introduction/packages.md + - Installation: + - "Introduction": v6/installation/installation-intro.md + - "Getting Started": v6/installation/getting-started.md + - "Composer": v6/installation/composer.md + - "Configuration Files": v6/installation/configuration-files.md + - "Doctrine ORM": v6/installation/doctrine-orm.md + - "Manage Geolite2": v6/installation/manage-geolite2.md + - "Test the Installation": v6/installation/test-the-installation.md + - How to: + - "Create Database Migrations": v6/how-to/creating-migrations.md + - "Create Database Fixtures": v6/how-to/creating-fixtures.md + - "Configure Authorizations": v6/how-to/authorization.md + - "Use NPM Commands": v6/how-to/npm_commands.md + - "Inject Dependencies": v6/how-to/dependency-injection.md + - "Set Up CSRF": v6/how-to/csrf.md site_name: admin site_description: "DotKernel Admin" repo_url: "https://github.com/dotkernel/admin" From 77c4c38264327c23a1d88dc3b595f2d2b6f7711a Mon Sep 17 00:00:00 2001 From: nati Date: Wed, 9 Jul 2025 13:33:43 +0300 Subject: [PATCH 3/8] Added packages versions for packages.md Signed-off-by: nati --- docs/book/v6/introduction/packages.md | 50 +++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/book/v6/introduction/packages.md b/docs/book/v6/introduction/packages.md index aad5246..ed697c4 100644 --- a/docs/book/v6/introduction/packages.md +++ b/docs/book/v6/introduction/packages.md @@ -1,27 +1,27 @@ # Packages -* `dotkernel/dot-cache` - Provides caching based on symfony/cache -* `dotkernel/dot-cli` - Build console applications based on laminas-cli -* `dotkernel/dot-data-fixtures` - Provides a CLI interface for listing & executing doctrine data fixtures -* `dotkernel/dot-dependency-injection` - Dependency injection component using class attributes -* `dotkernel/dot-errorhandler` - Logging Error Handler for Middleware Applications -* `dotkernel/dot-flashmessenger` - Provides session messages between redirects -* `dotkernel/dot-geoip` - Retrieve information about an IP address based on maxmind/GeoIP2-php -* `dotkernel/dot-helpers` - Helper/Utility classes based on mezzio/mezzio-helpers -* `dotkernel/dot-mail` - Mail component based on laminas-mail -* `dotkernel/dot-navigation` - Allows you to easily define and parse menus inside templates, configuration based approach -* `dotkernel/dot-rbac-guard` - Defines authorization guards that authorize users for accessing certain parts of an application based on various criteria -* `dotkernel/dot-router` - Dotkernel component to build complex routes, based on mezzio/mezzio-fastroute -* `dotkernel/dot-session` - Dotkernel session component extending and customizing laminas-session -* `dotkernel/dot-twigrenderer` - Dotkernel component providing twig extensions and customizations -* `friendsofphp/proxy-manager-lts` - Fork of ocramius/proxy-manager -* `laminas/laminas-component-installer` - Composer plugin for injecting modules and configuration providers into application configuration -* `laminas/laminas-config-aggregator` - Lightweight library for collecting and merging configuration from different sources -* `mezzio/mezzio` - PSR-15 Middleware Microframework -* `mezzio-authentication-oauth2` - Middleware for Mezzio and PSR-7 applications providing an OAuth2 server for authentication. -* `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 -* `ramsey/uuid` - Library for generating and working with universally unique identifiers (UUIDs). -* `ramsey/uuid-doctrine` - Use ramsey/uuid as a Doctrine field type -* `roave/psr-container-doctrine` - Doctrine Factories for PSR-11 Containers +* `dotkernel/dot-cache`:`^4.3` - Provides caching based on symfony/cache +* `dotkernel/dot-cli`:`^3.9` - Build console applications based on laminas-cli +* `dotkernel/dot-data-fixtures`:`^1.4` - Provides a CLI interface for listing & executing doctrine data fixtures +* `dotkernel/dot-dependency-injection`:`^1.2` - Dependency injection component using class attributes +* `dotkernel/dot-errorhandler`:`^4.0` - Logging Error Handler for Middleware Applications +* `dotkernel/dot-flashmessenger`:`^3.6` - Provides session messages between redirects +* `dotkernel/dot-geoip`:`^3.9` - Retrieve information about an IP address based on maxmind/GeoIP2-php +* `dotkernel/dot-helpers`:`^3.8` - Helper/Utility classes based on mezzio/mezzio-helpers +* `dotkernel/dot-mail`:`^5.1` - Mail component based on laminas-mail +* `dotkernel/dot-navigation`:`^3.5` - Allows you to easily define and parse menus inside templates, configuration based approach +* `dotkernel/dot-rbac-guard`:`^3.6` - Defines authorization guards that authorize users for accessing certain parts of an application based on various criteria +* `dotkernel/dot-router`:`^1.0` - Dotkernel component to build complex routes, based on mezzio/mezzio-fastroute +* `dotkernel/dot-session`:`^5.7` - Dotkernel session component extending and customizing laminas-session +* `dotkernel/dot-twigrenderer`:`^3.6` - Dotkernel component providing twig extensions and customizations +* `friendsofphp/proxy-manager-lts`:`^1.0` - Fork of ocramius/proxy-manager +* `laminas/laminas-component-installer`:`^3.5` - Composer plugin for injecting modules and configuration providers into application configuration +* `laminas/laminas-config-aggregator`:`^1.18` - Lightweight library for collecting and merging configuration from different sources +* `mezzio/mezzio`:`^3.21` - PSR-15 Middleware Microframework +* `mezzio-authentication-oauth2`:`^2.11` - Middleware for Mezzio and PSR-7 applications providing an OAuth2 server for authentication. +* `mezzio/mezzio-authorization-rbac`:`^1.9` - Mezzio authorization rbac adapter for laminas/laminas-permissions-rbac +* `mezzio/mezzio-cors`:`^1.14` - CORS component for Mezzio and other PSR-15 middleware runners +* `mezzio/mezzio-fastroute`:`^3.13` - FastRoute integration for Mezzio +* `ramsey/uuid`:`^4.5` - Library for generating and working with universally unique identifiers (UUIDs). +* `ramsey/uuid-doctrine`:`^2.1` - Use ramsey/uuid as a Doctrine field type +* `roave/psr-container-doctrine`:`^5.2` - Doctrine Factories for PSR-11 Containers From bc4ec069232540fb0910146b3b4cd68dc0bdf899 Mon Sep 17 00:00:00 2001 From: nati Date: Thu, 10 Jul 2025 15:50:19 +0300 Subject: [PATCH 4/8] Revised text and markup blocks Signed-off-by: nati --- docs/book/v6/how-to/authorization.md | 31 +++++++++---------- docs/book/v6/how-to/creating-fixtures.md | 9 +++--- docs/book/v6/how-to/creating-migrations.md | 2 +- docs/book/v6/how-to/csrf.md | 17 ++++------ docs/book/v6/how-to/dependency-injection.md | 3 +- docs/book/v6/installation/composer.md | 6 ++-- .../v6/installation/configuration-files.md | 12 ++----- docs/book/v6/installation/doctrine-orm.md | 14 ++++----- docs/book/v6/installation/manage-geolite2.md | 8 ++--- .../v6/installation/test-the-installation.md | 10 +++--- docs/book/v6/introduction/file-structure.md | 2 +- docs/book/v6/introduction/packages.md | 3 ++ 12 files changed, 53 insertions(+), 64 deletions(-) diff --git a/docs/book/v6/how-to/authorization.md b/docs/book/v6/how-to/authorization.md index 626a984..1850917 100644 --- a/docs/book/v6/how-to/authorization.md +++ b/docs/book/v6/how-to/authorization.md @@ -1,28 +1,27 @@ # Authorization Guards -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. +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. The `authorization.global.php` file provides multiple configurations specifying multiple roles as well as the types of permissions to which these roles have access. ```php //example of a flat RBAC model that specifies two types of roles as well as their permission 'roles' => [ - 'admin' => [ - 'permissions' => [ - 'authenticated', - 'edit', - 'delete', - //etc.. - ] - ], - 'user' => [ - 'permissions' => [ - 'authenticated', - //etc.. - ] - ] + 'admin' => [ + 'permissions' => [ + 'authenticated', + 'edit', + 'delete', + //etc.. ] + ], + 'user' => [ + 'permissions' => [ + 'authenticated', + //etc.. + ] + ] + ] ``` The `authorization-guards.global.php` file defines which permissions are required to access specific route handlers. These permissions must first be declared in the authorization.global.php (dot-rbac) configuration file. diff --git a/docs/book/v6/how-to/creating-fixtures.md b/docs/book/v6/how-to/creating-fixtures.md index 2f5057e..8fafd6c 100644 --- a/docs/book/v6/how-to/creating-fixtures.md +++ b/docs/book/v6/how-to/creating-fixtures.md @@ -2,8 +2,7 @@ > 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`. -See below on how to use our CLI command for listing and executing Doctrine data fixtures. +Seeding the database is done with the help of our custom package `dotkernel/dot-data-fixtures` built on top of `doctrine/data-fixtures`. See below on how to use our CLI command for listing and executing Doctrine data fixtures. ## Working with fixtures @@ -12,19 +11,19 @@ You can find an example of a fixtures class in `src/Core/src/App/src/Fixture/Adm To list all the available fixtures by order of execution run: ```shell -php bin/doctrine fixtures:list +php ./bin/doctrine fixtures:list ``` To execute all fixtures run: ```shell -php bin/doctrine fixtures:execute +php ./bin/doctrine fixtures:execute ``` To execute a specific fixture, use its class name, like in this example: ```shell -php bin/doctrine fixtures:execute --class=AdminLoader +php ./bin/doctrine fixtures:execute --class=AdminLoader ``` Fixtures can and should be ordered to ensure database consistency. diff --git a/docs/book/v6/how-to/creating-migrations.md b/docs/book/v6/how-to/creating-migrations.md index cfc3407..12ddb09 100644 --- a/docs/book/v6/how-to/creating-migrations.md +++ b/docs/book/v6/how-to/creating-migrations.md @@ -4,7 +4,7 @@ Migrations are used to create and/or edit the database structure. To generate a new migration file, use this command: ```shell -php vendor/bin/doctrine-migrations migrations:generate +php ./vendor/bin/doctrine-migrations migrations:generate ``` It creates a PHP file like this one `src/Core/src/App/src/Migration/Version20240627134952.php` that can then be edited in the IDE. diff --git a/docs/book/v6/how-to/csrf.md b/docs/book/v6/how-to/csrf.md index 307181e..49dcd8d 100644 --- a/docs/book/v6/how-to/csrf.md +++ b/docs/book/v6/how-to/csrf.md @@ -23,7 +23,7 @@ Open the form's PHP class and append the following code to the method that initi ```php $this->add( - (new Csrf('exampleCsrf')) + (new \Laminas\Form\Element\Csrf('exampleCsrf')) ->setOptions([ 'csrf_options' => ['timeout' => 3600, 'session' => new Container()], ]) @@ -39,7 +39,7 @@ Open the InputFilter that validates the form fields and append the following cod fields (usually `init`): ```php -$this->add(new CsrfInput('exampleCsrf')); +$this->add(new \Admin\App\InputFilter\Input\CsrfInput('exampleCsrf')); ``` where `exampleCsrf` must match the CSRF field's name in the form. @@ -50,8 +50,7 @@ where `exampleCsrf` must match the CSRF field's name in the form. ### Render field -Open the template that renders your form and add the following code somewhere between the form's opening and closing -tags: +Open the template that renders your form and add the following code somewhere between the form's opening and closing tags: ```text {{ formElement(form.get('exampleCsrf')) }} @@ -59,19 +58,15 @@ tags: ## 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). After filling out the form, submitting it should work as before. +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. -In order 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. Submitting a filled out form should result in a validation error: +In order 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. Submitting a filled out form should result in a validation error: > This field is required and cannot be empty. ### Timeout -Note the `timeout` option in your PHP form's `exampleCsrf` field, with its default value set to **3600**. This -represents the value in seconds for how long the token is valid. Submitting a form that has been rendered for longer -than this value will result in a validation error: +Note the `timeout` option in your PHP form's `exampleCsrf` field, with its default value set to **3600**. This represents the value in seconds for how long the token is valid. Submitting a form that has been rendered for longer than this value will result in a validation error: > Invalid CSRF. diff --git a/docs/book/v6/how-to/dependency-injection.md b/docs/book/v6/how-to/dependency-injection.md index 50c53f1..1d20e15 100644 --- a/docs/book/v6/how-to/dependency-injection.md +++ b/docs/book/v6/how-to/dependency-injection.md @@ -35,8 +35,7 @@ class GetAccountLogoutHandler implements RequestHandlerInterface > If your class needs the value of a specific configuration key, you can specify the path using dot notation: `config.example` -The next step is to register the class in the `ConfigProvider` under `factories` using -`Dot\DependencyInjection\Factory\AttributedServiceFactory::class`. +The next step is to register the class in the `ConfigProvider` under `factories` using `Dot\DependencyInjection\Factory\AttributedServiceFactory::class`. ```php public function getDependencies(): array diff --git a/docs/book/v6/installation/composer.md b/docs/book/v6/installation/composer.md index 75ae8b4..f51f860 100644 --- a/docs/book/v6/installation/composer.md +++ b/docs/book/v6/installation/composer.md @@ -32,7 +32,7 @@ Package operations: 171 installs, 0 updates, 0 removals The setup script prompts for some configuration settings, for example the lines below: -```shell +```text Please select which config file you wish to inject 'Laminas\Validator\ConfigProvider' into: [0] Do not inject [1] config/config.php @@ -46,7 +46,9 @@ Type `0` to select `[0] Do not inject`. The next question is: -`Remember this option for other packages of the same type? (y/N)` +```text +Remember this option for other packages of the same type? (y/N) +``` Type `y` here, and hit `enter` to complete this stage. diff --git a/docs/book/v6/installation/configuration-files.md b/docs/book/v6/installation/configuration-files.md index 63d3062..42cdad8 100644 --- a/docs/book/v6/installation/configuration-files.md +++ b/docs/book/v6/installation/configuration-files.md @@ -5,8 +5,7 @@ > If you intend to send emails from your Frontend, make sure to fill in SMTP connection params. > This will be covered in the next section. -> **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. +> **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. If you want your application to send mail, add valid credentials to the following keys in `config/autoload/mail.global.php` @@ -15,13 +14,6 @@ Under `message_options` key: - `from` - email address that will send emails (required) - `from_name` - organization name for signing sent emails (optional) -Under `smtp_options` key: - -- `host` - hostname or IP address of the mail server (required) -- `connection_config` - add the `username` and `password` keys (required) - -In `config/autoload/local.php` edit the key `contact` => `message_receivers` => `to` with *string* values for emails that should receive contact messages. - > **Please add at least 1 email address in order for contact message to reach someone** -Also feel free to add as many CCs as you require under the `contact` => `message_receivers` => `cc` key. +Also feel free to add as many CCs as you require under the `dot_mail` => `default` => `message_options` => `cc` key. diff --git a/docs/book/v6/installation/doctrine-orm.md b/docs/book/v6/installation/doctrine-orm.md index b5df8a4..8a56954 100644 --- a/docs/book/v6/installation/doctrine-orm.md +++ b/docs/book/v6/installation/doctrine-orm.md @@ -33,13 +33,13 @@ $databases = [ Run the database migrations by using the following command: ```shell -php vendor/bin/doctrine-migrations migrate +php ./vendor/bin/doctrine-migrations migrate ``` -Note: If you have already run the migrations, you may get this message. -You should double-check to make sure the new migrations are ok to run. +> If you have already run the migrations, you may get this message. +> You should double-check to make sure the new migrations are ok to run. -```shell +```text WARNING! You have x previously executed migrations in the database that are not registered migrations. {migration list} Are you sure you wish to continue? (y/n) @@ -47,7 +47,7 @@ Are you sure you wish to continue? (y/n) When using an empty database, you will get this confirmation message instead. -```shell +```text 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) ``` @@ -56,7 +56,7 @@ Each migration will be logged in the `migrations` table to prevent running the s If everything ran correctly, you will get this confirmation. -```shell +```text [OK] Successfully migrated to version: Core\App\Migration\Version20250407142911 ``` @@ -67,7 +67,7 @@ If everything ran correctly, you will get this confirmation. Run this command to populate the admin tables with the default values: ```shell -php bin/doctrine fixtures:execute +php ./bin/doctrine fixtures:execute ``` You should see our galloping horse in the command line. diff --git a/docs/book/v6/installation/manage-geolite2.md b/docs/book/v6/installation/manage-geolite2.md index 576b665..d175c55 100644 --- a/docs/book/v6/installation/manage-geolite2.md +++ b/docs/book/v6/installation/manage-geolite2.md @@ -3,13 +3,13 @@ You can download/update a specific GeoLite2 database, by running the following command where `{DATABASE}` can be `asn`, `city`, `country`: ```shell -php bin/cli.php geoip:synchronize -d {DATABASE} +php ./bin/cli.php geoip:synchronize -d {DATABASE} ``` You can download/update all GeoLite2 databases at once, by running the following command: ```shell -php bin/cli.php geoip:synchronize +php ./bin/cli.php geoip:synchronize ``` The output should be similar to the below, displaying per row: `database identifier`: `previous build datetime` -> `current build datetime`. @@ -25,7 +25,7 @@ country: n/a -> 2024-11-01 02:25:09 Get help for this command by running: ```shell -php bin/cli.php help geoip:synchronize +php ./bin/cli.php help geoip:synchronize ``` -**Tip**: 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. +> 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. diff --git a/docs/book/v6/installation/test-the-installation.md b/docs/book/v6/installation/test-the-installation.md index b37d7d6..bb3caf4 100644 --- a/docs/book/v6/installation/test-the-installation.md +++ b/docs/book/v6/installation/test-the-installation.md @@ -4,18 +4,18 @@ We recommend running your applications in WSL: -- Make sure you have [WSL](https://github.com/dotkernel/development/blob/main/wsl/README.md) installed on your system. -- Currently we provide a distro implementations for [AlmaLinux9](https://github.com/dotkernel/development/blob/main/wsl/os/almalinux9/README.md). +- Make sure you have [WSL2](https://docs.dotkernel.org/development/v2/setup/system-requirements/) installed on your system. +- Currently we provide a distro implementations for [AlmaLinux9](https://github.com/dotkernel/development/blob/main/wsl/README.md). - Install the application in a virtualhost as recommended by the chosen distro. - Set `$baseUrl` in **config/autoload/local.php** to the address of the virtualhost. - Run the application by opening the virtualhost address in your browser. -You should see the `Dotkernel admin` login page. +You should see the `Dotkernel Admin` login page. > If you are getting exceptions or errors regarding some missing services, try running the following command: ```shell -sudo php bin/clear-config-cache.php +sudo php ./bin/clear-config-cache.php ``` > If `config-cache.php` is present that config will be loaded regardless of the `ConfigAggregator::ENABLE_CACHE` in `config/autoload/mezzio.global.php` @@ -40,4 +40,4 @@ return [ ]; ``` -Do not change this in `local.php.dist` as well because this value should remain `true` on production. +> Do not change this in `local.php.dist` as well because this value should remain `true` on production. diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md index 6b74f24..0d6a76d 100644 --- a/docs/book/v6/introduction/file-structure.md +++ b/docs/book/v6/introduction/file-structure.md @@ -59,7 +59,7 @@ This folder contains all service-related local and global config files: This folder is a storage for project data files and service caches. It contains these folders: -* `cache` - Cache for e.g. Twig files +* `cache` - Twig and Doctrine cache files * `geoip` - Holds the GeoLite2 databases * `lock` - Contains lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/) diff --git a/docs/book/v6/introduction/packages.md b/docs/book/v6/introduction/packages.md index ed697c4..b9a27b6 100644 --- a/docs/book/v6/introduction/packages.md +++ b/docs/book/v6/introduction/packages.md @@ -1,5 +1,8 @@ # Packages +> Dotkernel Admin 6.x will have full Laminas Service Manager 4 support once all dependencies do support it. +> Once Laminas Service Manager 4 is fully supported, Dotkernel Admin 6.x will be installable on PHP 8.4 as well. + * `dotkernel/dot-cache`:`^4.3` - Provides caching based on symfony/cache * `dotkernel/dot-cli`:`^3.9` - Build console applications based on laminas-cli * `dotkernel/dot-data-fixtures`:`^1.4` - Provides a CLI interface for listing & executing doctrine data fixtures From e0da7e44714c39e60a0ad70633c9da03e0a2a373 Mon Sep 17 00:00:00 2001 From: nati Date: Thu, 10 Jul 2025 15:54:53 +0300 Subject: [PATCH 5/8] Fixed text typo Signed-off-by: nati --- docs/book/v6/installation/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/v6/installation/getting-started.md b/docs/book/v6/installation/getting-started.md index bf4ce37..76e13e5 100644 --- a/docs/book/v6/installation/getting-started.md +++ b/docs/book/v6/installation/getting-started.md @@ -3,7 +3,7 @@ ## Recommended development environment > If you are using Windows as OS on your machine, you can use WSL2 as development environment. -> Read more here: [PHP-Mariadb-on-WLS2](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/) +> Read more here: [PHP-Mariadb-on-WSL2](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/) 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. From 299f91a8d6efecd78ec70bb6d057425a240a3b2b Mon Sep 17 00:00:00 2001 From: nati Date: Thu, 10 Jul 2025 19:20:51 +0300 Subject: [PATCH 6/8] Added core module details in file-structure.md for v6 Signed-off-by: nati --- docs/book/v6/introduction/file-structure.md | 23 +++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md index 0d6a76d..180044d 100644 --- a/docs/book/v6/introduction/file-structure.md +++ b/docs/book/v6/introduction/file-structure.md @@ -99,10 +99,8 @@ These are the modules included by default: Each Module folder, in turn, should contain the following folders, unless they are empty: -* `src/Entity` - Used by database entities * `src/Handler` - Action classes * `src/InputFilter` - Validation rules for inputs -* `src/Repository` - Entity repository folder * `src/Service` - Service classes The above example is just some of the folders a project may include, but they should give you an idea about the recommended structure. @@ -120,3 +118,24 @@ This folder contains the template files, used for example to help render e-mail > `twig` is used as Templating Engine. > All template files have the extension `.html.twig`. + +### Core module + +The Core module is a common codebase set up to be used by the applications you added to your project. + +These are the submodules included by default: + +* `Admin` - Contains logic for the admin submodule features +* `App` - Contains shared application-level services and infrastructure utilities +* `Security` - Contains authentication, authorization, and related security mechanisms +* `Setting` - Contains configuration and application settings management +* `User` - Contains user entities, repositories, and services handling user data and logic + +Each submodule folder should contain: + +* `src/Entity` - Used by database entities +* `src/Repository` - Entity repository folder +* `ConfigProvider.php` - Configuration data for the module + +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. From 330971b849c25d75ea6d59e75d84bdc0eab37f4d Mon Sep 17 00:00:00 2001 From: nati Date: Thu, 10 Jul 2025 19:26:53 +0300 Subject: [PATCH 7/8] Linting error fix Signed-off-by: nati --- docs/book/v6/introduction/file-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md index 180044d..a7fd87a 100644 --- a/docs/book/v6/introduction/file-structure.md +++ b/docs/book/v6/introduction/file-structure.md @@ -121,7 +121,7 @@ This folder contains the template files, used for example to help render e-mail ### Core module -The Core module is a common codebase set up to be used by the applications you added to your project. +The Core module is a common codebase set up to be used by the applications you added to your project. These are the submodules included by default: From c2e81f9e864efe63129cd5f05f2fe05f1ee4bb27 Mon Sep 17 00:00:00 2001 From: nati Date: Mon, 14 Jul 2025 12:43:36 +0300 Subject: [PATCH 8/8] Changed file-structure.md image to reflect v6 structure Signed-off-by: nati --- docs/book/v6/introduction/file-structure.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md index a7fd87a..c428d07 100644 --- a/docs/book/v6/introduction/file-structure.md +++ b/docs/book/v6/introduction/file-structure.md @@ -6,7 +6,8 @@ It is considered good practice to standardize the file structure of projects. When using Dotkernel Admin the following structure is installed by default: -![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/file-structure-dk-admin.jpg) +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v6/file-structure-dk-admin.jpg +) ## Special purpose folders