@@ -614,5 +614,5 @@
Search
diff --git a/search/search_index.json b/search/search_index.json
index de86123..997c943 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"../../README.md","title":"Home"},{"location":"#readmemd","text":"","title":"../../README.md"},{"location":"v5/how-to/authorization/","text":"Authorization Guards The packages responsible for restricting access to certain parts of the application are dot-rbac-guard and 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. //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 provides configuration to restrict access to certain actions based on the permissions defined in authorization.global.php so basically we have to add the permissions in the dot-rbac configuration file first to specify the action restriction permissions. // configuration example to restrict certain actions of some routes based on the permissions specified in the dot-rbac configuration file 'rules' => [ [ 'route' => 'account', 'actions' => [//list of actions to apply , or empty array for all actions 'unregister', 'avatar', 'details', 'changePassword' ], 'permissions' => ['authenticated'] ], [ 'route' => 'admin', 'actions' => [ 'deleteAccount' ], 'permissions' => [ 'delete' //list of roles to allow ] ] ]","title":"Configure Authorizations"},{"location":"v5/how-to/authorization/#authorization-guards","text":"The packages responsible for restricting access to certain parts of the application are dot-rbac-guard and 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. //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 provides configuration to restrict access to certain actions based on the permissions defined in authorization.global.php so basically we have to add the permissions in the dot-rbac configuration file first to specify the action restriction permissions. // configuration example to restrict certain actions of some routes based on the permissions specified in the dot-rbac configuration file 'rules' => [ [ 'route' => 'account', 'actions' => [//list of actions to apply , or empty array for all actions 'unregister', 'avatar', 'details', 'changePassword' ], 'permissions' => ['authenticated'] ], [ 'route' => 'admin', 'actions' => [ 'deleteAccount' ], 'permissions' => [ 'delete' //list of roles to allow ] ] ]","title":"Authorization Guards"},{"location":"v5/how-to/creating-fixtures/","text":"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 data/doctrine/fixtures/AdminLoader.php . To list all the available fixtures by order of execution run: php bin/doctrine fixtures:list To execute all fixtures run: php bin/doctrine fixtures:execute To execute a specific fixture, use its class name, like in this example: 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","title":"Create Database Fixtures"},{"location":"v5/how-to/creating-fixtures/#fixtures","text":"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.","title":"Fixtures"},{"location":"v5/how-to/creating-fixtures/#working-with-fixtures","text":"You can find an example of a fixtures class in data/doctrine/fixtures/AdminLoader.php . To list all the available fixtures by order of execution run: php bin/doctrine fixtures:list To execute all fixtures run: php bin/doctrine fixtures:execute To execute a specific fixture, use its class name, like in this example: 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","title":"Working with fixtures"},{"location":"v5/how-to/creating-migrations/","text":"Creating migrations Migrations are used to create and/or edit the database structure. To generate a new migration file, use this command: php vendor/bin/doctrine-migrations migrations:generate It creates a PHP file like this one /data/doctrine/migrations/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 : $this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL'); And its opposite in public function down : $this->addSql('ALTER TABLE admin DROP test');","title":"Create Database Migrations"},{"location":"v5/how-to/creating-migrations/#creating-migrations","text":"Migrations are used to create and/or edit the database structure. To generate a new migration file, use this command: php vendor/bin/doctrine-migrations migrations:generate It creates a PHP file like this one /data/doctrine/migrations/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.","title":"Creating migrations"},{"location":"v5/how-to/creating-migrations/#example","text":"This example creates a new column named test . Add this in public function up : $this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL'); And its opposite in public function down : $this->addSql('ALTER TABLE admin DROP test');","title":"Example"},{"location":"v5/how-to/csrf/","text":"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 's CSRF element validate new field using laminas/laminas-session 's CSRF validator render field using laminas/laminas-form 's FormElement helper Create field Open the form's PHP class and append the following code to the method that initializes the fields (usually init ): $this->add(new \\Laminas\\Form\\Element\\Csrf('exampleCsrf', [ 'csrf_options' => [ 'timeout' => 3600, 'session' => new \\Laminas\\Session\\Container(), ], ])); 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 ): $csrf = new \\Laminas\\InputFilter\\Input('exampleCsrf'); $csrf->setRequired(true); $csrf->getFilterChain() ->attachByName(\\Laminas\\Filter\\StringTrim::class) ->attachByName(\\Laminas\\Filter\\StripTags::class); $csrf->getValidatorChain() ->attachByName(\\Laminas\\Validator\\NotEmpty::class, [ 'message' => '<b>CSRF</b> is required and cannot be empty', ], true) ->attachByName(\\Laminas\\Session\\Validator\\Csrf::class, [ 'name' => 'exampleCsrf', 'message' => '<b>CSRF</b> is invalid', 'session' => new \\Laminas\\Session\\Container(), ], true); $this->add($csrf); 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: {{ 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: CSRF 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: CSRF is invalid You can modify the value of timeout in each form, but the default value should work in most cases.","title":"Set Up CSRF"},{"location":"v5/how-to/csrf/#csrf-protection-in-forms","text":"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.","title":"CSRF protection in forms"},{"location":"v5/how-to/csrf/#implement-csrf-protection","text":"Implementing CSRF protection requires three steps: create new field using laminas/laminas-form 's CSRF element validate new field using laminas/laminas-session 's CSRF validator render field using laminas/laminas-form 's FormElement helper","title":"Implement CSRF protection"},{"location":"v5/how-to/csrf/#test-the-implementation","text":"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: CSRF is required and cannot be empty","title":"Test the implementation"},{"location":"v5/how-to/dependency-injection/","text":"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 package focuses only on constructor injection. Usage Dotkernel Admin comes out of the box with the 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 AdminService and config dependencies into a AdminController . use Dot\\DependencyInjection\\Attribute\\Inject; class AdminController implements RequestHandlerInterface { #[Inject( AdminService::class, \"config\", )] public function __construct( protected AdminServiceInterface $adminService, protected array $config, ) { } } 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 . public function getDependencies(): array { return [ 'factories' => [ AdminController::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 controller and so on, simply by registering them in the ConfigProvider .","title":"Inject Dependencies"},{"location":"v5/how-to/dependency-injection/#dependency-injection","text":"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 package focuses only on constructor injection.","title":"Dependency Injection"},{"location":"v5/how-to/dependency-injection/#usage","text":"Dotkernel Admin comes out of the box with the 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 AdminService and config dependencies into a AdminController . use Dot\\DependencyInjection\\Attribute\\Inject; class AdminController implements RequestHandlerInterface { #[Inject( AdminService::class, \"config\", )] public function __construct( protected AdminServiceInterface $adminService, protected array $config, ) { } } 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 . public function getDependencies(): array { return [ 'factories' => [ AdminController::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 controller and so on, simply by registering them in the ConfigProvider .","title":"Usage"},{"location":"v5/how-to/npm_commands/","text":"NPM Commands To install dependencies into the node_modules directory run this command. 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. npm run watch After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. npm run prod","title":"Use NPM Commands"},{"location":"v5/how-to/npm_commands/#npm-commands","text":"To install dependencies into the node_modules directory run this command. 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. npm run watch After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. npm run prod","title":"NPM Commands"},{"location":"v5/installation/composer/","text":"Composer Installation of Packages Composer is required to install Dotkernel Admin. You can install Composer from the official site . 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. 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. 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: 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: composer development-enable You can disable development mode by running: composer development-disable You can check if you have development mode enabled by running: composer development-status","title":"Composer"},{"location":"v5/installation/composer/#composer-installation-of-packages","text":"Composer is required to install Dotkernel Admin. You can install Composer from the official site . First make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.","title":"Composer Installation of Packages"},{"location":"v5/installation/composer/#install-dependencies","text":"Run this command in the command prompt. Use the CLI in order to ensure interactivity for proper configuration. 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. 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: 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.","title":"Install dependencies"},{"location":"v5/installation/composer/#development-mode","text":"If you're installing the project for development, make sure you have development mode enabled, by running: composer development-enable You can disable development mode by running: composer development-disable You can check if you have development mode enabled by running: composer development-status","title":"Development mode"},{"location":"v5/installation/configuration-files/","text":"Configuration Files Prepare config files duplicate config/autoload/local.php.dist as config/autoload/local.php duplicate config/autoload/mail.local.php.dist as config/autoload/mail.local.php If 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. Mail If you want your application to send mail, add valid credentials to the following keys in config/autoload/mail.local.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.","title":"Configuration Files"},{"location":"v5/installation/configuration-files/#configuration-files","text":"","title":"Configuration Files"},{"location":"v5/installation/configuration-files/#prepare-config-files","text":"duplicate config/autoload/local.php.dist as config/autoload/local.php duplicate config/autoload/mail.local.php.dist as config/autoload/mail.local.php If 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.","title":"Prepare config files"},{"location":"v5/installation/configuration-files/#mail","text":"If you want your application to send mail, add valid credentials to the following keys in config/autoload/mail.local.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.","title":"Mail"},{"location":"v5/installation/doctrine-orm/","text":"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. $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: 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. 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. WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n) 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. [OK] Successfully migrated to version: Admin\\Migrations\\Version20240627134952 The migration name Version20240627134952 may differ in future Admin updates. Fixtures Run this command to populate the admin tables with the default values: php bin/doctrine fixtures:execute You should see our galloping horse in the command line. Executing Admin\\Fixtures\\AdminRoleLoader Executing Admin\\Fixtures\\AdminLoader Fixtures have been loaded. .'' ._.-.___.' (`\\ //( ( `' '/ )\\ ).__. ) ' <' `\\ ._/'\\ ` \\ \\","title":"Doctrine ORM"},{"location":"v5/installation/doctrine-orm/#doctrine-orm","text":"This step saves the database connection credentials in an Admin configuration file. We do not cover the creation steps of the database itself.","title":"Doctrine ORM"},{"location":"v5/installation/doctrine-orm/#setup-database","text":"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. $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 ];","title":"Setup database"},{"location":"v5/installation/doctrine-orm/#running-migrations","text":"Run the database migrations by using the following command: 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. 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. WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n) 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. [OK] Successfully migrated to version: Admin\\Migrations\\Version20240627134952 The migration name Version20240627134952 may differ in future Admin updates.","title":"Running migrations"},{"location":"v5/installation/doctrine-orm/#fixtures","text":"Run this command to populate the admin tables with the default values: php bin/doctrine fixtures:execute You should see our galloping horse in the command line. Executing Admin\\Fixtures\\AdminRoleLoader Executing Admin\\Fixtures\\AdminLoader Fixtures have been loaded. .'' ._.-.___.' (`\\ //( ( `' '/ )\\ ).__. ) ' <' `\\ ._/'\\ ` \\ \\","title":"Fixtures"},{"location":"v5/installation/getting-started/","text":"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 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: 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. 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.","title":"Getting Started"},{"location":"v5/installation/getting-started/#clone-the-project","text":"","title":"Clone the project"},{"location":"v5/installation/getting-started/#recommended-development-environment","text":"If you are using Windows as OS on your machine, you can use WSL2 as development environment. Read more here: PHP-Mariadb-on-WLS2 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: 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. 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.","title":"Recommended development environment"},{"location":"v5/installation/installation-intro/","text":"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.","title":"Introduction"},{"location":"v5/installation/installation-intro/#introduction","text":"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.","title":"Introduction"},{"location":"v5/installation/manage-geolite2/","text":"Manage the GeoLite2 databases You can download/update a specific GeoLite2 database, by running the following command where {DATABASE} can be asn , city , country : php bin/cli.php geoip:synchronize -d {DATABASE} You can download/update all GeoLite2 databases at once, by running the following command: 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 . 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: 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.","title":"Manage Geolite2"},{"location":"v5/installation/manage-geolite2/#manage-the-geolite2-databases","text":"You can download/update a specific GeoLite2 database, by running the following command where {DATABASE} can be asn , city , country : php bin/cli.php geoip:synchronize -d {DATABASE} You can download/update all GeoLite2 databases at once, by running the following command: 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 . 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: 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.","title":"Manage the GeoLite2 databases"},{"location":"v5/installation/test-the-installation/","text":"Running the application Do not enable dev mode in production We recommend running your applications in WSL: Make sure you have WSL installed on your system. Currently we provide a distro implementations for AlmaLinux9 . 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: 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: # 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.","title":"Test the Installation"},{"location":"v5/installation/test-the-installation/#running-the-application","text":"Do not enable dev mode in production We recommend running your applications in WSL: Make sure you have WSL installed on your system. Currently we provide a distro implementations for AlmaLinux9 . 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: 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: # 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.","title":"Running the application"},{"location":"v5/introduction/file-structure/","text":"File structure Dotkernel Admin follows the 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: 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 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 doctrine.global.php - Configuration used by Object–relational mapping error-handling.global.php - Configures and activates error logs local.php.dist - Local config file where you can overwrite application name and URL local.test.php.dist - Local configuration for functional tests mail.local.php.dist - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging mezzio.global.php - Mezzio core config file 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 doctrine - Database migrations and fixtures geoip - Holds the GeoLite2 databases lock - Contains lock files generated by dotkernel/dot-cli 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 Setting - Contains functionality for saving and reading display settings Module contents Each Module folder, in turn, should contain the following folders, unless they are empty: src/Controller - Action classes src/Entity - Used by database entities 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 InputFilter , EventListener , Helper , Command , Factory 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 .","title":"File Structure"},{"location":"v5/introduction/file-structure/#file-structure","text":"Dotkernel Admin follows the 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:","title":"File structure"},{"location":"v5/introduction/file-structure/#special-purpose-folders","text":".github - Contains GitHub workflow files .laminas-ci - Contains laminas-ci workflow files","title":"Special purpose folders"},{"location":"v5/introduction/file-structure/#bin-folder","text":"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 doctrine - Used by the doctrine fixtures to populate the database tables","title":"bin folder"},{"location":"v5/introduction/file-structure/#config-folder","text":"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","title":"config folder"},{"location":"v5/introduction/file-structure/#data-folder","text":"This folder is a storage for project data files and service caches. It contains these folders: cache - Cache for e.g. Twig files doctrine - Database migrations and fixtures geoip - Holds the GeoLite2 databases lock - Contains lock files generated by dotkernel/dot-cli AVOID storing sensitive data on the repository!","title":"data folder"},{"location":"v5/introduction/file-structure/#log-folder","text":"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.","title":"log folder"},{"location":"v5/introduction/file-structure/#public-folder","text":"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","title":"public folder"},{"location":"v5/introduction/file-structure/#src-folder","text":"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 Setting - Contains functionality for saving and reading display settings","title":"src folder"},{"location":"v5/introduction/introduction/","text":"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 . Submit user admin and password dotadmin to authenticate yourself.","title":"Introduction"},{"location":"v5/introduction/introduction/#introduction","text":"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 . Submit user admin and password dotadmin to authenticate yourself.","title":"Introduction"},{"location":"v5/introduction/packages/","text":"Packages dotkernel/dot-cache - Provides caching based on symfony/cache dotkernel/dot-cli - Build console applications based on laminas-cli dotkernel/dot-controller - Provides base classes for action based controllers similar to Laminas controller component 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-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 laminas/laminas-i18n - Complete translation suite laminas/laminas-math - Create cryptographically secure pseudo-random numbers and manage big integers mezzio/mezzio - PSR-15 Middleware Microframework 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-doctrine - Use ramsey/uuid as a Doctrine field type roave/psr-container-doctrine - Doctrine Factories for PSR-11 Containers","title":"Packages"},{"location":"v5/introduction/packages/#packages","text":"dotkernel/dot-cache - Provides caching based on symfony/cache dotkernel/dot-cli - Build console applications based on laminas-cli dotkernel/dot-controller - Provides base classes for action based controllers similar to Laminas controller component 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-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 laminas/laminas-i18n - Complete translation suite laminas/laminas-math - Create cryptographically secure pseudo-random numbers and manage big integers mezzio/mezzio - PSR-15 Middleware Microframework 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-doctrine - Use ramsey/uuid as a Doctrine field type roave/psr-container-doctrine - Doctrine Factories for PSR-11 Containers","title":"Packages"},{"location":"v5/introduction/server-requirements/","text":"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 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","title":"Server Requirements"},{"location":"v5/introduction/server-requirements/#server-requirements","text":"For production, we highly recommend a *nix based system.","title":"Server Requirements"},{"location":"v5/introduction/server-requirements/#webserver","text":"","title":"Webserver"},{"location":"v5/introduction/server-requirements/#php-82","text":"Both mod_php and FCGI (FPM) are supported.","title":"PHP >= 8.2"},{"location":"v5/introduction/server-requirements/#required-settings-and-modules-extensions","text":"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)","title":"Required Settings and Modules & Extensions"},{"location":"v5/introduction/server-requirements/#rdbms","text":"Tested with MariaDB 10.11 LTS and MariaDB 11.4 LTS","title":"RDBMS"},{"location":"v5/introduction/server-requirements/#recommended-extensions","text":"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","title":"Recommended extensions"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"../../README.md","title":"Home"},{"location":"#readmemd","text":"","title":"../../README.md"},{"location":"v5/how-to/authorization/","text":"Authorization Guards The packages responsible for restricting access to certain parts of the application are dot-rbac-guard and 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. //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 provides configuration to restrict access to certain actions based on the permissions defined in authorization.global.php so basically we have to add the permissions in the dot-rbac configuration file first to specify the action restriction permissions. // configuration example to restrict certain actions of some routes based on the permissions specified in the dot-rbac configuration file 'rules' => [ [ 'route' => 'account', 'actions' => [//list of actions to apply , or empty array for all actions 'unregister', 'avatar', 'details', 'changePassword' ], 'permissions' => ['authenticated'] ], [ 'route' => 'admin', 'actions' => [ 'deleteAccount' ], 'permissions' => [ 'delete' //list of roles to allow ] ] ]","title":"Configure Authorizations"},{"location":"v5/how-to/authorization/#authorization-guards","text":"The packages responsible for restricting access to certain parts of the application are dot-rbac-guard and 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. //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 provides configuration to restrict access to certain actions based on the permissions defined in authorization.global.php so basically we have to add the permissions in the dot-rbac configuration file first to specify the action restriction permissions. // configuration example to restrict certain actions of some routes based on the permissions specified in the dot-rbac configuration file 'rules' => [ [ 'route' => 'account', 'actions' => [//list of actions to apply , or empty array for all actions 'unregister', 'avatar', 'details', 'changePassword' ], 'permissions' => ['authenticated'] ], [ 'route' => 'admin', 'actions' => [ 'deleteAccount' ], 'permissions' => [ 'delete' //list of roles to allow ] ] ]","title":"Authorization Guards"},{"location":"v5/how-to/creating-fixtures/","text":"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 data/doctrine/fixtures/AdminLoader.php . To list all the available fixtures by order of execution run: php bin/doctrine fixtures:list To execute all fixtures run: php bin/doctrine fixtures:execute To execute a specific fixture, use its class name, like in this example: 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","title":"Create Database Fixtures"},{"location":"v5/how-to/creating-fixtures/#fixtures","text":"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.","title":"Fixtures"},{"location":"v5/how-to/creating-fixtures/#working-with-fixtures","text":"You can find an example of a fixtures class in data/doctrine/fixtures/AdminLoader.php . To list all the available fixtures by order of execution run: php bin/doctrine fixtures:list To execute all fixtures run: php bin/doctrine fixtures:execute To execute a specific fixture, use its class name, like in this example: 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","title":"Working with fixtures"},{"location":"v5/how-to/creating-migrations/","text":"Creating migrations Migrations are used to create and/or edit the database structure. To generate a new migration file, use this command: php vendor/bin/doctrine-migrations migrations:generate It creates a PHP file like this one /data/doctrine/migrations/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 : $this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL'); And its opposite in public function down : $this->addSql('ALTER TABLE admin DROP test');","title":"Create Database Migrations"},{"location":"v5/how-to/creating-migrations/#creating-migrations","text":"Migrations are used to create and/or edit the database structure. To generate a new migration file, use this command: php vendor/bin/doctrine-migrations migrations:generate It creates a PHP file like this one /data/doctrine/migrations/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.","title":"Creating migrations"},{"location":"v5/how-to/creating-migrations/#example","text":"This example creates a new column named test . Add this in public function up : $this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL'); And its opposite in public function down : $this->addSql('ALTER TABLE admin DROP test');","title":"Example"},{"location":"v5/how-to/csrf/","text":"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 's CSRF element validate new field using laminas/laminas-session 's CSRF validator render field using laminas/laminas-form 's FormElement helper Create field Open the form's PHP class and append the following code to the method that initializes the fields (usually init ): $this->add(new \\Laminas\\Form\\Element\\Csrf('exampleCsrf', [ 'csrf_options' => [ 'timeout' => 3600, 'session' => new \\Laminas\\Session\\Container(), ], ])); 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 ): $csrf = new \\Laminas\\InputFilter\\Input('exampleCsrf'); $csrf->setRequired(true); $csrf->getFilterChain() ->attachByName(\\Laminas\\Filter\\StringTrim::class) ->attachByName(\\Laminas\\Filter\\StripTags::class); $csrf->getValidatorChain() ->attachByName(\\Laminas\\Validator\\NotEmpty::class, [ 'message' => '<b>CSRF</b> is required and cannot be empty', ], true) ->attachByName(\\Laminas\\Session\\Validator\\Csrf::class, [ 'name' => 'exampleCsrf', 'message' => '<b>CSRF</b> is invalid', 'session' => new \\Laminas\\Session\\Container(), ], true); $this->add($csrf); 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: {{ 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: CSRF 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: CSRF is invalid You can modify the value of timeout in each form, but the default value should work in most cases.","title":"Set Up CSRF"},{"location":"v5/how-to/csrf/#csrf-protection-in-forms","text":"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.","title":"CSRF protection in forms"},{"location":"v5/how-to/csrf/#implement-csrf-protection","text":"Implementing CSRF protection requires three steps: create new field using laminas/laminas-form 's CSRF element validate new field using laminas/laminas-session 's CSRF validator render field using laminas/laminas-form 's FormElement helper","title":"Implement CSRF protection"},{"location":"v5/how-to/csrf/#test-the-implementation","text":"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: CSRF is required and cannot be empty","title":"Test the implementation"},{"location":"v5/how-to/dependency-injection/","text":"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 package focuses only on constructor injection. Usage Dotkernel Admin comes out of the box with the 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 AdminService and config dependencies into a AdminController . use Dot\\DependencyInjection\\Attribute\\Inject; class AdminController implements RequestHandlerInterface { #[Inject( AdminService::class, \"config\", )] public function __construct( protected AdminServiceInterface $adminService, protected array $config, ) { } } 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 . public function getDependencies(): array { return [ 'factories' => [ AdminController::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 controller and so on, simply by registering them in the ConfigProvider .","title":"Inject Dependencies"},{"location":"v5/how-to/dependency-injection/#dependency-injection","text":"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 package focuses only on constructor injection.","title":"Dependency Injection"},{"location":"v5/how-to/dependency-injection/#usage","text":"Dotkernel Admin comes out of the box with the 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 AdminService and config dependencies into a AdminController . use Dot\\DependencyInjection\\Attribute\\Inject; class AdminController implements RequestHandlerInterface { #[Inject( AdminService::class, \"config\", )] public function __construct( protected AdminServiceInterface $adminService, protected array $config, ) { } } 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 . public function getDependencies(): array { return [ 'factories' => [ AdminController::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 controller and so on, simply by registering them in the ConfigProvider .","title":"Usage"},{"location":"v5/how-to/npm_commands/","text":"NPM Commands To install dependencies into the node_modules directory run this command. 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. npm run watch After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. npm run prod","title":"Use NPM Commands"},{"location":"v5/how-to/npm_commands/#npm-commands","text":"To install dependencies into the node_modules directory run this command. 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. npm run watch After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. npm run prod","title":"NPM Commands"},{"location":"v5/installation/composer/","text":"Composer Installation of Packages Composer is required to install Dotkernel Admin. You can install Composer from the official site . 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. 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. 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: 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: composer development-enable You can disable development mode by running: composer development-disable You can check if you have development mode enabled by running: composer development-status","title":"Composer"},{"location":"v5/installation/composer/#composer-installation-of-packages","text":"Composer is required to install Dotkernel Admin. You can install Composer from the official site . First make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.","title":"Composer Installation of Packages"},{"location":"v5/installation/composer/#install-dependencies","text":"Run this command in the command prompt. Use the CLI in order to ensure interactivity for proper configuration. 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. 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: 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.","title":"Install dependencies"},{"location":"v5/installation/composer/#development-mode","text":"If you're installing the project for development, make sure you have development mode enabled, by running: composer development-enable You can disable development mode by running: composer development-disable You can check if you have development mode enabled by running: composer development-status","title":"Development mode"},{"location":"v5/installation/configuration-files/","text":"Configuration Files Prepare config files duplicate config/autoload/local.php.dist as config/autoload/local.php duplicate config/autoload/mail.local.php.dist as config/autoload/mail.local.php If 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. Mail If you want your application to send mail, add valid credentials to the following keys in config/autoload/mail.local.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.","title":"Configuration Files"},{"location":"v5/installation/configuration-files/#configuration-files","text":"","title":"Configuration Files"},{"location":"v5/installation/configuration-files/#prepare-config-files","text":"duplicate config/autoload/local.php.dist as config/autoload/local.php duplicate config/autoload/mail.local.php.dist as config/autoload/mail.local.php If 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.","title":"Prepare config files"},{"location":"v5/installation/configuration-files/#mail","text":"If you want your application to send mail, add valid credentials to the following keys in config/autoload/mail.local.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.","title":"Mail"},{"location":"v5/installation/doctrine-orm/","text":"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. $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: 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. 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. WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n) 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. [OK] Successfully migrated to version: Admin\\Migrations\\Version20240627134952 The migration name Version20240627134952 may differ in future Admin updates. Fixtures Run this command to populate the admin tables with the default values: php bin/doctrine fixtures:execute You should see our galloping horse in the command line. Executing Admin\\Fixtures\\AdminRoleLoader Executing Admin\\Fixtures\\AdminLoader Fixtures have been loaded. .'' ._.-.___.' (`\\ //( ( `' '/ )\\ ).__. ) ' <' `\\ ._/'\\ ` \\ \\","title":"Doctrine ORM"},{"location":"v5/installation/doctrine-orm/#doctrine-orm","text":"This step saves the database connection credentials in an Admin configuration file. We do not cover the creation steps of the database itself.","title":"Doctrine ORM"},{"location":"v5/installation/doctrine-orm/#setup-database","text":"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. $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 ];","title":"Setup database"},{"location":"v5/installation/doctrine-orm/#running-migrations","text":"Run the database migrations by using the following command: 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. 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. WARNING! You are about to execute a database migration that could result in schema changes and data loss. Are you sure you wish to continue? (y/n) 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. [OK] Successfully migrated to version: Admin\\Migrations\\Version20240627134952 The migration name Version20240627134952 may differ in future Admin updates.","title":"Running migrations"},{"location":"v5/installation/doctrine-orm/#fixtures","text":"Run this command to populate the admin tables with the default values: php bin/doctrine fixtures:execute You should see our galloping horse in the command line. Executing Admin\\Fixtures\\AdminRoleLoader Executing Admin\\Fixtures\\AdminLoader Fixtures have been loaded. .'' ._.-.___.' (`\\ //( ( `' '/ )\\ ).__. ) ' <' `\\ ._/'\\ ` \\ \\","title":"Fixtures"},{"location":"v5/installation/getting-started/","text":"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 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: 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. 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.","title":"Getting Started"},{"location":"v5/installation/getting-started/#clone-the-project","text":"","title":"Clone the project"},{"location":"v5/installation/getting-started/#recommended-development-environment","text":"If you are using Windows as OS on your machine, you can use WSL2 as development environment. Read more here: PHP-Mariadb-on-WLS2 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: 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. 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.","title":"Recommended development environment"},{"location":"v5/installation/installation-intro/","text":"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.","title":"Introduction"},{"location":"v5/installation/installation-intro/#introduction","text":"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.","title":"Introduction"},{"location":"v5/installation/manage-geolite2/","text":"Manage the GeoLite2 databases You can download/update a specific GeoLite2 database, by running the following command where {DATABASE} can be asn , city , country : php bin/cli.php geoip:synchronize -d {DATABASE} You can download/update all GeoLite2 databases at once, by running the following command: 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 . 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: 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.","title":"Manage Geolite2"},{"location":"v5/installation/manage-geolite2/#manage-the-geolite2-databases","text":"You can download/update a specific GeoLite2 database, by running the following command where {DATABASE} can be asn , city , country : php bin/cli.php geoip:synchronize -d {DATABASE} You can download/update all GeoLite2 databases at once, by running the following command: 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 . 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: 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.","title":"Manage the GeoLite2 databases"},{"location":"v5/installation/test-the-installation/","text":"Running the application Do not enable dev mode in production We recommend running your applications in WSL: Make sure you have WSL installed on your system. Currently we provide a distro implementations for AlmaLinux9 . 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: 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: # 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.","title":"Test the Installation"},{"location":"v5/installation/test-the-installation/#running-the-application","text":"Do not enable dev mode in production We recommend running your applications in WSL: Make sure you have WSL installed on your system. Currently we provide a distro implementations for AlmaLinux9 . 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: 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: # 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.","title":"Running the application"},{"location":"v5/introduction/file-structure/","text":"File structure Dotkernel Admin follows the 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: 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 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 doctrine.global.php - Configuration used by Object–relational mapping error-handling.global.php - Configures and activates error logs local.php.dist - Local config file where you can overwrite application name and URL local.test.php.dist - Local configuration for functional tests mail.local.php.dist - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging mezzio.global.php - Mezzio core config file 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 doctrine - Database migrations and fixtures geoip - Holds the GeoLite2 databases lock - Contains lock files generated by dotkernel/dot-cli 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 Setting - Contains functionality for saving and reading display settings Module contents Each Module folder, in turn, should contain the following folders, unless they are empty: src/Controller - Action classes src/Entity - Used by database entities 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 InputFilter , EventListener , Helper , Command , Factory 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 .","title":"File Structure"},{"location":"v5/introduction/file-structure/#file-structure","text":"Dotkernel Admin follows the 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:","title":"File structure"},{"location":"v5/introduction/file-structure/#special-purpose-folders","text":".github - Contains GitHub workflow files .laminas-ci - Contains laminas-ci workflow files","title":"Special purpose folders"},{"location":"v5/introduction/file-structure/#bin-folder","text":"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 doctrine - Used by the doctrine fixtures to populate the database tables","title":"bin folder"},{"location":"v5/introduction/file-structure/#config-folder","text":"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","title":"config folder"},{"location":"v5/introduction/file-structure/#data-folder","text":"This folder is a storage for project data files and service caches. It contains these folders: cache - Cache for e.g. Twig files doctrine - Database migrations and fixtures geoip - Holds the GeoLite2 databases lock - Contains lock files generated by dotkernel/dot-cli AVOID storing sensitive data on the repository!","title":"data folder"},{"location":"v5/introduction/file-structure/#log-folder","text":"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.","title":"log folder"},{"location":"v5/introduction/file-structure/#public-folder","text":"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","title":"public folder"},{"location":"v5/introduction/file-structure/#src-folder","text":"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 Setting - Contains functionality for saving and reading display settings","title":"src folder"},{"location":"v5/introduction/introduction/","text":"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 . Submit user admin and password dotadmin to authenticate yourself.","title":"Introduction"},{"location":"v5/introduction/introduction/#introduction","text":"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 . Submit user admin and password dotadmin to authenticate yourself.","title":"Introduction"},{"location":"v5/introduction/packages/","text":"Packages dotkernel/dot-cache - Provides caching based on symfony/cache dotkernel/dot-cli - Build console applications based on laminas-cli dotkernel/dot-controller - Provides base classes for action based controllers similar to Laminas controller component 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-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 laminas/laminas-i18n - Complete translation suite laminas/laminas-math - Create cryptographically secure pseudo-random numbers and manage big integers mezzio/mezzio - PSR-15 Middleware Microframework 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-doctrine - Use ramsey/uuid as a Doctrine field type roave/psr-container-doctrine - Doctrine Factories for PSR-11 Containers","title":"Packages"},{"location":"v5/introduction/packages/#packages","text":"dotkernel/dot-cache - Provides caching based on symfony/cache dotkernel/dot-cli - Build console applications based on laminas-cli dotkernel/dot-controller - Provides base classes for action based controllers similar to Laminas controller component 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-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 laminas/laminas-i18n - Complete translation suite laminas/laminas-math - Create cryptographically secure pseudo-random numbers and manage big integers mezzio/mezzio - PSR-15 Middleware Microframework 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-doctrine - Use ramsey/uuid as a Doctrine field type roave/psr-container-doctrine - Doctrine Factories for PSR-11 Containers","title":"Packages"},{"location":"v5/introduction/server-requirements/","text":"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 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","title":"Server Requirements"},{"location":"v5/introduction/server-requirements/#server-requirements","text":"For production, we highly recommend a *nix based system.","title":"Server Requirements"},{"location":"v5/introduction/server-requirements/#webserver","text":"","title":"Webserver"},{"location":"v5/introduction/server-requirements/#php-82","text":"Both mod_php and FCGI (FPM) are supported.","title":"PHP >= 8.2"},{"location":"v5/introduction/server-requirements/#required-settings-and-modules-extensions","text":"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)","title":"Required Settings and Modules & Extensions"},{"location":"v5/introduction/server-requirements/#rdbms","text":"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 mysql_native_password=ON","title":"RDBMS"},{"location":"v5/introduction/server-requirements/#recommended-extensions","text":"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","title":"Recommended extensions"}]}
\ No newline at end of file
diff --git a/sitemap.xml b/sitemap.xml
index 0582528..2b222cd 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -2,74 +2,74 @@
https://docs.dotkernel.org/admin-documentation/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/how-to/authorization/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/how-to/creating-fixtures/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/how-to/creating-migrations/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/how-to/csrf/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/how-to/dependency-injection/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/how-to/npm_commands/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/composer/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/configuration-files/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/doctrine-orm/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/getting-started/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/installation-intro/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/manage-geolite2/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/installation/test-the-installation/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/introduction/file-structure/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/introduction/introduction/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/introduction/packages/
- 2024-11-26
+ 2025-01-06
https://docs.dotkernel.org/admin-documentation/v5/introduction/server-requirements/
- 2024-11-26
+ 2025-01-06
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index f190bd5..261b8e7 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ
diff --git a/v5/introduction/server-requirements/index.html b/v5/introduction/server-requirements/index.html
index a38f799..794d794 100644
--- a/v5/introduction/server-requirements/index.html
+++ b/v5/introduction/server-requirements/index.html
@@ -467,7 +467,12 @@
Required Settings and Modules
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
+
+mysql_native_password=ON
Recommended extensions