updated intro, how to

bidi47 · bidi47 · commit ef9c7b25c4e9 · 2024-11-13T12:29:35.000+02:00
Signed-off-by: bidi &lt;bidi@apidemia.com&gt;
diff --git a/docs/book/v5/how-to/authorization.md 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/how-to/csrf.md b/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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -11,15 +11,20 @@ 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
           - "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
-      - 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"
