diff --git a/docs/book/v6/how-to/authorization.md b/docs/book/v6/how-to/authorization.md new file mode 100644 index 0000000..1850917 --- /dev/null +++ b/docs/book/v6/how-to/authorization.md @@ -0,0 +1,41 @@ +# Authorization Guards + +The packages responsible for restricting access to certain parts of the application are [dot-rbac-guard](https://github.com/dotkernel/dot-rbac-guard) and [dot-rbac](https://github.com/dotkernel/dot-rbac). These packages work together to create an infrastructure that is customizable and diversified to manage user access to the platform by specifying the type of role the user has. + +The `authorization.global.php` file provides multiple configurations specifying multiple roles as well as the types of permissions to which these roles have access. + +```php +//example of a flat RBAC model that specifies two types of roles as well as their permission + 'roles' => [ + 'admin' => [ + 'permissions' => [ + 'authenticated', + 'edit', + 'delete', + //etc.. + ] + ], + 'user' => [ + 'permissions' => [ + 'authenticated', + //etc.. + ] + ] + ] +``` + +The `authorization-guards.global.php` file defines which permissions are required to access specific route handlers. These permissions must first be declared in the authorization.global.php (dot-rbac) configuration file. + +```php +// Example configuration granting access to route handlers based on permissions. + 'rules' => [ + 'admin::admin-login-form' => [], + 'admin::admin-login' => [], + 'admin::admin-create-form' => ['authenticated'], + 'admin::admin-create' => ['authenticated'], + 'admin::admin-delete-form' => ['authenticated'], + 'admin::admin-delete' => ['authenticated'], + 'admin::admin-edit-form' => ['authenticated'], + 'admin::admin-edit' => ['authenticated'], + ] +``` diff --git a/docs/book/v6/how-to/creating-fixtures.md b/docs/book/v6/how-to/creating-fixtures.md new file mode 100644 index 0000000..8fafd6c --- /dev/null +++ b/docs/book/v6/how-to/creating-fixtures.md @@ -0,0 +1,31 @@ +# Fixtures + +> Fixtures are used to seed the database with initial values and should only be executed ONCE each, after migrating the database. + +Seeding the database is done with the help of our custom package `dotkernel/dot-data-fixtures` built on top of `doctrine/data-fixtures`. See below on how to use our CLI command for listing and executing Doctrine data fixtures. + +## Working with fixtures + +You can find an example of a fixtures class in `src/Core/src/App/src/Fixture/AdminLoader.php`. + +To list all the available fixtures by order of execution run: + +```shell +php ./bin/doctrine fixtures:list +``` + +To execute all fixtures run: + +```shell +php ./bin/doctrine fixtures:execute +``` + +To execute a specific fixture, use its class name, like in this example: + +```shell +php ./bin/doctrine fixtures:execute --class=AdminLoader +``` + +Fixtures can and should be ordered to ensure database consistency. +More on ordering fixtures can be found here : +https://www.doctrine-project.org/projects/doctrine-data-fixtures/en/latest/how-to/fixture-ordering.html#fixture-ordering diff --git a/docs/book/v6/how-to/creating-migrations.md b/docs/book/v6/how-to/creating-migrations.md new file mode 100644 index 0000000..12ddb09 --- /dev/null +++ b/docs/book/v6/how-to/creating-migrations.md @@ -0,0 +1,29 @@ +# Creating migrations + +Migrations are used to create and/or edit the database structure. +To generate a new migration file, use this command: + +```shell +php ./vendor/bin/doctrine-migrations migrations:generate +``` + +It creates a PHP file like this one `src/Core/src/App/src/Migration/Version20240627134952.php` that can then be edited in the IDE. +You can add new queries in: + +- `public function up` - these are executed when the migration is run. +- `public function down` - these are optional queries that undo the above changes. + +## Example + +This example creates a new column named `test`. +Add this in `public function up`: + +```shell +$this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL'); +``` + +And its opposite in `public function down`: + +```shell +$this->addSql('ALTER TABLE admin DROP test'); +``` diff --git a/docs/book/v6/how-to/csrf.md b/docs/book/v6/how-to/csrf.md new file mode 100644 index 0000000..49dcd8d --- /dev/null +++ b/docs/book/v6/how-to/csrf.md @@ -0,0 +1,73 @@ +# CSRF protection in forms + +A Cross-Site Request Forgery (CSRF) attack is a type of security vulnerability that tricks a user into performing +actions on a web application in which they are authenticated, without their knowledge or consent. + +Web applications can protect users against these types of attacks by implementing CSRF tokens in their forms which are +known only to the application that generated them and must be included when submitting forms. With each visit, a new +CSRF token is added to the form so tokens are not reusable between forms. Missing to provide a valid CSRF token will +result in a form validation error. + +## Implement CSRF protection + +Implementing CSRF protection requires three steps: + +- create new field using [laminas/laminas-form](https://github.com/laminas/laminas-form)'s [CSRF](https://github.com/laminas/laminas-form/blob/3.21.x/src/Element/Csrf.php) element +- validate new field using [laminas/laminas-session](https://github.com/laminas/laminas-session)'s +[CSRF](https://github.com/laminas/laminas-session/blob/2.22.x/src/Validator/Csrf.php) validator +- render field using [laminas/laminas-form](https://github.com/laminas/laminas-form)'s [FormElement](https://github.com/laminas/laminas-form/blob/3.21.x/src/View/Helper/FormElement.php) helper + +### Create field + +Open the form's PHP class and append the following code to the method that initializes the fields (usually `init`): + +```php +$this->add( + (new \Laminas\Form\Element\Csrf('exampleCsrf')) + ->setOptions([ + 'csrf_options' => ['timeout' => 3600, 'session' => new Container()], + ]) + ->setAttribute('required', true) +); +``` + +where `exampleCsrf` should be a suggestive name that describes the purpose of the field (example: `forgotPasswordCsrf`). + +### Validate field + +Open the InputFilter that validates the form fields and append the following code to the method that initializes the +fields (usually `init`): + +```php +$this->add(new \Admin\App\InputFilter\Input\CsrfInput('exampleCsrf')); +``` + +where `exampleCsrf` must match the CSRF field's name in the form. + +> Don't forget to modify both occurrences in this file. + +> Make sure that you validate the form using its `isValid` method in the handler/controller where it is submitted. + +### Render field + +Open the template that renders your form and add the following code somewhere between the form's opening and closing tags: + +```text +{{ formElement(form.get('exampleCsrf')) }} +``` + +## Test the implementation + +Access your form from the browser and view its source. You should see a new hidden field, called `exampleCsrf` (or however you named it). After filling out the form, submitting it should work as before. + +In order to make sure that the new CSRF field works as expected, you can inspect the form using your browser's `Developer tools` and modify its value in any way. Submitting a filled out form should result in a validation error: + +> This field is required and cannot be empty. + +### Timeout + +Note the `timeout` option in your PHP form's `exampleCsrf` field, with its default value set to **3600**. This represents the value in seconds for how long the token is valid. Submitting a form that has been rendered for longer than this value will result in a validation error: + +> Invalid CSRF. + +You can modify the value of `timeout` in each form, but the default value should work in most cases. diff --git a/docs/book/v6/how-to/dependency-injection.md b/docs/book/v6/how-to/dependency-injection.md new file mode 100644 index 0000000..1d20e15 --- /dev/null +++ b/docs/book/v6/how-to/dependency-injection.md @@ -0,0 +1,55 @@ +# Dependency Injection + +Dependency injection is a design pattern used in software development to implement inversion of control. +In simpler terms, it's the act of providing dependencies for an object during instantiation. + +In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter injection and property injection. + +Dotkernel Admin, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection. + +## Usage + +**Dotkernel Admin** comes out of the box with the [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all the functionality injecting dependencies into any object you want. + +`dot-dependency-injection` determines the dependencies by looking at the `#[Inject]` attribute, added to the constructor of a class. +Each dependency is specified as a separate parameter of the `#[Inject]` attribute. + +For our example we will inject `RouterInterface` and `AuthenticationServiceInterface` dependencies into `GetAccountLogoutHandler`. + +```php +use Dot\DependencyInjection\Attribute\Inject; + +class GetAccountLogoutHandler implements RequestHandlerInterface +{ + #[Inject( + RouterInterface::class, + AuthenticationServiceInterface::class, + )] + public function __construct( + protected RouterInterface $router, + protected AuthenticationServiceInterface $authenticationService, + ) { + } +} +``` + +> If your class needs the value of a specific configuration key, you can specify the path using dot notation: `config.example` + +The next step is to register the class in the `ConfigProvider` under `factories` using `Dot\DependencyInjection\Factory\AttributedServiceFactory::class`. + +```php +public function getDependencies(): array +{ + return [ + 'factories' => [ + GetAccountLogoutHandler::class => AttributedServiceFactory::class, + ] + ]; +} +``` + +That's it. +When your object is instantiated from the container, it will automatically have its dependencies resolved. + +> Dependencies injection is available to any object within Dotkernel Admin. +> For example, you can inject dependencies in a service, a handler and so on, simply by registering them in the `ConfigProvider`. diff --git a/docs/book/v6/how-to/npm_commands.md b/docs/book/v6/how-to/npm_commands.md new file mode 100644 index 0000000..f03d9cf --- /dev/null +++ b/docs/book/v6/how-to/npm_commands.md @@ -0,0 +1,22 @@ +# NPM Commands + +To install dependencies into the `node_modules` directory run this command. + +```shell +npm install +``` + +> If `npm install` fails, this could be caused by user permissions of npm. +> The recommended way to install npm is through `Node Version Manager`. + +The watch command compiles the components then monitors the files for changes and recompiles them. + +```shell +npm run watch +``` + +After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production. + +```shell +npm run prod +``` diff --git a/docs/book/v6/installation/composer.md b/docs/book/v6/installation/composer.md new file mode 100644 index 0000000..f51f860 --- /dev/null +++ b/docs/book/v6/installation/composer.md @@ -0,0 +1,73 @@ +# Composer Installation of Packages + +Composer is required to install Dotkernel Admin. You can install Composer from the [official site](https://getcomposer.org/). + +> First make sure that you have navigated your command prompt to the folder where you copied the files in the previous step. + +## Install dependencies + +Run this command in the command prompt. + +> Use the **CLI** in order to ensure interactivity for proper configuration. + +```shell +composer install +``` + +You should see this text below, along with a long list of packages to be installed instead of the `[...]`. +In this example there are 171 packages, though the number can change in future updates. +You will find the packages in the `vendor` folder. + +```shell +No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information. +Loading composer repositories with package information +Updating dependencies +Lock file operations: 171 installs, 0 updates, 0 removals +[...] +Writing lock file +Installing dependencies from lock file (including require-dev) +Package operations: 171 installs, 0 updates, 0 removals +[...] +``` + +The setup script prompts for some configuration settings, for example the lines below: + +```text +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: + +```text +Remember this option for other packages of the same type? (y/N) +``` + +Type `y` here, and hit `enter` to complete this stage. + +## Development mode + +If you're installing the project for development, make sure you have development mode enabled, by running: + +```shell +composer development-enable +``` + +You can disable development mode by running: + +```shell +composer development-disable +``` + +You can check if you have development mode enabled by running: + +```shell +composer development-status +``` diff --git a/docs/book/v6/installation/configuration-files.md b/docs/book/v6/installation/configuration-files.md new file mode 100644 index 0000000..42cdad8 --- /dev/null +++ b/docs/book/v6/installation/configuration-files.md @@ -0,0 +1,19 @@ +# Configuration Files + +## Mail + +> If you intend to send emails from your Frontend, make sure to fill in SMTP connection params. +> This will be covered in the next section. + +> **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php` this creates a new in-memory database that your tests will run on. + +If you want your application to send mail, add valid credentials to the following keys in `config/autoload/mail.global.php` + +Under `message_options` key: + +- `from` - email address that will send emails (required) +- `from_name` - organization name for signing sent emails (optional) + +> **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 `dot_mail` => `default` => `message_options` => `cc` key. diff --git a/docs/book/v6/installation/doctrine-orm.md b/docs/book/v6/installation/doctrine-orm.md new file mode 100644 index 0000000..8a56954 --- /dev/null +++ b/docs/book/v6/installation/doctrine-orm.md @@ -0,0 +1,89 @@ +# Doctrine ORM + +This step saves the database connection credentials in an Admin configuration file. +We do not cover the creation steps of the database itself. + +## Setup database + +Create a new MySQL database and set its collation to `utf8mb4_general_ci`. + +Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`. +Below is the item you need to focus on. + +> `my_database`, `my_user`, `my_password` are provided only as an example. + +```php +$databases = [ + 'default' => [ + 'host' => 'localhost', + 'dbname' => 'my_database', + 'user' => 'my_user', + 'password' => 'my_password', + 'port' => 3306, + 'driver' => 'pdo_mysql', + 'charset' => 'utf8mb4', + 'collate' => 'utf8mb4_general_ci', + ], + // you can add more database connections into this array +]; +``` + +## Running migrations + +Run the database migrations by using the following command: + +```shell +php ./vendor/bin/doctrine-migrations migrate +``` + +> 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. + +```text +WARNING! You have x previously executed migrations in the database that are not registered migrations. + {migration list} +Are you sure you wish to continue? (y/n) +``` + +When using an empty database, you will get this confirmation message instead. + +```text +WARNING! You are about to execute a migration in database "" that could result in schema changes and data loss. Are you sure you wish to continue? (yes/no) +``` + +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. + +```text +[OK] Successfully migrated to version: Core\App\Migration\Version20250407142911 +``` + +> The migration name `Version20250407142911` may differ in future Admin updates. + +## Fixtures + +Run this command to populate the admin tables with the default values: + +```shell +php ./bin/doctrine fixtures:execute +``` + +You should see our galloping horse in the command line. + +```shell +Executing Core\App\Fixture\AdminRoleLoader +Executing Core\App\Fixture\OAuthClientLoader +Executing Core\App\Fixture\OAuthScopeLoader +Executing Core\App\Fixture\UserRoleLoader +Executing Core\App\Fixture\AdminLoader +Executing Core\App\Fixture\UserLoader +Fixtures have been loaded. + .'' + ._.-.___.' (`\ + //( ( `' + '/ )\ ).__. ) + ' <' `\ ._/'\ + ` \ \ +``` diff --git a/docs/book/v6/installation/getting-started.md b/docs/book/v6/installation/getting-started.md new file mode 100644 index 0000000..76e13e5 --- /dev/null +++ b/docs/book/v6/installation/getting-started.md @@ -0,0 +1,28 @@ +# Clone the project + +## Recommended development environment + +> If you are using Windows as OS on your machine, you can use WSL2 as development environment. +> Read more here: [PHP-Mariadb-on-WSL2](https://www.dotkernel.com/php-development/almalinux-9-in-wsl2-install-php-apache-mariadb-composer-phpmyadmin/) + +Using your terminal, navigate inside the directory you want to download the project files into. +Make sure that the directory is empty before proceeding to the download process. +Once there, run the following command: + +```shell +git clone https://github.com/dotkernel/admin.git . +``` + +If everything ran correctly, you can expect to see an output like this, though the numbers may differ. + +```shell +Cloning into '.'... +remote: Enumerating objects: 6538, done. +remote: Counting objects: 100% (1652/1652), done. +remote: Compressing objects: 100% (785/785), done. +remote: Total 6538 (delta 804), reused 1417 (delta 748), pack-reused 4886 (from 1) +Receiving objects: 100% (6538/6538), 11.84 MiB | 16.52 MiB/s, done. +Resolving deltas: 100% (3359/3359), done. +``` + +You can already open the project in your preferred IDE to double-check the files were copied correctly. diff --git a/docs/book/v6/installation/installation-intro.md b/docs/book/v6/installation/installation-intro.md new file mode 100644 index 0000000..b6f2e1b --- /dev/null +++ b/docs/book/v6/installation/installation-intro.md @@ -0,0 +1,11 @@ +# Introduction + +In this tutorial, we will install Dotkernel Admin from scratch. +We will focus on these tasks: + +- Highlight 3rd party tools required for the installation. +- Provide all the relevant commands with expected responses. +- Configure the development environment. +- Run the project. + +By the end of this tutorial you will have a fully-functional Dotkernel Admin on your selected environment and can begin coding. diff --git a/docs/book/v6/installation/manage-geolite2.md b/docs/book/v6/installation/manage-geolite2.md new file mode 100644 index 0000000..d175c55 --- /dev/null +++ b/docs/book/v6/installation/manage-geolite2.md @@ -0,0 +1,31 @@ +# Manage the GeoLite2 databases + +You can download/update a specific GeoLite2 database, by running the following command where `{DATABASE}` can be `asn`, `city`, `country`: + +```shell +php ./bin/cli.php geoip:synchronize -d {DATABASE} +``` + +You can download/update all GeoLite2 databases at once, by running the following command: + +```shell +php ./bin/cli.php geoip:synchronize +``` + +The output should be similar to the below, displaying per row: `database identifier`: `previous build datetime` -> `current build datetime`. + +```shell +asn: n/a -> 2024-11-01 02:29:44 +city: n/a -> 2024-11-01 02:29:31 +country: n/a -> 2024-11-01 02:25:09 +``` + +> `n/a` will be replaced by the older version of the GeoLite2 databases when you run the command again. + +Get help for this command by running: + +```shell +php ./bin/cli.php help geoip:synchronize +``` + +> If you set up the synchronizer command as a cronjob, you can add the `-q|--quiet` option, and it will output data only if an error has occurred. diff --git a/docs/book/v6/installation/test-the-installation.md b/docs/book/v6/installation/test-the-installation.md new file mode 100644 index 0000000..bb3caf4 --- /dev/null +++ b/docs/book/v6/installation/test-the-installation.md @@ -0,0 +1,43 @@ +# Running the application + +> **Do not enable dev mode in production** + +We recommend running your applications in WSL: + +- Make sure you have [WSL2](https://docs.dotkernel.org/development/v2/setup/system-requirements/) installed on your system. +- Currently we provide a distro implementations for [AlmaLinux9](https://github.com/dotkernel/development/blob/main/wsl/README.md). +- Install the application in a virtualhost as recommended by the chosen distro. +- Set `$baseUrl` in **config/autoload/local.php** to the address of the virtualhost. +- Run the application by opening the virtualhost address in your browser. + +You should see the `Dotkernel Admin` login page. + +> If you are getting exceptions or errors regarding some missing services, try running the following command: + +```shell +sudo php ./bin/clear-config-cache.php +``` + +> If `config-cache.php` is present that config will be loaded regardless of the `ConfigAggregator::ENABLE_CACHE` in `config/autoload/mezzio.global.php` + +If you ran the fixtures you will have an admin user in the database with the following credentials: + +- **User**: `admin` +- **Password**: `dotadmin` + +> **Production only**: Make sure you modify the default admin credentials. + +> **Development only**: `session.cookie_secure` does not work locally so make sure you modify your `local.php`, as per the following: + +```php +# other code + +return [ + # other configurations... + 'session_config' => [ + 'cookie_secure' => false, + ], +]; +``` + +> Do not change this in `local.php.dist` as well because this value should remain `true` on production. diff --git a/docs/book/v6/introduction/file-structure.md b/docs/book/v6/introduction/file-structure.md new file mode 100644 index 0000000..c428d07 --- /dev/null +++ b/docs/book/v6/introduction/file-structure.md @@ -0,0 +1,142 @@ +# 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/v6/file-structure-dk-admin.jpg +) + +## Special purpose folders + +* `.github` - Contains GitHub workflow files +* `.laminas-ci` - Contains laminas-ci workflow files + +## `bin` folder + +This folder contents are + +* `clear-config-cache.php` - Removes the config cache file `data/cache/config-cache.php`; available only when development mode is enabled +* `cli.php` - Used to build console applications based on [laminas-cli](https://github.com/laminas/laminas-cli) +* `doctrine` - Used by the doctrine fixtures to populate the database tables + +## `config` folder + +This folder contains all application-related config files: + +* `cli-config.php` - Command line interface configuration used by migrations, fixtures, crons +* `config.php` - Registers ConfigProviders for installing packages +* `container.php` - Main service container that provides access to all registered services +* `development.config.php.dist` - Activates debug mode; gets symlinked as `development.config.php` when enabling development mode +* `migrations.php` - Configuration for database migration, like migration file location and table to save the migration log +* `pipeline.php` - Contains a list of middlewares, in the order of their execution +* `twig-cs-fixer.php` - Configuration file for Twig code style checker/fixer + +### `config/autoload` folder + +This folder contains all service-related local and global config files: + +* `app.global.php` - Configures basic app variables +* `authentication.global.php` - Defines the Admin identity +* `authorization.global.php` - Configures permissions for user roles +* `authorization-guards.global.php` - Configures access per route for user roles +* `cli.global.php` - Configures cli +* `cors.global.php` - Configures Cross-Origin Resource Sharing, like call origin, headers, cookies +* `dependencies.global.php` - Config file to set global dependencies that should be accessible by all modules +* `development.local.php.dist` - Gets symlinked as `development.local.php` when enabling development mode; activates error handlers +* `error-handling.global.php` - Configures and activates error logs +* `local.php.dist` - Local config file where you can overwrite application name and URL +* `local.test.php.dist` - Local configuration for functional tests +* `mail.global.php` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging +* `mezzio.global.php` - Mezzio core config file +* `navigation.global.php` - Configures the top menu +* `session.global.php` - Configures the session +* `templates.global.php` - dotkernel/dot-twigrenderer config file + +## `data` folder + +This folder is a storage for project data files and service caches. +It contains these folders: + +* `cache` - Twig and Doctrine cache files +* `geoip` - Holds the GeoLite2 databases +* `lock` - Contains lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/) + +> AVOID storing sensitive data on the repository! + +## `log` folder + +This folder stores daily log files. +When you access the application from the browser, (if not already created) a new log file gets created in the format specified in the `config/autoload/error-handling.global.php` config file under the `stream` array key. + +## `public` folder + +This folder contains all publicly available assets and serves as the entry point of the application: + +* `css` and `js` - Contains the css and js file(s) generated by the webpack (npm) from the assets folder +* `fonts` and `images` - Contain the font and image file(s) copied by the webpack (npm) from the assets folder +* `uploads` - a folder that normally contains admin avatar images +* `.htaccess` - server configuration file used by Apache web server; it enables the URL rewrite functionality +* `index.php` - the application's main entry point +* `robots.txt.dist` - a sample robots.txt file that allows/denies bot access to certain areas of your application; activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment + +## `src` folder + +This folder contains a separate folder for each Module. + +These are the modules included by default: + +* `Admin` - Contains functionality for managing users with `admin` role; note these are users save in the `admin` database table +* `App` - Contains core functionality, from authentication, to rendering, to error reporting +* `Core` – Contains the shared logic and base infrastructure used across multiple modules +* `Dashboard` – Contains the structure and rendering logic of the main admin dashboard, including layout, widgets, and default admin landing page +* `Page` - Contains reusable UI components and layout elements such as dropdowns, modal popups, error displays, and tooltips for the admin interface +* `Setting` - Contains functionality for saving and reading display settings +* `User` - Contains functionality for managing users; note these are users save in the `user` database table + +### Module contents + +Each Module folder, in turn, should contain the following folders, unless they are empty: + +* `src/Handler` - Action classes +* `src/InputFilter` - Validation rules for inputs +* `src/Service` - Service classes + +The above example is just some of the folders a project may include, but they should give you an idea about the recommended structure. +Other classes the `src` folder may include are `Adapter`, `Factory`, `Form`, `Delegator` etc. + +The `src` folder in each Module folder normally also contains these files: + +* `ConfigProvider.php` - Configuration data for the module +* `OpenAPI.php` - Detailed descriptions for each endpoint in the OpenAPI format +* `RoutesDelegator.php` - Module specific route registrations + +### `templates` folder for modules + +This folder contains the template files, used for example to help render e-mail templates. + +> `twig` is used as Templating Engine. +> All template files have the extension `.html.twig`. + +### Core module + +The Core module is a common codebase set up to be used by the applications you added to your project. + +These are the submodules included by default: + +* `Admin` - Contains logic for the admin submodule features +* `App` - Contains shared application-level services and infrastructure utilities +* `Security` - Contains authentication, authorization, and related security mechanisms +* `Setting` - Contains configuration and application settings management +* `User` - Contains user entities, repositories, and services handling user data and logic + +Each submodule folder should contain: + +* `src/Entity` - Used by database entities +* `src/Repository` - Entity repository folder +* `ConfigProvider.php` - Configuration data for the module + +The above example is just some of the folders a project may include, but they should give you an idea about the recommended structure. +Other classes the `src` folder may include are `DBAL`, `Enum`, `Command`, `Factory` etc. diff --git a/docs/book/v6/introduction/introduction.md b/docs/book/v6/introduction/introduction.md new file mode 100644 index 0000000..9d780dc --- /dev/null +++ b/docs/book/v6/introduction/introduction.md @@ -0,0 +1,9 @@ +# Introduction + +Dotkernel Admin is an application (skeleton) intended for quickly setting up an administration site for your platform. +It's a fast and reliable way to manage records in your database with a simple table-based approach, and also to build reports and graphs to monitor your platform. +The many graphical components at your disposal ensure an intuitive user experience. + +> Check out our [demo](https://admin6.dotkernel.net/). +> +> Submit user `admin` and password `dotadmin` to authenticate yourself. diff --git a/docs/book/v6/introduction/packages.md b/docs/book/v6/introduction/packages.md new file mode 100644 index 0000000..b9a27b6 --- /dev/null +++ b/docs/book/v6/introduction/packages.md @@ -0,0 +1,30 @@ +# Packages + +> Dotkernel Admin 6.x will have full Laminas Service Manager 4 support once all dependencies do support it. +> Once Laminas Service Manager 4 is fully supported, Dotkernel Admin 6.x will be installable on PHP 8.4 as well. + +* `dotkernel/dot-cache`:`^4.3` - Provides caching based on symfony/cache +* `dotkernel/dot-cli`:`^3.9` - Build console applications based on laminas-cli +* `dotkernel/dot-data-fixtures`:`^1.4` - Provides a CLI interface for listing & executing doctrine data fixtures +* `dotkernel/dot-dependency-injection`:`^1.2` - Dependency injection component using class attributes +* `dotkernel/dot-errorhandler`:`^4.0` - Logging Error Handler for Middleware Applications +* `dotkernel/dot-flashmessenger`:`^3.6` - Provides session messages between redirects +* `dotkernel/dot-geoip`:`^3.9` - Retrieve information about an IP address based on maxmind/GeoIP2-php +* `dotkernel/dot-helpers`:`^3.8` - Helper/Utility classes based on mezzio/mezzio-helpers +* `dotkernel/dot-mail`:`^5.1` - Mail component based on laminas-mail +* `dotkernel/dot-navigation`:`^3.5` - Allows you to easily define and parse menus inside templates, configuration based approach +* `dotkernel/dot-rbac-guard`:`^3.6` - Defines authorization guards that authorize users for accessing certain parts of an application based on various criteria +* `dotkernel/dot-router`:`^1.0` - Dotkernel component to build complex routes, based on mezzio/mezzio-fastroute +* `dotkernel/dot-session`:`^5.7` - Dotkernel session component extending and customizing laminas-session +* `dotkernel/dot-twigrenderer`:`^3.6` - Dotkernel component providing twig extensions and customizations +* `friendsofphp/proxy-manager-lts`:`^1.0` - Fork of ocramius/proxy-manager +* `laminas/laminas-component-installer`:`^3.5` - Composer plugin for injecting modules and configuration providers into application configuration +* `laminas/laminas-config-aggregator`:`^1.18` - Lightweight library for collecting and merging configuration from different sources +* `mezzio/mezzio`:`^3.21` - PSR-15 Middleware Microframework +* `mezzio-authentication-oauth2`:`^2.11` - Middleware for Mezzio and PSR-7 applications providing an OAuth2 server for authentication. +* `mezzio/mezzio-authorization-rbac`:`^1.9` - Mezzio authorization rbac adapter for laminas/laminas-permissions-rbac +* `mezzio/mezzio-cors`:`^1.14` - CORS component for Mezzio and other PSR-15 middleware runners +* `mezzio/mezzio-fastroute`:`^3.13` - FastRoute integration for Mezzio +* `ramsey/uuid`:`^4.5` - Library for generating and working with universally unique identifiers (UUIDs). +* `ramsey/uuid-doctrine`:`^2.1` - Use ramsey/uuid as a Doctrine field type +* `roave/psr-container-doctrine`:`^5.2` - Doctrine Factories for PSR-11 Containers diff --git a/docs/book/v6/introduction/server-requirements.md b/docs/book/v6/introduction/server-requirements.md new file mode 100644 index 0000000..26435fd --- /dev/null +++ b/docs/book/v6/introduction/server-requirements.md @@ -0,0 +1,50 @@ +# Server Requirements + +For production, we highly recommend a *nix based system. + +## Webserver + +### Apache >= 2.2 + +* mod_rewrite +* .htaccess support `(AllowOverride All)` + +> The repository includes a default `.htaccess` file in the `public` folder. + +### Nginx + +You need to convert the provided Apache related `.htaccess` file into Nginx configuration instructions. + +## PHP >= 8.2 + +Both mod_php and FCGI (FPM) are supported. + +## Required Settings and Modules & Extensions + +* memory_limit >= 128M +* upload_max_filesize and post_max_size >= 100M (depending on your data) +* mbstring +* CLI SAPI (for Cron Jobs) +* Composer (added to $PATH) + +## RDBMS + +* Tested with MariaDB 10.11 LTS and MariaDB 11.4 LTS +* Tested with MySQL 8.4 LTS + +> For MySQL 8.4 LTS be sure you have the below line in my.cnf + +```text +mysql_native_password=ON +``` + +## Recommended extensions + +* opcache +* pdo_mysql or mysqli (if using MySQL or MariaDB as RDBMS) +* dom - if working with markup files structure (html, xml, etc) +* simplexml - working with xml files +* gd, exif - if working with images +* zlib, zip, bz2 - if compessing files +* curl (required if APIs are used) +* sqlite3 - for tests diff --git a/mkdocs.yml b/mkdocs.yml index 48205b3..9b21473 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,9 +2,10 @@ docs_dir: docs/book site_dir: docs/html extra: project: Admin - current_version: v5 + current_version: v6 versions: - v5 + - v6 nav: - Home: index.md - v5: @@ -28,6 +29,27 @@ nav: - "Use NPM Commands": v5/how-to/npm_commands.md - "Inject Dependencies": v5/how-to/dependency-injection.md - "Set Up CSRF": v5/how-to/csrf.md + - v6: + - Introduction: v6/introduction/introduction.md + - Overview: + - "Server Requirements": v6/introduction/server-requirements.md + - "File Structure": v6/introduction/file-structure.md + - "Packages": v6/introduction/packages.md + - Installation: + - "Introduction": v6/installation/installation-intro.md + - "Getting Started": v6/installation/getting-started.md + - "Composer": v6/installation/composer.md + - "Configuration Files": v6/installation/configuration-files.md + - "Doctrine ORM": v6/installation/doctrine-orm.md + - "Manage Geolite2": v6/installation/manage-geolite2.md + - "Test the Installation": v6/installation/test-the-installation.md + - How to: + - "Create Database Migrations": v6/how-to/creating-migrations.md + - "Create Database Fixtures": v6/how-to/creating-fixtures.md + - "Configure Authorizations": v6/how-to/authorization.md + - "Use NPM Commands": v6/how-to/npm_commands.md + - "Inject Dependencies": v6/how-to/dependency-injection.md + - "Set Up CSRF": v6/how-to/csrf.md site_name: admin site_description: "DotKernel Admin" repo_url: "https://github.com/dotkernel/admin"