updated installation, howto

Signed-off-by: bidi <[email protected]>

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

@@ -0,0 +1,32 @@
+# Fixtures
+
+> Fixtures are used to seed the database with initial values and should only be executed ONCE each, after migrating the database.
+
+Seeding the database is done with the help of our custom package `dotkernel/dot-data-fixtures` built on top of `doctrine/data-fixtures`.
+See below on how to use our CLI command for listing and executing Doctrine data fixtures.
+
+## Working with fixtures
+
+You can find an example of a fixtures class in `data/doctrine/fixtures/AdminLoader.php`.
+
+To list all the available fixtures by order of execution run:
+
+```shell
+php bin/doctrine fixtures:list
+```
+
+To execute all fixtures run:
+
+```shell
+php bin/doctrine fixtures:execute
+```
+
+To execute a specific fixture, use its class name, like in this example:
+
+```shell
+php bin/doctrine fixtures:execute --class=AdminLoader
+```
+
+Fixtures can and should be ordered to ensure database consistency.
+More on ordering fixtures can be found here :
+https://www.doctrine-project.org/projects/doctrine-data-fixtures/en/latest/how-to/fixture-ordering.html#fixture-ordering

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

@@ -0,0 +1,29 @@
+# Creating migrations
+
+Migrations are used to create and/or edit the database structure.
+To generate a new migration file, use this command:
+
+```shell
+php vendor/bin/doctrine-migrations migrations:generate
+```
+
+It creates a PHP file like this one `/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`:
+
+```shell
+$this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL');
+```
+
+And its opposite in `public function down`:
+
+```shell
+$this->addSql('ALTER TABLE admin DROP test');
+```

docs/book/v5/installation/composer.md

@@ -1,6 +1,6 @@
 # Composer Installation of Packages
 
