Merge pull request #8 from dotkernel/composer

updated intro, how to

Author: arhimede

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
+                        ]
+                    ]
+                ]
+```

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

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

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

@@ -0,0 +1,29 @@
+# Creating migrations
+
+Migrations are used to create and/or edit the database structure.
+To generate a new migration file, use this command:
+
+```shell
+php vendor/bin/doctrine-migrations migrations:generate
+```
+
+It creates a PHP file like this one `/data/doctrine/migrations/Version20240627134952.php` that can then be edited in the IDE.
+You can add new queries in:
+
+- `public function up` - these are executed when the migration is run.
+- `public function down` - these are optional queries that undo the above changes.
+
+## Example
+
+This example creates a new column named `test`.
+Add this in `public function up`:
+
+```shell
+$this->addSql('ALTER TABLE admin ADD test VARCHAR(255) NOT NULL');
+```
+
+And its opposite in `public function down`:
+
+```shell
+$this->addSql('ALTER TABLE admin DROP test');
+```

docs/book/v5/core-features/csrf.md docs/book/v5/how-to/csrf.mddocs/book/v5/core-features/csrf.md renamed to docs/book/v5/how-to/csrf.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`.

docs/book/v5/how-to/dependency-injection.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
+```

docs/book/v5/how-to/npm_commands.md

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

docs/book/v5/installation/composer.md

@@ -2,16 +2,31 @@
 
 ## Prepare config files
 
-* duplicate `config/autoload/local.php.dist` as `config/autoload/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`
 
-* 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.
 
-### Note
+> **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 your Admin will send emails, make sure to fill in SMTP connection params
+## Mail
 
-* **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php`
+If you want your application to send mail, add valid credentials to the following keys in `config/autoload/mail.local.php`
 
-### Note
+Under `message_options` key:
 
-> this creates a new in-memory database that your tests will run on.
+- `from` - email address that will send emails (required)
+- `from_name` - organization name for signing sent emails (optional)
+
+Under `smtp_options` key:
+
+- `host` - hostname or IP address of the mail server (required)
+- `connection_config` - add the `username` and `password` keys (required)
+
+In `config/autoload/local.php` edit the key `contact` => `message_receivers` => `to` with *string* values for emails that should receive contact messages.
+
+> **Please add at least 1 email address in order for contact message to reach someone**
+
+Also feel free to add as many CCs as you require under the `contact` => `message_receivers` => `cc` key.

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

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

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

@@ -5,9 +5,24 @@
 > 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.