yii2-extension module-user-management

mauztor/module-user-management

User with improved RBAC

User management module for Yii 2, _(*1)

===== forked from webvimark/user-management, _(*2)

Perks

• User management
• RBAC (roles, permissions and stuff) with web interface
• Registration, authorization, password recovery and so on
• Visit log
• Optimised (zero DB queries during usual user workflow)
• Nice widgets like GhostMenu or GhostHtml::a where elements are visible only if user has access to route where they point

Installation

The preferred way to install this extension is through composer., _(*3)

Either run, _(*4)

composer require webvimark/module-user-management

or add, _(*5)

"mauztor/module-user-management": "^1"

to the require section of your composer.json file., _(*6)

Configuration

1) In your config/web.php, _(*7)

'components'=>[
    'user' => [
        'class' => 'mauztor\modules\UserManagement\components\UserConfig',

        // Comment this if you don't want to record user logins
        'on afterLogin' => function($event) {
                \mauztor\modules\UserManagement\models\UserVisitLog::newVisitor($event->identity->id);
            }
    ],
],

'modules'=>[
    'user-management' => [
        'class' => 'mauztor\modules\UserManagement\UserManagementModule',

        // 'enableRegistration' => true,

        // Add regexp validation to passwords. Default pattern does not restrict user and can enter any set of characters.
        // The example below allows user to enter :
        // any set of characters
        // (?=\S{8,}): of at least length 8
        // (?=\S*[a-z]): containing at least one lowercase letter
        // (?=\S*[A-Z]): and at least one uppercase letter
        // (?=\S*[\d]): and at least one number
        // $: anchored to the end of the string

        //'passwordRegexp' => '^\S*(?=\S{8,})(?=\S*[a-z])(?=\S*[A-Z])(?=\S*[\d])\S*$',


        // Here you can set your handler to change layout for any controller or action
        // Tip: you can use this event in any module
        'on beforeAction'=>function(yii\base\ActionEvent $event) {
                if ( $event->action->uniqueId == 'user-management/auth/login' )
                {
                    $event->action->controller->layout = 'loginLayout.php';
                };
            },
    ],
],

To learn about events check:, _(*8)

• http://www.yiiframework.com/doc-2.0/guide-concept-events.html
• http://www.yiiframework.com/doc-2.0/guide-concept-configurations.html#configuration-format

Layout handler example in AuthHelper::layoutHandler(), _(*9)

To see full list of options check UserManagementModule file, _(*10)

2) In your config/console.php (this is needed for migrations and working with console), _(*11)

'modules'=>[
    'user-management' => [
        'class' => 'mauztor\modules\UserManagement\UserManagementModule',
            'controllerNamespace'=>'vendor\mauztor\modules\UserManagement\controllers', // To prevent yii help from crashing
    ],
],

3) Run migrations, _(*12)

./yii migrate --migrationPath=vendor/mauztor/module-user-management/migrations/

4) In you base controller, _(*13)

public function behaviors()
{
    return [
        'ghost-access'=> [
            'class' => 'mauztor\modules\UserManagement\components\GhostAccessControl',
        ],
    ];
}

Where you can go

false,
    'activateParents'=>true,
    'items' => [
        [
            'label' => 'Backend routes',
            'items'=>UserManagementModule::menuItems()
        ],
        [
            'label' => 'Frontend routes',
            'items'=>[
                ['label'=>'Login', 'url'=>['/user-management/auth/login']],
                ['label'=>'Logout', 'url'=>['/user-management/auth/logout']],
                ['label'=>'Registration', 'url'=>['/user-management/auth/registration']],
                ['label'=>'Change own password', 'url'=>['/user-management/auth/change-own-password']],
                ['label'=>'Password recovery', 'url'=>['/user-management/auth/password-recovery']],
                ['label'=>'E-mail confirmation', 'url'=>['/user-management/auth/confirm-email']],
            ],
        ],
    ],
]);
?>

First steps

From the menu above at first you'll se only 2 element: "Login" and "Logout" because you have no permission to visit other urls and to render menu we using GhostMenu::widget(). It's render only element that active user can visit., _(*14)

Also same functionality has GhostNav::widget() and GhostHtml:a(), _(*15)

1) Login as superadmin/superadmin, _(*16)

2) Go to "Permissions" and play there, _(*17)

3) Go to "Roles" and play there, _(*18)

4) Go to "User" and play there, _(*19)

5) Relax, _(*20)

Usage

You controllers may have two properties that will make whole controller or selected action accessible to everyone, _(*21)

public $freeAccess = true;

Or, _(*22)

public $freeAccessActions = ['first-action', 'another-action'];

Here are list of the useful helpers. For detailed explanation look in the corresponding functions., _(*23)

User::hasRole($roles, $superAdminAllowed = true)
User::hasPermission($permission, $superAdminAllowed = true)
User::canRoute($route, $superAdminAllowed = true)

User::assignRole($userId, $roleName)
User::revokeRole($userId, $roleName)

User::getCurrentUser($fromSingleton = true)

Role, Permission and Route all have following methods, _(*24)

Role::create($name, $description = null, $groupCode = null, $ruleName = null, $data = null)
Role::addChildren($parentName, $childrenNames, $throwException = false)
Role::removeChildren($parentName, $childrenNames)

Events

Events can be handled via config file like following, _(*25)

'modules'=>[
    'user-management' => [
        'class' => 'mauztor\modules\UserManagement\UserManagementModule',
        'on afterRegistration' => function(UserAuthEvent $event) {
            // Here you can do your own stuff like assign roles, send emails and so on
        },
    ],
],

List of supported events can be found in UserAuthEvent class, _(*26)

FAQ

Question: Do you have API docs?, _(*27)

Answer: Check this one http://opensource.id5.com.br/webvimark/doc/index.html (Credits to lukBarros), _(*28)

Question: I want users to register and login with they e-mails! Mmmmm... And they should confirm it too!, _(*29)

Answer: See configuration properties $useEmailAsLogin and $emailConfirmationRequired, _(*30)

Question: I want to have profile for user with avatar, birthday and stuff. What should I do ?, _(*31)

Answer: Profiles are to project-specific, so you'll have to implement them yourself (but you can find example here - https://github.com/webvimark/user-management/wiki/Profile-and-custom-registration). Here is how to do it without modifying this module, _(*32)

1) Create table and model for profile, that have user_id (connect with "user" table), _(*33)

2) Check AuthController::actionRegistration() how it works (you can skip this part), _(*34)

3) Define your layout for registration. Check example in AuthHelper::layoutHandler(). Now use theming to change registraion.php file, _(*35)

4) Define your own UserManagementModule::$registrationFormClass. In this class you can do whatever you want like validating custom forms and saving profiles, _(*36)

5) Create your controller where user can view profiles, _(*37)