Dotkernel web starter package suitable for frontend applications.

Branch	Release	PSR-11	OSS Lifecycle	PHP Version
5.0	>= 5.0	1
4.0	< 5.0	1
3.0	< 4.0	1

• Installing DotKernel frontend
  • Installation
    • Composer
  • Choose a destination path for DotKernel frontend installation
  • Installing the frontend Composer package
    • Installing DotKernel Frontend
  • Configuration - First Run
  • Testing (Running)

DotKernel can be installed through a single command that utilizes Composer. Because of that, Composer is required to install DotKernel frontend.

Installation instructions:

• Composer Installation - Linux/Unix/OSX
• Composer Installation - Windows

If you have never used composer before make sure you read the Composer Basic Usage section in Composer's documentation

Example:

• absolute path /var/www/dk
• or relative path dk (equivalent with ./dk)

After choosing the path for DotKernel (dk will be used for the remainder of this example) it must be installed. There are two installation methods.

The installation uses the PHP extension ext-intl that may not be enabled by default in your web server. If the installation returns a similar error to the below, check the extension=intl extension in your php.ini.

Your requirements could not be resolved to an installable set of packages.

Problem 1
 - laminas/laminas-i18n 2.10.3 requires ext-intl * -> the requested PHP extension intl is missing from your system.

To enable an extension, remove the semicolon (;) in front of it.

The advantage of using this command is that it runs through the whole installation process. Run the following command:

$ composer create-project dotkernel/frontend -s dev dk

The above command downloads the frontend package, then downloads and installs the dependencies.

The setup script prompts for some configuration settings, for example the lines below:

Please select which config file you wish to inject 'Laminas\Diactoros\ConfigProvider' into:
  [0] Do not inject
  [1] config/config.php
  Make your selection (default is 0):

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.

The next question is:

Remember this option for other packages of the same type? (y/N)

Type y here, and hit enter

This method requires more manual input, but it ensures that the default branch is installed, even if it is not released. Run the following command:

$ git clone https://github.com/dotkernel/frontend.git .

The dependencies have to be installed separately, by running this command

$ composer install

Just like for II Installing DotKernel frontend using composer (see above), the setup asks for configuration settings regarding injections (type 0 and hit enter) and a confirmation to use this setting for other packages (type y and hit enter)

• Remove the .dist extension from the files config/autoload/local.php.dist and config/autoload/mail.local.php.dist
• Edit config/autoload/local.php according to your dev machine and fill in the database configuration

If you want your application to send mails on registration, contact... please provide valid credentials to the following keys in config/autoload/mail.local.php

Under message_options key:

• from - email address from whom users will receive emails (required)
• from_name - organization name from whom users will receive emails (optional)

Under smtp_options key:

• host - hostname or IP address of the mail server (required)
• connection_config - please complete the username and password keys (required)

In config/autoload/local.php add under contact => message_receivers => to key string values with the emails that should receive contact messages

Note: Please add at least 1 email address in order for contact message to reach someone

Also feel free to add as many cc as you want under 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. You must first generate a siteKey and secretKey in your Google account - Google reCAPTCHA

Update the recaptcha array in config/autoload/local.php with the siteKey and secretKey from Google reCAPTCHA.

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

Out of the box, we use Doctrine Migrations like detailed below to populate the database. An example file is included in /data/doctrine/migrations. To generate a new migration file, use this command:

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 to be executed when the migration is run (in public function up) and optionally queries that undo those changes (in public function down).

Here is an example you can add in public function up

$this->addSql('ALTER TABLE users ADD test VARCHAR(255) NOT NULL');

and its opposite in public function down

$this->addSql('ALTER TABLE users DROP test');

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

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)

After submitting y, you will get this confirmation message.

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 of 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.

You can opt to run a single migration

php vendor/bin/doctrine-migrations migrations:execute --up 20220606131835

and you can revert its changes with

php vendor/bin/doctrine-migrations migrations:execute --down 20220606131835

This will also remove the log for that migration in the database, allowing the migration to run again with php vendor/bin/doctrine-migrations migrate. Note the 20220606131835 is taken from the migration filename, e.g. Version20220606131835.php

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

Running php bin/doctrine fixtures:list will list all the available fixtures, by order of execution.

To execute all fixtures run : php bin/doctrine fixtures:execute.

To execute a specific fixtures run : 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

• If you use composer create-project, the project will go into development mode automatically after installing. The development mode status can be checked and toggled by using these composer commands

$ composer development-status
$ composer development-enable
$ composer development-disable

• If not already done on installation, remove the .dist extension from config/autoload/development.global.php.dist. This will 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.

