Merge pull request #8 from dotkernel/diataxis

Diataxis

docs/book/v5/core-features/authorization.md → docs/book/v5/how-to/authorization.md

@@ -1,6 +1,7 @@
 # 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 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.
 

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/RoleLoader.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=RoleLoader
+```
+
+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/Version20220606131835.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 users ADD test VARCHAR(255) NOT NULL');
+```
+
+And its opposite in `public function down`:
+
+```shell
+$this->addSql('ALTER TABLE users DROP test');
+```

docs/book/v5/core-features/csrf.md → docs/book/v5/how-to/csrf.md

@@ -1,12 +1,10 @@
 # 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.
+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.
+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.
+Failing to provide a valid CSRF token will result in a form validation error.
 
 ## Implement CSRF protection
 
@@ -30,7 +28,7 @@ $this->add(new \Laminas\Form\Element\Csrf('exampleCsrf', [
 ]));
 ```
 
-where `exampleCsrf` should be a suggestive name that describes the purpose of the field (example: `forgotPasswordCsrf`).
+> You should use a relevant name instead of `exampleCsrf` that best describes the purpose of the field (example: `forgotPasswordCsrf`).
 
 ### Validate field
 
@@ -55,37 +53,41 @@ $csrf->getValidatorChain()
 $this->add($csrf);
 ```
 
-where `exampleCsrf` must match the CSRF field's name in the form.
+Replace `exampleCsrf` with 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:
+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.
+Access your form from the browser and view its source.
+You should see a new hidden field, called `exampleCsrf` (or whatever name you used).
+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:
+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.
+Submitting a filled out form should result in a validation error:
 
-> **CSRF** is required and cannot be empty
+```text
+CSRF 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:
+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:
 
-> **CSRF** is invalid
+```text
+**CSRF** is invalid
+```
 
-You can modify the value of `timeout` in each form, but the default value should work in most cases.
+> You can modify the value of `timeout` in each form, but the default value should work in most cases.

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 Frontend, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection.
+
+## Usage
+
+**DotKernel Frontend** 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 `UserService` and `config` dependencies into a `UserHandler`.
+
+```php
+use Dot\DependencyInjection\Attribute\Inject;
+
+class UserHandler implements RequestHandlerInterface
+{
+    #[Inject(
+        UserService::class,
+        "config",
+    )]
+    public function __construct(
+        protected UserServiceInterface $userService,
+        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' => [
+            UserHandler::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 Frontend.
+> For example, you can inject dependencies in a service, a handler and so on, simply by registering them in the `ConfigProvider`.

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

@@ -0,0 +1,18 @@
+# Languages
+
+The `local.php.dist` file provides an example for working with multiple languages.
+The `translator` variable can be expanded to other languages using [Poedit](https://poedit.net/) which can edit `.po` files like the example in `data/language/da_DK/LC_MESSAGES/messages.po`.
+The compiled file will have the extension `.mo`.
+
+To apply the translations
+
+- the twig templates need either `{% trans 'translateText' %}` or `{{ translateText|trans }}`
+- then the js file needs `translateText("translateText")`
+
+> In order to have a proper behaviour of language selector , you need the language pack installed at Operating System level.
+
+```shell
+dnf install glibc-all-langpacks
+```
+
+Then restart PHP-FPM.

docs/book/v5/core-features/npm_commands.md → docs/book/v5/how-to/npm_commands.md

@@ -6,9 +6,10 @@ To install dependencies into the `node_modules` directory run this command.
 npm install
 ```
 
-- If `npm install` fails, this could be caused by user permissions of npm. Recommendation is to install npm through `Node Version Manager`.
+> 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 watches the files and recompiles when one of them changes.
+The watch command compiles the components then monitors the files for changes and recompiles them.
 
 ```shell
 npm run watch

docs/book/v5/installation/composer.md

@@ -1,13 +1,33 @@
 # Composer Installation of Packages
 
-Composer is required to install DotKernel `frontend`. You can install Composer starting [here](https://getcomposer.org/).
+Composer is required to install DotKernel `frontend`. You can install Composer on the [official site](https://getcomposer.org/).
+
+> First make sure that you have navigated your command prompt in the folder where you copied the files in the previous step.
 
 ## Install dependencies
 
+Run this command in the command prompt.
+
 ```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 158 packages, though the number can change in future `Frontend` 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: 158 installs, 0 updates, 0 removals
+[...]
+Writing lock file
+Installing dependencies from lock file (including require-dev)
+Package operations: 158 installs, 0 updates, 0 removals
+[...]
+```
+
 The setup script prompts for some configuration settings, for example the lines below:
 
 ```shell
@@ -19,13 +39,14 @@ Please select which config file you wish to inject 'Laminas\Diactoros\ConfigProv
 
 Simply select `[0] Do not inject`, because DotKernel includes its own configProvider which already contains the prompted configurations.
 
-If you choose `[1] config/config.php` Laminas's `ConfigProvider` from `session` will be injected.
+> If you choose `[1] config/config.php` Laminas's `ConfigProvider` from `session` will be injected.
+> This is not required for the default installation, so make sure to select `[0] Do not inject`
 
 The next question is:
 
 `Remember this option for other packages of the same type? (y/N)`
 
-Type `y` here, and hit `enter`
+Type `y` here, and hit `enter`.
 
 ## Development mode