search

sjaakp / yii2-pluto

User management extension for Yii2
https://demo.sjaakpriester.nl/
MIT License
8 stars 12 forks source link

readme

yii2-pluto

User management module for Yii2 framework

Latest Stable Version Total Downloads License

Pluto is a complete user management module for the Yii 2.0 PHP Framework.

It manages log in and log out of users, sign up, email-confirmation, blocking and assigning roles. Users can change their email-address, ask for a reset of their password. The site administrator can define roles and permissions and assign permissions to roles.

A demonstration of Pluto is here.

Prerequisites

Pluto relies on Role-Based Access Control (RBAC). Therefore, the authManager application component has to be configured. Pluto works with Yii's PhpManager as well as with the DbManager.

Because Pluto sends emails, the mailer component of the application has to be up and running. Be sure that the 'adminEmail' parameter of the application has a sensible value. If you prefer, you may set the 'supportEmail' parameter as well; if set, Pluto will use this.

Pluto uses Yii2 flash messages, so these have to be configured as well. If the site is set up using one of Yii's project templates, this will be taken care of.

Installation

Install yii2-pluto in the usual way with Composer. Add the following to the require section of your composer.json file:

"sjaakp/yii2-pluto": "*"

or run:

composer require sjaakp/yii2-pluto

You can manually install yii2-pluto by downloading the source in ZIP-format.

Module

Pluto is a module in the Yii2 framework. It has to be configured in the main configuration file, usually called web.php in the config directory. Add the following to the configuration array:

<?php
// ...
'modules' => [
    'pluto' => [
        'class' => 'sjaakp\pluto\Module',
        // several options
    ],
],
// ...

The module has to be bootstrapped. Do this by adding the following to the application configuration array:

<php
// ...
'bootstrap' => [
    'pluto',
]
// ...

There probably already is a bootstrap property in your configuration file; just add 'pluto' to it.

Important: the module should also be set up in the same way in the console configuration (usually called console.php). Notice that in some setups, there may be a main.php containing the configuration for both web and console tiers. A notable example is the Yii2 advanced template.

Console commands

To complete the installation, two console commands have to be run. The first will create a database table for the users:

yii migrate

The migration applied is called sjaakp\pluto\migrations\m000000_000000_init.

The second console command is:

yii pluto

This will set up the basic roles and permissions.

Actions

Pluto adds a bunch of actions to the application. The most important are:

Route Description
/pluto/login to log in
/pluto/logout to log out
/pluto/signup to sign up (register)
/pluto/forgot if the user forgot her password
/pluto/settings to change name or email-address
/pluto/download to download user data in human and machine readable form (requirement of European legislation)
/pluto/delete to be completely forgotten by the site (also a requirement of the EU)
/pluto/user User management (only for 'support' and 'admin' Roles)
/pluto/role Role management (only for 'admin')

Roles

After installation of Pluto, the site recognizes two user Roles and a few Permissions. Read more about them in the Authorization chapter of the Yii-guide. The installed Roles are:

Role Description
'support' user who can manage user data (except those from 'admin')
'admin' user with unlimited Permissions, like creating more Roles and Permissions

Integrate in the user interface

Now that Pluto is installed, it has to be integrated in the user interface of the site. There are dozens of ways to accomplish this, but here are some general guidelines:

LoginMenu is a widget to integrate Pluto in the site's main menu:

<?php
use ...
use sjaakp\pluto\widgets\LoginMenu

$user = Yii::$app->user;

$navItems = [
    ['label' => 'Home', 'url' => '/' ],
    // ...
    ['label' => 'About', 'url' => ['/site/about']],
    // ... more menu items ...,
    LoginMenu::widget([
        'options' => [
           'class' => 'bg-primary'
        ]
    ]),
];

NavBar::begin([
    'options' => [
        'class' => '... navbar-dark bg-primary',
    ],
    // ... more NavBar options ...
]);
echo Nav::widget([
    'items' => $navItems,
]);
NavBar::end();

Take care to give LoginMenu the same background defining CSS class as NavBar, for instance bg-primary.

Options

The Pluto module has an extensive range of options. They are set in the application configuration like so:

 <?php
 // ...
 'modules' => [
     'pluto' => [
         'class' => 'sjaakp\pluto\Module',
         'passwordHint' => 'At least eight characters, one uppercase, one digit',
         // ...
         // ... more options ...
     ],
 ],
 // ...

The options (all are optional) are:

Profile

Apart from the User model, users can also have a Profile model. This can hold extra information that's intended to be public: a short bio, profile photo, avatar, location and the like. Pluto doesn't implement a Profile model itself, but it does support it.

