diff --git a/docs/book/v5/how-to/creating-fixtures.md b/docs/book/v5/how-to/creating-fixtures.md new file mode 100644 index 0000000..c80a750 --- /dev/null +++ b/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 diff --git a/docs/book/v5/how-to/creating-migrations.md b/docs/book/v5/how-to/creating-migrations.md new file mode 100644 index 0000000..a65ae07 --- /dev/null +++ b/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'); +``` diff --git a/docs/book/v5/installation/composer.md b/docs/book/v5/installation/composer.md index 29ffa2f..75ae8b4 100644 --- a/docs/book/v5/installation/composer.md +++ b/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. diff --git a/docs/book/v5/installation/configuration-files.md b/docs/book/v5/installation/configuration-files.md index b8a7e83..001410e 100644 --- a/docs/book/v5/installation/configuration-files.md +++ b/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. diff --git a/docs/book/v5/installation/doctrine-orm.md b/docs/book/v5/installation/doctrine-orm.md index 156d709..f1d41a8 100644 --- a/docs/book/v5/installation/doctrine-orm.md +++ b/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 diff --git a/docs/book/v5/installation/getting-started.md b/docs/book/v5/installation/getting-started.md index 3e276a0..bc3bb2e 100644 --- a/docs/book/v5/installation/getting-started.md +++ b/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. + diff --git a/docs/book/v5/installation/installation-intro.md b/docs/book/v5/installation/installation-intro.md new file mode 100644 index 0000000..b6f2e1b --- /dev/null +++ b/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. diff --git a/docs/book/v5/installation/manage-geolite2.md b/docs/book/v5/installation/manage-geolite2.md index cd2ec8a..576b665 100644 --- a/docs/book/v5/installation/manage-geolite2.md +++ b/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. diff --git a/docs/book/v5/installation/test-the-installation.md b/docs/book/v5/installation/test-the-installation.md index 002743c..b37d7d6 100644 --- a/docs/book/v5/installation/test-the-installation.md +++ b/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. diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 2746416..1d8be7c 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 87dc220..8171797 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,7 @@ 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 @@ -21,6 +22,8 @@ nav: - "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