From ef9c7b25c4e90e713b367a929b945b57dd52b248 Mon Sep 17 00:00:00 2001 From: bidi Date: Wed, 13 Nov 2024 12:29:35 +0200 Subject: [PATCH 1/7] updated intro, how to Signed-off-by: bidi --- docs/book/v5/how-to/authorization.md | 54 ++++++++++++++++ .../book/v5/{core-features => how-to}/csrf.md | 0 docs/book/v5/how-to/dependency-injection.md | 56 +++++++++++++++++ docs/book/v5/how-to/npm_commands.md | 22 +++++++ docs/book/v5/introduction/file-structure.md | 61 +++++++++++++++++++ docs/book/v5/introduction/introduction.md | 4 +- docs/book/v5/introduction/packages.md | 27 ++++++++ mkdocs.yml | 9 ++- 8 files changed, 230 insertions(+), 3 deletions(-) create mode 100644 docs/book/v5/how-to/authorization.md rename docs/book/v5/{core-features => how-to}/csrf.md (100%) create mode 100644 docs/book/v5/how-to/dependency-injection.md create mode 100644 docs/book/v5/how-to/npm_commands.md create mode 100644 docs/book/v5/introduction/file-structure.md create mode 100644 docs/book/v5/introduction/packages.md diff --git a/docs/book/v5/how-to/authorization.md b/docs/book/v5/how-to/authorization.md new file mode 100644 index 0000000..b7b1f2c --- /dev/null +++ b/docs/book/v5/how-to/authorization.md @@ -0,0 +1,54 @@ +# Authorization Guards + +The packages responsible for restricting access to certain parts of the application are [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) and [dot-rbac](https://github.com/dotkernel/dot-rbac). +These packages work together to create an infrastructure that is customizable and diversified to manage user access to the platform by specifying the type of role the user has. + +The `authorization.global.php` file provides multiple configurations specifying multiple roles as well as the types of permissions to which these roles have access. + +```php +//example of a flat RBAC model that specifies two types of roles as well as their permission + 'roles' => [ + 'admin' => [ + 'permissions' => [ + 'authenticated', + 'edit', + 'delete', + //etc.. + ] + ], + 'user' => [ + 'permissions' => [ + 'authenticated', + //etc.. + ] + ] + ] +``` + +The `authorization-guards.global.php` file 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. + +```php +// 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 + ] + ] + ] +``` diff --git a/docs/book/v5/core-features/csrf.md b/docs/book/v5/how-to/csrf.md similarity index 100% rename from docs/book/v5/core-features/csrf.md rename to docs/book/v5/how-to/csrf.md diff --git a/docs/book/v5/how-to/dependency-injection.md b/docs/book/v5/how-to/dependency-injection.md new file mode 100644 index 0000000..0bc0817 --- /dev/null +++ b/docs/book/v5/how-to/dependency-injection.md @@ -0,0 +1,56 @@ +# Dependency Injection + +Dependency injection is a design pattern used in software development to implement inversion of control. +In simpler terms, it's the act of providing dependencies for an object during instantiation. + +In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter injection and property injection. + +Dotkernel Admin, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection. + +## Usage + +**Dotkernel Admin** comes out of the box with the [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all the functionality injecting dependencies into any object you want. + +`dot-dependency-injection` determines the dependencies by looking at the `#[Inject]` attribute, added to the constructor of a class. +Each dependency is specified as a separate parameter of the `#[Inject]` attribute. + +For our example we will inject `AdminService` and `config` dependencies into a `AdminController`. + +```php +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`. + +```php +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`. diff --git a/docs/book/v5/how-to/npm_commands.md b/docs/book/v5/how-to/npm_commands.md new file mode 100644 index 0000000..f03d9cf --- /dev/null +++ b/docs/book/v5/how-to/npm_commands.md @@ -0,0 +1,22 @@ +# NPM Commands + +To install dependencies into the `node_modules` directory run this command. + +```shell +npm install +``` + +> If `npm install` fails, this could be caused by user permissions of npm. +> The recommended way to install npm is through `Node Version Manager`. + +The watch command compiles the components then monitors the files for changes and recompiles them. + +```shell +npm run watch +``` + +After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. + +```shell +npm run prod +``` diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md new file mode 100644 index 0000000..2746416 --- /dev/null +++ b/docs/book/v5/introduction/file-structure.md @@ -0,0 +1,61 @@ +# File structure + +Dotkernel Admin follows the [PSR-4](https://www.php-fig.org/psr/psr-4/) standards. + +It is considered good practice to standardize the file structure of projects. + +When using Dotkernel Admin the following structure is installed by default: + +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/Admin/file-structure-dk-Admin.png) + +## Main directories + +* `bin` - Executable files from CLI +* `config` - Various configuration files +* `data` - Should contain project-related data (AVOID storing sensitive data on VCS) +* `log` - Storage of log files generated by dot-error-log library +* `public` - Publicly visible files. The webserver need to have this folder as www-document root folder. +* `src` - Should contain the source code files +* `test` - Should contain the test files + +## Special purpose folders + +* `.github` - Contains workflow files +* `.laminas-ci` - Contains laminas-ci workflow files + +## `src` directory + +This directory contains all source code related to the Module. +It should contain the following directories, if they are not empty: + +* Handler - Action classes (similar to Controllers but can only perform one action) +* Entity - Database entities +* Service - Service classes +* Collection - Database entities collections +* Repository - Entity repository folder + +> The above example lists just a part of the directories in a project, but it should give you an idea of what the structure should look like. + +Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc. + +The `src` directory should also contain 2 files: + +* `ConfigProvider.php` - Provides configuration data +* `RoutesDelegator.php` - Module main routes entry file + +## `templates` directory for modules + +This directory contains the template files, used for example to help render e-mail templates. + +> Dotkernel Admin uses `twig` as Templating Engine. +> All template files have the extension `.html.twig`. + +## `data` directory + +This directory contains project-related data, like cache and file uploads. + +We recommend using the following directory structure: + +* `data/cache` - Location where caches are stored +* `data/doctrine` - Fixtures and migrations +* `data/lock` - Lock files generated by [dotkernel/dot-cli](https://docs.dotkernel.org/dot-cli/v3/lock-files/) diff --git a/docs/book/v5/introduction/introduction.md b/docs/book/v5/introduction/introduction.md index be2c531..33603a4 100644 --- a/docs/book/v5/introduction/introduction.md +++ b/docs/book/v5/introduction/introduction.md @@ -1,3 +1,5 @@ # Introduction -Dotkernel web starter package suitable for admin applications. +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. diff --git a/docs/book/v5/introduction/packages.md b/docs/book/v5/introduction/packages.md new file mode 100644 index 0000000..fb17618 --- /dev/null +++ b/docs/book/v5/introduction/packages.md @@ -0,0 +1,27 @@ +# Packages + +* `dotkernel/dot-cache` - Provides caching based on symfony/cache +* `dotkernel/dot-cli` - Build console applications based on laminas-cli +* `dotkernel/dot-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 diff --git a/mkdocs.yml b/mkdocs.yml index 2b595b9..87dc220 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,6 +11,8 @@ nav: - Introduction: v5/introduction/introduction.md - Overview: - "Server Requirements": v5/introduction/server-requirements.md + - "File Structure": v5/introduction/file-structure.md + - "Packages": v5/introduction/packages.md - Installation: - "Getting Started": v5/installation/getting-started.md - "Composer": v5/installation/composer.md @@ -18,8 +20,11 @@ nav: - "Doctrine ORM": v5/installation/doctrine-orm.md - "Manage Geolite2": v5/installation/manage-geolite2.md - "Test the Installation": v5/installation/test-the-installation.md - - Core Features: - - "CSRF": v5/core-features/csrf.md + - Hot to: + - "Configure Authorizations": v5/how-to/authorization.md + - "Use NPM Commands": v5/how-to/npm_commands.md + - "Inject Dependencies": v5/how-to/dependency-injection.md + - "Set Up CSRF": v5/how-to/csrf.md site_name: admin site_description: "DotKernel Admin" repo_url: "https://github.com/dotkernel/admin" From 2c30012b4223452f570a3442b522bc1400a981e7 Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 14 Nov 2024 18:01:30 +0200 Subject: [PATCH 2/7] updated installation, howto Signed-off-by: bidi --- docs/book/v5/how-to/creating-fixtures.md | 32 +++++++++ docs/book/v5/how-to/creating-migrations.md | 29 ++++++++ docs/book/v5/installation/composer.md | 2 +- .../v5/installation/configuration-files.md | 27 +++++-- docs/book/v5/installation/doctrine-orm.md | 70 ++++++++++++++----- docs/book/v5/installation/getting-started.md | 20 +++++- .../v5/installation/installation-intro.md | 11 +++ docs/book/v5/installation/manage-geolite2.md | 36 +++++----- .../v5/installation/test-the-installation.md | 54 +++++++------- docs/book/v5/introduction/file-structure.md | 2 +- mkdocs.yml | 3 + 11 files changed, 217 insertions(+), 69 deletions(-) create mode 100644 docs/book/v5/how-to/creating-fixtures.md create mode 100644 docs/book/v5/how-to/creating-migrations.md create mode 100644 docs/book/v5/installation/installation-intro.md 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 From 8728e20aa358a4a78d3bc35dde57ea6115bb78e3 Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 14 Nov 2024 18:04:19 +0200 Subject: [PATCH 3/7] fixed linting Signed-off-by: bidi --- docs/book/v5/installation/configuration-files.md | 4 ++-- docs/book/v5/installation/getting-started.md | 1 - 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/book/v5/installation/configuration-files.md b/docs/book/v5/installation/configuration-files.md index 001410e..ceb7023 100644 --- a/docs/book/v5/installation/configuration-files.md +++ b/docs/book/v5/installation/configuration-files.md @@ -2,8 +2,8 @@ ## 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` +- 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. diff --git a/docs/book/v5/installation/getting-started.md b/docs/book/v5/installation/getting-started.md index bc3bb2e..bf4ce37 100644 --- a/docs/book/v5/installation/getting-started.md +++ b/docs/book/v5/installation/getting-started.md @@ -26,4 +26,3 @@ Resolving deltas: 100% (3359/3359), done. ``` You can already open the project in your preferred IDE to double-check the files were copied correctly. - From ce7f9b0b630f0690bca2179979c0ee092573dd66 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 15 Nov 2024 17:45:07 +0200 Subject: [PATCH 4/7] updated intro Signed-off-by: bidi --- docs/book/v5/introduction/introduction.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/book/v5/introduction/introduction.md b/docs/book/v5/introduction/introduction.md index 33603a4..02a0d9d 100644 --- a/docs/book/v5/introduction/introduction.md +++ b/docs/book/v5/introduction/introduction.md @@ -3,3 +3,5 @@ Dotkernel Admin is an application (skeleton) intended for quickly setting up an administration site for your platform. It's a fast and reliable way to manage records in your database with a simple table-based approach, and also to build reports and graphs to monitor your platform. The many graphical components at your disposal ensure an intuitive user experience. + +Check out our [demo](https://v5.dotkernel.net/). From 3e87ecc351601884baa9b9c56c3ebd50eb2ad97a Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 15 Nov 2024 17:51:10 +0200 Subject: [PATCH 5/7] typo Signed-off-by: bidi --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 8171797..48205b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,7 +21,7 @@ nav: - "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: + - How 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 From 3b63483ee3abea1b4fc689646e1ecfd91c319574 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 15 Nov 2024 17:57:50 +0200 Subject: [PATCH 6/7] updated intro Signed-off-by: bidi --- docs/book/v5/introduction/introduction.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/book/v5/introduction/introduction.md b/docs/book/v5/introduction/introduction.md index 02a0d9d..564ae8b 100644 --- a/docs/book/v5/introduction/introduction.md +++ b/docs/book/v5/introduction/introduction.md @@ -4,4 +4,6 @@ Dotkernel Admin is an application (skeleton) intended for quickly setting up an It's a fast and reliable way to manage records in your database with a simple table-based approach, and also to build reports and graphs to monitor your platform. The many graphical components at your disposal ensure an intuitive user experience. -Check out our [demo](https://v5.dotkernel.net/). +> Check out our [demo](https://admin5.dotkernel.net/). +> +> Submit user `admin` and password `dotadmin` to authenticate yourself. From fd31b435eb316a555895084fd6dc21efbe7e3615 Mon Sep 17 00:00:00 2001 From: bidi Date: Fri, 15 Nov 2024 17:59:49 +0200 Subject: [PATCH 7/7] fixed linting Signed-off-by: bidi --- docs/book/v5/introduction/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/book/v5/introduction/introduction.md b/docs/book/v5/introduction/introduction.md index 564ae8b..4650cb1 100644 --- a/docs/book/v5/introduction/introduction.md +++ b/docs/book/v5/introduction/introduction.md @@ -5,5 +5,5 @@ It's a fast and reliable way to manage records in your database with a simple ta The many graphical components at your disposal ensure an intuitive user experience. > Check out our [demo](https://admin5.dotkernel.net/). -> +> > Submit user `admin` and password `dotadmin` to authenticate yourself.