-Composer is required to install Dotkernel `admin`. You can install Composer from the [official site](https://getcomposer.org/).
+Composer is required to install Dotkernel Admin. You can install Composer from the [official site](https://getcomposer.org/).
 
 > First make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
 

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

@@ -3,15 +3,30 @@
 ## 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`
 
-### Note
+> 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.
 
-> if your Admin will send emails, make sure to fill in SMTP connection params
+> **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`
+> this creates a new in-memory database that your tests will run on.
 
-* **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`
+## Mail
 
-### Note
+If you want your application to send mail, add valid credentials to the following keys in `config/autoload/mail.local.php`
 
-> this creates a new in-memory database that your tests will run on.
+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.

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

@@ -1,47 +1,85 @@
 # 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
 
-Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`.
+Create a new MySQL database and set its collation to `utf8mb4_general_ci`.
 
-Create a new MySQL database - set collation to `utf8mb4_general_ci`
+Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`.
+Below is the item you need to focus on.
+
+> `my_database`, `my_user`, `my_password` are provided only as an example.
+
+```php
+$databases = [
+    'default' => [
+        'host'     => 'localhost',
+        'dbname'   => 'my_database',
+        'user'     => 'my_user',
+        'password' => 'my_password',
+        'port'     => 3306,
+        'driver'   => 'pdo_mysql',
+        'charset'  => 'utf8mb4',
+        'collate'  => 'utf8mb4_general_ci',
+    ],
+    // you can add more database connections into this array
+];
+```
 
 ## Running migrations
 
 Run the database migrations by using the following command:
 
 ```shell
-php bin/doctrine-migrations migrate
+php vendor/bin/doctrine-migrations migrate
 ```
 
-This command will prompt you to confirm that you want to run it.
+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 are about to execute a migration in database "..." that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) [yes]:
+```shell
+WARNING! You have x previously executed migrations in the database that are not registered migrations.
+  {migration list}
+Are you sure you wish to continue? (y/n)
+```
 
-Hit `Enter` to confirm the operation.
+When using an empty database, you will get this confirmation message instead.
 
-## Executing fixtures
+```shell
+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)
+```
 
-**Fixtures are used to seed the database with initial values and should be executed after migrating the database.**
+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.
 
-To list all the fixtures, run:
+If everything ran correctly, you will get this confirmation.
 
 ```shell
-php bin/doctrine fixtures:list
+[OK] Successfully migrated to version: Admin\Migrations\Version20240627134952
 ```
 
-This will output all the fixtures in the order of execution.
+> The migration name `Version20240627134952` may differ in future Admin updates.
 
-To execute all fixtures, run:
+## Fixtures
+
+Run this command to populate the admin tables with the default values:
 
 ```shell
 php bin/doctrine fixtures:execute
 ```
 
-To execute a specific fixture, run:
+You should see our galloping horse in the command line.
 
 ```shell
-php bin/doctrine fixtures:execute --class=FixtureClassName
+Executing Admin\Fixtures\AdminRoleLoader
+Executing Admin\Fixtures\AdminLoader
+Fixtures have been loaded.
+                .''
+      ._.-.___.' (`\
+     //(        ( `'
+    '/ )\ ).__. )
+    ' <' `\ ._/'\
+       `   \     \
 ```
-
-More details on how fixtures work can be found here: https://github.com/dotkernel/dot-data-fixtures#creating-fixtures

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

@@ -5,9 +5,25 @@
 > If you are using Windows as OS on your machine, you can use WSL2 as development environment.
 > Read more here: [PHP-Mariadb-on-WLS2](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/)
 
-Using your terminal, navigate inside the directory you want to download the project files into. Make sure that the
-directory is empty before proceeding to the download process. Once there, run the following command:
+Using your terminal, navigate inside the directory you want to download the project files into.
+Make sure that the directory is empty before proceeding to the download process.
+Once there, run the following command:
 
 ```shell
 git clone https://github.com/dotkernel/admin.git .
 ```
+
+If everything ran correctly, you can expect to see an output like this, though the numbers may differ.
+
+```shell
+Cloning into '.'...
+remote: Enumerating objects: 6538, done.
+remote: Counting objects: 100% (1652/1652), done.
+remote: Compressing objects: 100% (785/785), done.
+remote: Total 6538 (delta 804), reused 1417 (delta 748), pack-reused 4886 (from 1)
+Receiving objects: 100% (6538/6538), 11.84 MiB | 16.52 MiB/s, done.
+Resolving deltas: 100% (3359/3359), done.
+```
+
+You can already open the project in your preferred IDE to double-check the files were copied correctly.
+

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

@@ -0,0 +1,11 @@
+# Introduction
+
+In this tutorial, we will install Dotkernel Admin from scratch.
+We will focus on these tasks:
+
+- Highlight 3rd party tools required for the installation.
+- Provide all the relevant commands with expected responses.
+- Configure the development environment.
+- Run the project.
+
+By the end of this tutorial you will have a fully-functional Dotkernel Admin on your selected environment and can begin coding.

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

@@ -1,27 +1,31 @@
-# Manage GeoLite2 database
+# Manage the GeoLite2 databases
 
-You can download/update a specific GeoLite2 database, by running the following command:
+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}
-
-Where _{DATABASE}_ takes one of the following values: `asn`, `city`, `country`.
+```shell
+php bin/cli.php geoip:synchronize -d {DATABASE}
+```
 
 You can download/update all GeoLite2 databases at once, by running the following command:
 
-    php bin/cli.php geoip:synchronize
+```shell
+php bin/cli.php geoip:synchronize
+```
+
+The output should be similar to the below, displaying per row: `database identifier`: `previous build datetime` -> `current build datetime`.
 
-The output should be similar to the below, displaying per
-row: `database identifier`: `previous build datetime` -> `current build datetime`.
+```shell
+asn: n/a -> 2024-11-01 02:29:44
+city: n/a -> 2024-11-01 02:29:31
+country: n/a -> 2024-11-01 02:25:09
+```
 
-> asn: n/a -> 2021-07-01 02:09:34
->
-> city: n/a -> 2021-07-01 02:09:20
->
-> country: n/a -> 2021-07-01 02:05:12
+> `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
+```shell
+php bin/cli.php help geoip:synchronize
+```
 
-**Tip**: If you setup the synchronizer command as a cronjob, you can add the `-q|--quiet` option, and it will output
-data only if an error has occurred.
+**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.

docs/book/v5/installation/test-the-installation.md

@@ -1,43 +1,43 @@
-# Testing (Running)
+# Running the application
 
-Note: **Do not enable dev mode in production**
+> **Do not enable dev mode in production**
 
-- Run the following command in your project's directory to start PHPs built-in server:
+We recommend running your applications in WSL:
 
-      php -S 0.0.0.0:8080 -t public
+- Make sure you have [WSL](https://github.com/dotkernel/development/blob/main/wsl/README.md) installed on your system.
+- Currently we provide a distro implementations for [AlmaLinux9](https://github.com/dotkernel/development/blob/main/wsl/os/almalinux9/README.md).
+- Install the application in a virtualhost as recommended by the chosen distro.
+- Set `$baseUrl` in **config/autoload/local.php** to the address of the virtualhost.
+- Run the application by opening the virtualhost address in your browser.
 
-> Running command `composer serve` will do the exact same, but the above is faster.
-
-`0.0.0.0` means that the server is open to all incoming connections
-`127.0.0.1` means that the server can only be accessed locally (localhost only)
-`8080` the port on which the server is started (the listening port for the server)
-
-**NOTE:**
-If you are still getting exceptions or errors regarding some missing services, try running the following command
-
-    php bin/clear-config-cache.php
+You should see the `Dotkernel admin` login page.
 
-> 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 are getting exceptions or errors regarding some missing services, try running the following command:
 
-- Open a web browser and visit `http://localhost:8080/`
+```shell
+sudo php bin/clear-config-cache.php
+```
 
-You should see the `Dotkernel admin` login page.
+> 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 migrations you will have an admin user in the database with the following credentials:
+If you ran the fixtures you will have an admin user in the database with the following credentials:
 
 - **User**: `admin`
 - **Password**: `dotadmin`
 
-**NOTE:**
+> **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:
 
-- **Production only**: Make sure you modify the default admin credentials.
-- **Development only**: `session.cookie_secure` does not work locally so make sure you modify your `local.php`, as per the following:
+```php
+# other code
 
-      return [
-        'session_config' => [
-            'cookie_secure' => false,
-        ]
-      ];
+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.

docs/book/v5/introduction/file-structure.md

@@ -6,7 +6,7 @@ It is considered good practice to standardize the file structure of projects.
 
 When using Dotkernel Admin the following structure is installed by default:
 
-![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/Admin/file-structure-dk-Admin.png)
+![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/file-structure-dk-admin.jpg)
 
 ## Main directories
 

mkdocs.yml

@@ -14,13 +14,16 @@ nav:
           - "File Structure": v5/introduction/file-structure.md
           - "Packages": v5/introduction/packages.md
       - Installation:
+          - "Introduction": v5/installation/installation-intro.md
           - "Getting Started": v5/installation/getting-started.md
           - "Composer": v5/installation/composer.md
           - "Configuration Files": v5/installation/configuration-files.md
           - "Doctrine ORM": v5/installation/doctrine-orm.md
           - "Manage Geolite2": v5/installation/manage-geolite2.md
           - "Test the Installation": v5/installation/test-the-installation.md
       - Hot to:
+          - "Create Database Migrations": v5/how-to/creating-migrations.md
+          - "Create Database Fixtures": v5/how-to/creating-fixtures.md
           - "Configure Authorizations": v5/how-to/authorization.md
           - "Use NPM Commands": v5/how-to/npm_commands.md
           - "Inject Dependencies": v5/how-to/dependency-injection.md