diff --git a/docs/book/v5/core-features/dependency-injection.md b/docs/book/v5/core-features/dependency-injection.md deleted file mode 100644 index b599a88..0000000 --- a/docs/book/v5/core-features/dependency-injection.md +++ /dev/null @@ -1,61 +0,0 @@ -# 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 API, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package -focuses only on constructor injection. - -## Usage - -**DotKernel API** comes out of the box with the -[dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all we need for -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. Dependencies are specified as separate parameters of the `#[Inject]` attribute. - -For our example we will inject `UserService` and `config` dependencies into a `UseHandler`. - -```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 API. For example, you can inject dependencies in a -> service, a handler and so on, simply by registering it in the `ConfigProvider`. diff --git a/docs/book/v5/core-features/languages.md b/docs/book/v5/core-features/languages.md deleted file mode 100644 index 2a689f2..0000000 --- a/docs/book/v5/core-features/languages.md +++ /dev/null @@ -1,17 +0,0 @@ -# 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")` - -**NOTE:** -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. diff --git a/docs/book/v5/core-features/account-anonymization.md b/docs/book/v5/how-to/account-anonymization.md similarity index 100% rename from docs/book/v5/core-features/account-anonymization.md rename to docs/book/v5/how-to/account-anonymization.md diff --git a/docs/book/v5/core-features/authorization.md b/docs/book/v5/how-to/authorization.md similarity index 92% rename from docs/book/v5/core-features/authorization.md rename to docs/book/v5/how-to/authorization.md index 1fe453b..b7b1f2c 100644 --- a/docs/book/v5/core-features/authorization.md +++ b/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. 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..a0610bc --- /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/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 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..9ee06d4 --- /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/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'); +``` diff --git a/docs/book/v5/core-features/csrf.md b/docs/book/v5/how-to/csrf.md similarity index 61% rename from docs/book/v5/core-features/csrf.md rename to docs/book/v5/how-to/csrf.md index 1e6a742..967e7ca 100644 --- a/docs/book/v5/core-features/csrf.md +++ b/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,7 +53,7 @@ $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. @@ -63,8 +61,7 @@ where `exampleCsrf` must match the CSRF field's name in the form. ### 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')) }} @@ -72,20 +69,25 @@ tags: ## 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. 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..12c1bb2 --- /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 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`. diff --git a/docs/book/v5/how-to/languages.md b/docs/book/v5/how-to/languages.md new file mode 100644 index 0000000..1f678bf --- /dev/null +++ b/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. diff --git a/docs/book/v5/core-features/npm_commands.md b/docs/book/v5/how-to/npm_commands.md similarity index 54% rename from docs/book/v5/core-features/npm_commands.md rename to docs/book/v5/how-to/npm_commands.md index 1bbcb93..f03d9cf 100644 --- a/docs/book/v5/core-features/npm_commands.md +++ b/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 diff --git a/docs/book/v5/installation/composer.md b/docs/book/v5/installation/composer.md index aae5a72..7fc433d 100644 --- a/docs/book/v5/installation/composer.md +++ b/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 diff --git a/docs/book/v5/installation/configuration-files.md b/docs/book/v5/installation/configuration-files.md index 130d5bd..c323a35 100644 --- a/docs/book/v5/installation/configuration-files.md +++ b/docs/book/v5/installation/configuration-files.md @@ -1,24 +1,21 @@ # Configuration Files +This step involves changing the names of or duplicating some of the `.dist` files in the project and editing their content to suit your project's requirements. + ## Prepare config files -- duplicate `config/autoload/debugbar.local.php.dist` as `config/autoload/debugbar.local.php` -- duplicate `config/autoload/development.local.php.dist` as `config/autoload/development.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/debugbar.local.php.dist` as `config/autoload/debugbar.local.php` +- Duplicate `config/autoload/development.local.php.dist` as `config/autoload/development.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` - Edit `config/autoload/local.php` according to your dev machine and fill in the `database` configuration. -### 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. -- **optional**: in order to run/create tests, duplicate `config/autoload/local.test.php.dist` as `config/autoload/local.test.php` - -### 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. -> this creates a new in-memory database that your tests will run on. - -## Configuration - Mail +## Mail If you want your application to send mails on registration, contact etc. add valid credentials to the following keys in `config/autoload/mail.local.php` @@ -34,16 +31,19 @@ Under `smtp_options` key: In `config/autoload/local.php` edit the key `contact` => `message_receivers` => `to` with *string* values for emails that should receive contact messages. -Note: **Please add at least 1 email address in order for contact message to reach someone** +> **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. + +## reCAPTCHA -Also feel free to add as many CCs as you want under the `contact` => `message_receivers` => `cc` key. +reCAPTCHA is used to prevent abusive activities on your website. +DotKernel frontend uses the Google reCAPTCHA for its `contact us` form. -## Configuration - reCAPTCHA +- Generate a `siteKey` and `secretKey` in your Google account: [Google reCAPTCHA](https://www.google.com/recaptcha/admin) -reCAPTCHA is used to prevent abusive activities on your website. DotKernel frontend uses the Google reCAPTCHA for its contact us form. -You must first generate a `siteKey` and `secretKey` in your Google account - [Google reCAPTCHA](https://www.google.com/recaptcha/admin) +- Update the `recaptcha` array in `config/autoload/local.php` with the `siteKey` and `secretKey` from Google reCAPTCHA. -Update the `recaptcha` array in `config/autoload/local.php` with the `siteKey` and `secretKey` from Google reCAPTCHA. +> You need to whitelist `localhost` in the reCAPTCHA settings page during development. -Note: you need to whitelist `localhost` in the reCAPTCHA settings page during development. -**When in production do not forget to either remove `localhost` from the reCAPTCHA whitelist, or have a separate reCAPTCHA** +>**When in production do not forget to either remove `localhost` from the reCAPTCHA whitelist, or have a separate reCAPTCHA** diff --git a/docs/book/v5/installation/development-mode-debugbar.md b/docs/book/v5/installation/development-mode-debugbar.md index a677641..02527e9 100644 --- a/docs/book/v5/installation/development-mode-debugbar.md +++ b/docs/book/v5/installation/development-mode-debugbar.md @@ -1,11 +1,19 @@ # Development mode -Run this command to enable dev mode by turning debug flag to `true` and turning configuration caching to `off`. It will also make sure that any existing config cache is cleared. +Run this command to enable dev mode by turning debug flag to `true` and turning configuration caching to `off`. +It will also make sure that any existing config cache is cleared. ```shell composer development-enable ``` +You should see this in the command prompt: + +```shell +> laminas-development-mode enable +You are now in development mode. +``` + - If not already done, remove the `.dist` extension from `config/autoload/development.global.php.dist`. ## Using DebugBar diff --git a/docs/book/v5/installation/doctrine-orm.md b/docs/book/v5/installation/doctrine-orm.md index 06b360a..f8ba8ff 100644 --- a/docs/book/v5/installation/doctrine-orm.md +++ b/docs/book/v5/installation/doctrine-orm.md @@ -1,12 +1,34 @@ # Doctrine ORM -## Setup database +This step saves the database connection credentials in a Frontend configuration file. +We do not cover the creation steps of the database itself. -Make sure you fill out the database credentials in `config/autoload/local.php` under `$databases['default']`. +## Setup database Create a new MySQL database and set its collation to `utf8mb4_general_ci`. -## Running migrations +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 +]; +``` + +## Migrations Running the migrations is done with this command @@ -14,7 +36,8 @@ Running the migrations is done with this command php vendor/bin/doctrine-migrations migrate ``` -Note: if you have already run the phinx migrations, you may get this message +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. ```shell WARNING! You have x previously executed migrations in the database that are not registered migrations. @@ -22,61 +45,40 @@ WARNING! You have x previously executed migrations in the database that are not Are you sure you wish to continue? (y/n) ``` -After submitting `y`, you will get this confirmation message. +When using an empty database, you will get this confirmation message instead. ```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) ``` -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. - -## Creating migrations +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 generate a new migration file, use this command: +If everything ran correctly, you will get this confirmation. ```shell -php vendor/bin/doctrine-migrations migrations:generate +[OK] Successfully migrated to version: Frontend\Migrations\Version20240806123413 ``` -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 to be executed when the migration is run (in `public function up`) and optionally queries that undo those changes (in `public function down`). +> The migration name `Version20240806123413` may differ in future Frontend updates. -Here is an example you can add in `public function up` +## Fixtures -```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'); -``` - -## Executing fixtures - -**Fixtures are used to seed the database with initial values and should only be executed ONCE, 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. - -An example of a fixtures class is ``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: +Run this command to populate the `user_role` table with the default values: ```shell php bin/doctrine fixtures:execute ``` -To execute a specific fixtures, run: +You should see our galloping horse in the command line. ```shell -php bin/doctrine fixtures:execute --class=RoleLoader +Executing Frontend\Fixtures\RoleLoader +Fixtures have been loaded. + .'' + ._.-.___.' (`\ + //( ( `' + '/ )\ ).__. ) + ' <' `\ ._/'\ + ` \ \ ``` - -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/installation/getting-started.md b/docs/book/v5/installation/getting-started.md index 6ab750c..adc9522 100644 --- a/docs/book/v5/installation/getting-started.md +++ b/docs/book/v5/installation/getting-started.md @@ -5,9 +5,30 @@ > 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. +> - You will get this error if the directory is not empty `fatal: destination path '.' already exists and is not an empty directory.` and no files will be cloned. +> - That you have writing permissions on the directory. + +Once there, run the following command: ```shell git clone https://github.com/dotkernel/frontend.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: 6901, done. +remote: Counting objects: 100% (795/795), done. +remote: Compressing objects: 100% (343/343), done. +remote: Total 6901 (delta 522), reused 478 (delta 449), pack-reused 6106 (from 1) +Receiving objects: 100% (6901/6901), 3.83 MiB | 6.42 MiB/s, done. +Resolving deltas: 100% (3868/3868), 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..ee0dffe --- /dev/null +++ b/docs/book/v5/installation/installation-intro.md @@ -0,0 +1,11 @@ +# Introduction + +In this tutorial, we will install Dotkernel Frontend 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 Frontend on your selected environment and can begin coding. diff --git a/docs/book/v5/installation/running-application.md b/docs/book/v5/installation/running-application.md index 717b13d..6f348d5 100644 --- a/docs/book/v5/installation/running-application.md +++ b/docs/book/v5/installation/running-application.md @@ -2,17 +2,15 @@ We recommend running your applications in WSL: -- 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 +- 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. You should see the `DotKernel Frontend` welcome page. -**NOTE:** - -- If you are getting exceptions or errors regarding some missing services, try running the following command: +> If you are getting exceptions or errors regarding some missing services, try running the following command: ```shell sudo php bin/clear-config-cache.php @@ -20,7 +18,7 @@ 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` -- **Development only**: `session.cookie_secure` does not work locally so make sure you modify your `local.php`, as per the following: +> **Development only**: `session.cookie_secure` does not work locally so make sure you modify your `local.php`, as per the following: ```php # other code diff --git a/docs/book/v5/introduction/file-structure.md b/docs/book/v5/introduction/file-structure.md index 3c5efce..cdf2dc1 100644 --- a/docs/book/v5/introduction/file-structure.md +++ b/docs/book/v5/introduction/file-structure.md @@ -10,31 +10,32 @@ When using DotKernel Frontend the following structure is installed by default: ## Main directories -* `bin` - executable files from CLI -* `config` - various configuration files -* `data` - should contain project-related data (AVOID storing sensitive data on VCS) -* `documentation` - should contain project-related documentation -* `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 +* `bin` - Executable files from CLI +* `config` - Various configuration files +* `data` - Should contain project-related data (AVOID storing sensitive data on VCS) +* `documentation` - Should contain project-related documentation +* `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` - containes workflow files -* `.laminas-ci` - contains laminas-ci workflow files +* `.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 following directories, if they’re not empty: +This directory contains all source code related to the Module. +It should contain the following directories, if they’re not empty: * Handler - Action classes (similar to Controllers but can only perform one action) -* Entity - For database entities +* Entity - Database entities * Service - Service classes * Collection - Database entities collections * Repository - Entity repository folder -> The above example is just some of the directories a project may include, but these should give you an idea of how the structure should look like. +> 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. @@ -47,14 +48,15 @@ The `src` directory should also contain 2 files: This directory contains the template files, used for example to help render e-mail templates. -> DotKernel Frontend uses twig as Templating Engine. All template files have the extension .html.twig +> DotKernel Frontend uses `twig` as Templating Engine. +> All template files have the extension `.html.twig`. ## `data` directory -This directory contains project-related data (such as cache, file uploads) +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` [See more](https://docs.dotkernel.org/dot-cli/v3/lock-files/) +* `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/mkdocs.yml b/mkdocs.yml index d489ceb..efb2d73 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,13 +22,15 @@ nav: - "Development Mode and the Debugbar": v5/installation/development-mode-debugbar.md - "Running the Application": v5/installation/running-application.md - "FAQ": v5/installation/faq.md - - Core Features: - - "Authorization": v5/core-features/authorization.md - - "NPM Commands": v5/core-features/npm_commands.md - - "Dependency Injection": v5/core-features/dependency-injection.md - - "Languages": v5/core-features/languages.md - - "CSRF": v5/core-features/csrf.md - - "Account anonymization": v5/core-features/account-anonymization.md + - 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 + - "Use NPM Commands": v5/how-to/npm_commands.md + - "Inject Dependencies": v5/how-to/dependency-injection.md + - "Configure Languages": v5/how-to/languages.md + - "Set Up CSRF": v5/how-to/csrf.md + - "Anonymize Accounts": v5/how-to/account-anonymization.md site_name: frontend site_description: "DotKernel Frontend" repo_url: "https://github.com/dotkernel/frontend"