Migration guide from Dektrium tools

yii2-usuario is 99% compatible with dektrium tools.

Package removal

First of all you need to remove the old packages. Depending on your installation you need to remove one or both:

composer remove dektrium/yii2-user
composer remove dektrium/yii2-rbac

Install yii2-usuario

composer require 2amigos/yii2-usuario

Configuration

Configure the config/console.php stuff:

        'authManager' => [
            'class' => 'yii\rbac\DbManager',
        ],

Configure the controller map for migrations

    'controllerMap' => [
        'migrate' => [
            'class' => 'yii\console\controllers\MigrateController',
            'migrationNamespaces' => [
                'Da\User\Migration',
            ],
        ],
    ],

Remove the modules > rbac configuration parameter, and replace the value of modules > user with:

    'user' => Da\User\Module::class,

In config/web.php remove module > rbac configuration and change the modules > user with:

    ...
        'user' => [
            'class' => Da\User\Module::class,
            // Othe yii2-usuario configuration parameters
            'enableRegistration' => false,
        ],
    ...

If you had modelMap customization you have to replace them with classMap.
In your extended model replace the BaseUser inheritance from dektrium\user\models\User to Da\User\Model\User
If you had controller remapping replace the inheritance from dektrium\user\controllers\XX to Da\User\Controller\XX
Some properties has been renamed: from enableConfirmation to enableEmailConfirmation; from enableGeneratingPassword to generatePasswords
Restore Identity url rule has been renamed: from /user/admin/switch to /user/admin/switch-identity
Restore Identity session checker has changes: from

if (Yii::$app->session->has(\dektrium\user\controllers\AdminController::ORIGINAL_USER_SESSION_KEY))

/** @var Da\User\Module $module */
$module = Yii::$app->getModule('user');
if(Yii::$app->session->has($module->switchIdentitySessionKey))

If you use event of Controllers see events chapter of this docs. All of relative controller constant has been move to events class:
from \dektrium\user\controllers\RecoveryController::EVENT_AFTER_REQUEST to \Da\User\Event\FormEvent::EVENT_AFTER_REQUEST,
from \dektrium\user\controllers\RecoveryController::EVENT_AFTER_RESET to \Da\User\Event\ResetPasswordEvent::EVENT_AFTER_RESET, etc.
Map of constants can be find in events chapter of this docs.

BackendFilter and FrontendFilter

BackendFilter disable this controllers: 'profile', 'recovery', 'registration', 'settings'; FrontendFilter disable this controller: 'admin';

This functionality has been dropped. Use deny rule in your configuration directly. For example change frontend config like this:

    'modules' => [
        'user' => [
            'controllerMap' => [
                'admin' => [
                    'class' => Da\User\Controller\AdminController::class,
                    'as access' => [
                        'class' => yii\filters\AccessControl::class,
                        'rules' => [['allow' => false]],
                    ],
                ],
                'role' => [
                    'class' => Da\User\Controller\RoleController::class,
                    'as access' => [
                        'class' => yii\filters\AccessControl::class,
                        'rules' => [['allow' => false]],
                    ],
                ],
                'permission' => [
                    'class' => Da\User\Controller\PermissionController::class,
                    'as access' => [
                        'class' => yii\filters\AccessControl::class,
                        'rules' => [['allow' => false]],
                    ],
                ],
                'rule' => [
                    'class' => Da\User\Controller\RuleController::class,
                    'as access' => [
                        'class' => yii\filters\AccessControl::class,
                        'rules' => [['allow' => false]],
                    ],
                ],
            ],
        ],
    ],

Mark migrations as applied in an existing project

If you already have a production project which has all the necessary user tables from dektrium simply run the following commands to mark some migrations as already applied.

./yii migrate/mark "Da\User\Migration\m000000_000005_add_last_login_at"
./yii migrate/to "Da\User\Migration\m000000_000007_enable_password_expiration"

The first command will mark the migration as applied, the second will apply missing migrations. The second command is optional as a simple ./yii migrate/up would apply all missing migrations anyway.

Rbac migrations

yii2-rbac have a nice tool which are rbac migrations, which help writing new permissions and roles. There's no such feature in yii2-usuario, but in case you need to still apply them you can:

create a migration component which basically it's the same as the original Migration object, with some minor changes. Copy the content below and save it in your @app/components/RbacMigration.php:

