====== Yii2 Basic App with Docker ======

This How-To describes setting up a Docker stack with the Yii2 Basic App template.

The application will use a MariaDB database and activate a users management module.

All example commands below were entered in a Windows Command shell.

__**Note:**__

When you have to enter commands spanning over multiple lines, on Windows you have to enter `^` at the end of command lines instead of the backslash `\` shown below.

===== Basic Project Setup =====

  * Clone the git repository:

<code bash>
$ git clone https://github.com/yiisoft/yii2-app-basic.git my-yii-app
$ cd my-yii-app
</code>

  * Update the vendor packages:

<code bash>
$ docker-compose run --rm php composer update --prefer-dist
</code>

  * Run the installation triggers (e.g. creating cookie validation code):

<code bash>
$ docker-compose run --rm php composer install    
</code>

  * Start the container:

<code bash>
$ docker-compose up -d
</code>

You can then access the application through the following URL:

[[http://127.0.0.1:8000]]

  * To stop all the services:

<code bash>
$ docker-compose stop
</code>
===== Adding a Database =====

  * Edit the file ''docker-compose.yaml'':

<code yaml docker-compose.yaml>
version: '3'
services:
  php:
    image: yiisoftware/yii2-php:7.3-apache
    volumes:
      - ~/.composer-docker/cache:/root/.composer/cache:delegated
      - ./:/app:delegated
    ports:
      - '8000:80'
    links:
      - mariadb
  mariadb:
    image: mariadb:10.1
    volumes:
        - mariadb:/var/lib/mysql
    environment:
        TZ: "Europe/Berlin"
        MYSQL_ALLOW_EMPTY_PASSWORD: "no"
        MYSQL_ROOT_PASSWORD: "rootpw"
        MYSQL_USER: 'testuser'
        MYSQL_PASSWORD: 'testpassword'
        MYSQL_DATABASE: 'testdb'
volumes:
    mariadb:
</code>

  * Enter the database credentials in the config file ''db.php'':

<code php config/db.php>
<?php

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=mariadb;dbname=testdb',
    'username' => 'testuser',
    'password' => 'testpassword',
    'charset' => 'utf8',
];
</code>

===== Adding Adminer =====

[[https://www.adminer.org/de/|Adminer]] is a handy script to manage databases, tables and data.

  * Add the following code to ''docker-compose.yaml'':

<code yaml docker-compose.yaml>
services
  ...
  adminer:
    image: adminer
    restart: always
    ports:
      - 8081:8080
</code>

Now you can open the Adminer app in [[http://127.0.0.1:8081/?server=mariadb&username=testuser&db=testdb]].

  * Enter the following credentials:

<code>
Server:   mariadb
Username: testuser
Password: testpassword
Database: testdb
</code>

  * Then click on ''[Login]''.

===== Installing Dektrium/yii2-user =====

[[https://github.com/dektrium/yii2-user|Yii2-user]] is a flexible user registration and authentication module for Yii2.

  * Install it by running:

<code bash>
$ docker-compose run php composer require dektrium/yii2-user
</code>

  * Add the following lines to the main configuration file ''config/web.php'':

<code php>

return [
    ...
    'components' => [
        ...
        /* Comment out to use dektrium user model:
        'user' => [
            ...
        ],
        */
        ...
    ],    
    'modules' => [
        'user' => [
            'class' => 'dektrium\user\Module',
            'enableFlashMessages' => false,  // Don't print flash messages by the module, the app handles printing already
        ],
    ],
    ...
];
</code>

  * Run the database migrations to install required tables (user, profile, token, social_account):

<code bash>
$ docker-compose run php yii migrate/up \
  --migrationPath=@vendor/dektrium/yii2-user/migrations
</code>

==== Registering a First User ====

In order to register yourself as a first user, open http://127.0.0.1:8000/index.php?r=user/registration/register .

  * Enter your username, email and password, then submit the form.

In the examples below, we use theadminuser as an example username.

  * Check the folder ''runtime/mail/'' for a new email file (*.eml)
  * Open the email .eml file
  * Click the confirmation link which you will find in the email

The link looks something like this::

''http://127.0.0.1:8000/index.php?r=user%2Fregistration%2Fconfirm&id=1&code=...''

The application is opened and a confirmation message is shown:

    Thank you, registration is now complete.

==== Changing Menu Links ====

Now some links regarding user functionality in the page template need to be changed, e.g.

  * Login
  * Logout
  * Change user settings

  * Edit the file ''views/layout/main.php'':

<code php>
// Setup menu items
$menuItems = [];
$menuItems[] = ['label' => 'Home', 'url' => ['/site/index']];
if(!Yii::$app->user->isGuest and in_array(Yii::$app->user->identity->username, Yii::$app->params['userAdmins'])) {
    $menuItems[] = ['label' => 'Users Admin', 'url' => ['/user/admin']];
}
$menuItems[] = ['label' => 'About', 'url' => ['/site/about']];
$menuItems[] = ['label' => 'Contact', 'url' => ['/site/contact']];
if (Yii::$app->user->isGuest) {
    $menuItems[] = ['label' => 'Signup', 'url' => ['/user/registration/register']];
    $menuItems[] = ['label' => 'Login', 'url' => ['/user/security/login']];
} else {
    $menuItems[] = ['label' => 'Settings', 'url' => ['/user/settings']];
    $menuItems[] = ['label' => 'Logout (' . Yii::$app->user->identity->username . ')', 'url' => ['/user/security/logout'], 'linkOptions' => ['data-method' => 'post']];
}

...

echo Nav::widget([
    'options' => ['class' => 'navbar-nav navbar-right'],
    // Change:
    'items' => $menuItems,
]);
</code>

==== Adding an Admin User ====

The yii2-user module provides an administration view to manage users.

In order to access it, you need to configure a list of usernames who are allowed to use the view.

  * Edit the file ''config/params.php'':

<code php params.php>
<?php
return [
    ...
    // Users Module / Admin usernames
    'userAdmins' => ['theadminuser'],
];
</code>

  * Edit the file ''config/web.php'':

<code php web.php>
...
'modules' => [
    'user' => [
        'class' => 'dektrium\user\Module',
        // Admin users: see config/params.php
        'admins' => $params['userAdmins'],
    ],
],
...
</code>

You may now open the user administration screen using the URL

http://127.0.0.1:8000/index.php?r=user/admin

You will see a GridView with already registered users. From here you can edit users or create new ones.

===== Links =====

  * [[https://github.com/yiisoft/yii2-app-basic|Yii2 Basic App on GitHub]]
  * [[https://www.diggin-data.de/dd-cms/post/1003/Getting+Started+with+Yii2|Getting Started with Yii2]]