A Profile is a standard ActiveRecord with one, very important, peculiarity: it's id field is not auto-incrementing.

Instead, the id field in the Profile's database table should be declared UNIQUE. The Profile takes the same id as the User it is associated with.

The Profile model should be configured as profileClass in Pluto's configuration.

Instead of just the class name, the 'profile' component can also be initialized with a configuration array, with the class name as value of the 'class' element, like on many other places in the Yii2 kingdom.

With this setup, Pluto will automatically create a Profile for each registered user. If a User is deleted, her Profile will be deleted as well.

Roles, Permissions and all that

For the uninitiated, Roles and Permissions can be daunting. The Authorization chapter of the Yii-guide offers some help. Basically, Roles are assigned to Users, and Permissions are used to structure the site. One or more Permissions are assigned to each Role.

Both Roles and Permissions can be subject to Conditions (Yii2 calls these 'Rules'). They are implemented as PHP classes, extending from yii\rbac\Rule. Pluto looks under namespace 'app\rbac' (settable by option ruleNamespace) for unregistered Condition's and offers 'admin' an opportunity to register them.

Pluto avoids the somewhat misleading term 'children' with respect to Roles and Permissions. Instead it uses 'Included Roles' or 'Included Permissions'.

Sign up the first 'admin'

With the default set-up, Pluto automatically assigns the 'admin' Role to the first user who signs up. If afterwards you come into a situation without a registered 'admin', there is no possibility to manage Roles. There are several solutions to this puzzle. One is: temporarely set Pluto's defaultRole to 'admin'. The importance of temporarely can't be stretched enough. You'll never want this setting in a live site.

Captcha

Pluto supports Yii2's standard Captcha, as well as Google's reCaptcha v2 ('I am not a robot'). A captcha-challenge will show up in the dialog when one of the passwordFlags is 'captcha'. If himiklab/yii2-recaptcha-widget is installed on the site, it will be Google's reCaptcha v2, otherwise Yii2's standard captcha.

Internationalization

All of Pluto's utterances are translatable. The translations are in the 'sjaakp\pluto\messages' directory.

You can override Pluto's translations by setting the application's message source in the main configuration, like so: 

<?php
// ...
'components' => [
    // ... other components ...     
    'i18n' => [
         'translations' => [
              // ... other translations ...
             'pluto' => [    // override pluto's standard messages
                 'class' => 'yii\i18n\PhpMessageSource',
                 'basePath' => '@app/messages',  // this is a default
                 'sourceLanguage' => 'en-US',    // this as well
             ],
         ],
    ],
    // ... still more components ...
]

The translations should be in a file called 'pluto.php'.

If you want a single or only a few messages translated and use Pluto's translations for the main part, the trick is to set up 'i18n' like above and write your translation file something like:

 <?php
 // app/messages/nl/pluto.php

 $plutoMessages = Yii::getAlias('@sjaakp/pluto/messages/nl/pluto.php');

 return array_merge (require($plutoMessages), [
    'Settings' => 'Instellingen',   // your preferred translation
 ]);

At the moment, only a few languages are implemented: Italian, Russian, and Dutch. Agreed, Dutch is only the world's 52th language, but it happens to be my native tongue. Please, feel invited to translate Pluto in other languages. I'll be more than glad to include them into Pluto's next release.

Override view-files

Any of the Pluto's view files can be overridden, perhaps to add a logo or change the structure. Just set the views setting of the module to something like:

 <?php
 // ...
 'modules' => [
     'pluto' => [
         'class' => 'sjaakp\pluto\Module',
         'views' => [
              'default' => [    // Pluto controller id
                  'login' => <view file>    // action => view
              ]
         ],
         // ...
         // ... more options ...
     ],
 ],
 // ...

<view file> can be of any form [yii\web\controller::render()](https://www.yiiframework.com/doc/api/2.0/yii-base-controller#render()-detail "Yii2") accepts.

Override identity-class

Pluto sets sjaakp\pluto\models\User as identityClass of the application's yii\web\User component. If you're ambitious, you might develop your own identity-class. This should extend from sjaakp\pluto\models\User and be set as Pluto's identityClass option.

Pluto

Pluto happens to be the name of a friendly guard dog I once knew. If you really hate that name, just set up the module like this:

<?php
// ...
'modules' => [
    'saturnus' => [
        'class' => 'sjaakp\pluto\Module',
        // several options
    ],
],
// ...
'bootstrap' => [
    'saturnus',
]
// ...

Your users will never be confronted with the name 'pluto'.

Thanks