```php <?php

/ * This file is part of the Dektrium project. * * (c) Dektrium project http://github.com/dektrium/ * * For the full copyright and license information, please view the LICENSE * file that was distributed with this source code. /

namespace app\components;

use yii\rbac\DbManager; use yii\db\Migration; use yii\di\Instance; use yii\rbac\Item; use yii\rbac\Permission; use yii\rbac\Role; use yii\rbac\Rule;

/ * Migration for applying new RBAC items. * * @author Dmitry Erofeev dmeroff@gmail.com */ class RbacMigration extends Migration { / * @var string|DbManager The auth manager component ID that this migration should work with. */ public $authManager = 'authManager';

/**
 * Initializes the migration.
 * This method will set [[authManager]] to be the 'authManager' application component, if it is `null`.
 */
public function init()
{
    parent::init();

    $this->authManager = Instance::ensure($this->authManager, DbManager::className());
}

/**
 * Creates new permission.
 *
 * @param  string      $name        The name of the permission
 * @param  string      $description The description of the permission
 * @param  string|null $ruleName    The rule associated with the permission
 * @param  mixed|null  $data        The additional data associated with the permission
 * @return Permission
 */
protected function createPermission($name, $description = '', $ruleName = null, $data = null)
{
    echo "    > create permission $name ...";
    $time       = microtime(true);
    $permission = $this->authManager->createPermission($name);

    $permission->description = $description;
    $permission->ruleName    = $ruleName;
    $permission->data        = $data;

    $this->authManager->add($permission);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";

    return $permission;
}

/**
 * Creates new role.
 *
 * @param  string      $name        The name of the role
 * @param  string      $description The description of the role
 * @param  string|null $ruleName    The rule associated with the role
 * @param  mixed|null  $data        The additional data associated with the role
 * @return Role
 */
protected function createRole($name, $description = '', $ruleName = null, $data = null)
{
    echo "    > create role $name ...";
    $time = microtime(true);
    $role = $this->authManager->createRole($name);

    $role->description = $description;
    $role->ruleName    = $ruleName;
    $role->data        = $data;

    $this->authManager->add($role);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";

    return $role;
}

/**
 * Creates new rule.
 *
 * @param  string       $ruleName   The name of the rule
 * @param  string|array $definition The class of the rule
 * @return Rule
 */
protected function createRule($ruleName, $definition)
{
    echo "    > create rule $ruleName ...";
    $time = microtime(true);

    if (is_array($definition)) {
        $definition['name'] = $ruleName;
    } else {
        $definition = [
            'class' => $definition,
            'name' => $ruleName,
        ];
    }

    /** @var Rule $rule */
    $rule = \Yii::createObject($definition);

    $this->authManager->add($rule);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";

    return $rule;
}

/**
 * Finds either role or permission or throws an exception if it is not found.
 *
 * @param  string $name
 * @return Permission|Role|null
 */
protected function findItem($name)
{
    $item = $this->authManager->getRole($name);

    if ($item instanceof Role) {
        return $item;
    }

    $item = $this->authManager->getPermission($name);

    if ($item instanceof Permission) {
        return $item;
    }

    return null;
}

/**
 * Finds the role or throws an exception if it is not found.
 *
 * @param  string $name
 * @return Role|null
 */
protected function findRole($name)
{
    $role = $this->authManager->getRole($name);

    if ($role instanceof Role) {
        return $role;
    }

    return null;
}

/**
 * Finds the permission or throws an exception if it is not found.
 *
 * @param  string $name
 * @return Permission|null
 */
protected function findPermission($name)
{
    $permission = $this->authManager->getPermission($name);

    if ($permission instanceof Permission) {
        return $permission;
    }

    return null;
}

/**
 * Removes auth item.
 *
 * @param string|Item $item Either item name or item instance to be removed.
 */
protected function removeItem($item)
{
    if (is_string($item)) {
        $item = $this->findItem($item);
    }

    echo "    > removing $item->name ...";
    $time = microtime(true);
    $this->authManager->remove($item);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";
}

/**
 * Adds child.
 * 
 * @param Item|string $parent Either name or Item instance which is parent
 * @param Item|string $child  Either name or Item instance which is child
 */
protected function addChild($parent, $child)
{
    if (is_string($parent)) {
        $parent = $this->findItem($parent);
    }

    if (is_string($child)) {
        $child = $this->findItem($child);
    }

    echo "    > adding $child->name as child to $parent->name ...";
    $time = microtime(true);
    $this->authManager->addChild($parent, $child);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";
}

/**
 * Assigns a role to a user.
 *
 * @param string|Role $role
 * @param string|int  $userId
 */
protected function assign($role, $userId)
{
    if (is_string($role)) {
        $role = $this->findRole($role);
    }

    echo "    > assigning $role->name to user $userId ...";
    $time = microtime(true);
    $this->authManager->assign($role, $userId);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";
}

/**
 * Updates role.
 *
 * @param  string|Role $role
 * @param  string      $description
 * @param  string      $ruleName
 * @param  mixed       $data
 * @return Role
 */
protected function updateRole($role, $description = '', $ruleName = null, $data = null)
{
    if (is_string($role)) {
        $role = $this->findRole($role);
    }

    echo "    > update role $role->name ...";
    $time = microtime(true);

    $role->description = $description;
    $role->ruleName    = $ruleName;
    $role->data        = $data;

    $this->authManager->update($role->name, $role);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";

    return $role;
}

/**
 * Updates permission.
 *
 * @param  string|Permission $permission
 * @param  string            $description
 * @param  string            $ruleName
 * @param  mixed             $data
 * @return Permission
 */
protected function updatePermission($permission, $description = '', $ruleName = null, $data = null)
{
    if (is_string($permission)) {
        $permission = $this->findPermission($permission);
    }

    echo "    > update permission $permission->name ...";
    $time = microtime(true);

    $permission->description = $description;
    $permission->ruleName    = $ruleName;
    $permission->data        = $data;

    $this->authManager->update($permission->name, $permission);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";

    return $permission;
}

/**
 * Updates rule.
 *
 * @param  string $ruleName
 * @param  string $className
 * @return Rule
 */
protected function updateRule($ruleName, $className)
{
    echo "    > update rule $ruleName ...";
    $time = microtime(true);

    /** @var Rule $rule */
    $rule = \Yii::createObject([
        'class' => $className,
        'name'  => $ruleName,
    ]);

    $this->authManager->update($ruleName, $rule);
    echo ' done (time: ' . sprintf('%.3f', microtime(true) - $time) . "s)\n";

    return $rule;
}

} ```

change the inheritance of the @app/rbac/migrations files to app\components\RbacMigration as Migration

... and you're done! You can still apply your rbac migrations with ./yii migrate/up --migrationPath=@app/rbac/migrations.

To create a new migration just run yii migrate/create name_your_migration --migrationPath=@app/rbac/migrations and remember to change parent class.

Keys	Action
`?`	Open this help
`←`	Previous page
`→`	Next page
`s`	Search