Skip to content

Latest commit

 

History

History
300 lines (209 loc) · 7.72 KB

README.md

File metadata and controls

300 lines (209 loc) · 7.72 KB
Raw

User management module for Yii 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

Features of this fork

  • Correct maximum length of an e-mail address
  • Improved Spanish translation
  • LDAP support

Installation

The preferred way to install this extension is through composer.

Add the following lines to your composer.json file:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/quique/user-management"
    }
],
"require": {
	"webvimark/module-user-management": "dev-dev",
},

Configuration

  1. In your config/web.php
'components' => [
	'user' => [
		// 'identityClass' => 'app\models\User',
		'enableLdap' => false, // Change it to true to enable LDAP authentication
		'class' => 'webvimark\modules\UserManagement\components\UserConfig',

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

'modules' => [
	'user-management' => [
		'class' => 'webvimark\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';
			};
		},
	],
],

If needed, you can extend the base User class in app/models/User.php (change the identityClass in the configuration accordingly):

<?php
namespace app\models;

use webvimark\modules\UserManagement\models\User as BaseUser;
// use Yii;
// use yii\web\ServerErrorHttpException;

class User extends BaseUser
{
    // Your custom stuff (vg your own getUserAttributes() function)
}

To learn about events check:

Layout handler example in AuthHelper::layoutHandler()

To see full list of options check UserManagementModule file

  1. In your config/console.php (this is needed for migrations and working with console)
'modules'=>[
	'user-management' => [
		'class' => 'webvimark\modules\UserManagement\UserManagementModule',
	    'controllerNamespace'=>'vendor\webvimark\modules\UserManagement\controllers', // To prevent yii help from crashing
	],
],
  1. Run migrations
./yii migrate --migrationPath=vendor/webvimark/module-user-management/migrations/
  1. In you base controller
public function behaviors()
{
	return [
		'ghost-access'=> [
			'class' => 'webvimark\modules\UserManagement\components\GhostAccessControl',
		],
	];
}
  1. If you want to use LDAP authentication, add these lines to your params:
'ldap' => [
    'host' => 'ldapserver.domain.net',
    'port' => 389,
    'base_dn' => 'ou=unit, dc=domain, dc=net', // Base Distinguished Name
],

Where you can go

<?php
use webvimark\modules\UserManagement\components\GhostMenu;
use webvimark\modules\UserManagement\UserManagementModule;

echo GhostMenu::widget([
	'encodeLabels' => 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.

Also same functionality has GhostNav::widget() and GhostHtml:a()

  1. Login as superadmin/superadmin

  2. Go to "Permissions" and play there

  3. Go to "Roles" and play there

  4. Go to "User" and play there

  5. Relax

Usage

You controllers may have two properties that will make whole controller or selected action accessible to everyone

public $freeAccess = true;

Or

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

Here are list of the useful helpers. For detailed explanation look in the corresponding functions.

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

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

'modules' => [
	'user-management' => [
		'class' => 'webvimark\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

FAQ

Question: Do you have API docs?

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

Question: I want users to register and login with they e-mails! Mmmmm... And they should confirm it too!

Answer: See configuration properties $useEmailAsLogin and $emailConfirmationRequired

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

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

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

  2. Check AuthController::actionRegistration() how it works (you can skip this part)

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

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

  5. Create your controller where user can view profiles