Charset recommendation: utf8mb4_general_ci

These are the email templates provided on a fresh installation, all present in the User module

• activate.html.twig used for the activation email
• reset-password-requested.html.twig used when the user requests a password reset
• reset-password-completed.html.twig used when the password has reset successfully

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.

The watch command compiles the components then watches the files and recompiles when one of them changes.

npm run watch

After all updates are done, this command compiles the assets locally, minifies them and makes them ready for production.

npm run prod

The packages responsible for restricting access to certain parts of the application are dot-rbac-guard and 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.

//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.

// 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
                        ]
                    ]
                ]

In terms of business logic, any application launched in production needs to be indexed by search engines as friendly as possible.

Here comes the Slug module that works together with the application's routing system, which adds the option to customize each route replacing the old pattern such as the name of the route as well as its action with a chosen alias. On top of that, it allows you to replace the attributes with a more coherent version without losing their main functionality.

The slug.global.php.dist is the main configuration for Slug module .

 // How to add a registered route to your slug configuration.
 'slug_configuration' => [
        // Detect a duplicate alias to avoid confusion.
        // We may have duplicate aliases but it is not recommended
        // that it requires future development on each project.
        'detect_duplicates' => true,
        // Main slug declaration.
        'slug_route' => [
            [
                'route'     => '[route name]',    // <- Specify the route name.
                'action'    => '[route action]',  // <- Specify the route action.
                'alias'     => '/[alias]',        // <- Here you must add an alias for the
                // specific route ex: /list/detail -> /product-detail.
                'exchange'  => [                  // <- If you want to exchange your route
                // attribute specify the exchange configuration or leave it empty.
                    '[attribute name]' => [                              // <- Attribute name.
                          'table'           => '[table name]',           // <- The main table from which the attribute belongs. 
                          'identifier'      => '[table identifier]',     // <- This must be the main attribute afferent column.
                          'exchangeColumn'  => '[exchange column name]', // <- Specify the main column from which the slug will be generated.
                          'slugColumn'      => '[slug column]'           // <- This will be the main storage column for the generated slug.
                     ],
                     .
                     .
                     // You can add here more attribute.
                ]
            ],
            .
            .
            // You can add here more routes.
        ]
    ]

The main functionality of the exchange key is to replace one or more attributes that play the role of unique identifier later being used in controllers to access certain information, these unique identifiers can have an unfriendly format, irrelevant to the end user.

Therefore, we can replace the attribute with an auto-generated value from the column specified in the exchangeColumn key and then saved in the slugColumn.

Of course, we will have to make certain changes in the respective table requiring a field in which the generated value will be saved.

 // Example of slug configuration.
 'slug_configuration' => [
        'detect_duplicates' => true,
        'slug_route' => [
            [
                'route'     => 'page',
                'action'    => 'home',
                'alias'     => '/home-page',
                'exchange'  => []
            ],
              // The slug configuration will replace the basic route pattern with a specified alias so
              // the route path will be changed from `/page/home` to `/home-page`.
            [
                'route'     => 'product',
                'action'    => 'detail',
                'alias'     => '/product',
                'exchange'  => [
                    'uuid' => [
                          'table'           => 'products',
                          'identifier'      => 'uuid',
                          'exchangeColumn'  => 'name',
                          'slugColumn'      => 'slug'
                     ],
                ]
            ],
              // The above configuration will replace the `uuid` attribute from 
              // the route declaration path `/product[/{action}[/{uuid}]]` with a generated value from
              // `exchangeColumn` and stored in `slugColumn` key without changing his main functionality
              // Therefore, changing the path with a more friendly format from
              // `/product/detail/2e4c49d2-8187-11eb-a1c1-0c4de9a75a56` to `/product/product-name`.
        ]
    ]

Remember that you can add the slug configuration only to a valid registered route !

For redirect response you must use UrlHelperPlugin::class to generate the url, this class can detect the slug configuration.

The local.php.dist file provides an example for working with multiple languages. The translator variable can be expanded to other languages using Poedit 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: Do not enable dev mode in production

• Run the following command in your project's directory to start PHPs built-in server:

$ php -S 0.0.0.0:8080 -t public

Running command composer serve will do the exact same, but the above is faster.

0.0.0.0 means that the server is open to all incoming connections 127.0.0.1 means that the server can only be accessed locally (localhost only) 8080 the port on which the server is started (the listening port for the server)

NOTE: If you are still getting exceptions or errors regarding some missing services, try running the following command

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

• Open a web browser and visit http://localhost:8080/

You should see the DotKernel Frontend welcome page.