468 lines
15 KiB
Markdown
468 lines
15 KiB
Markdown
# Migration guide from Dektrium tools
|
||
|
||
yii2-usuario is 99% compatible with [dektrium](https://github.com/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:
|
||
|
||
```php
|
||
'authManager' => [
|
||
'class' => 'yii\rbac\DbManager',
|
||
],
|
||
```
|
||
|
||
Configure the controller map for migrations
|
||
|
||
```php
|
||
'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:
|
||
```php
|
||
'user' => Da\User\Module::class,
|
||
```
|
||
|
||
In `config/web.php` remove *module > rbac* configuration and change the *modules > user* with:
|
||
```php
|
||
...
|
||
'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
|
||
```php
|
||
if (Yii::$app->session->has(\dektrium\user\controllers\AdminController::ORIGINAL_USER_SESSION_KEY))
|
||
```
|
||
to
|
||
```php
|
||
/** @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](../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](../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](https://github.com/dektrium/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:
|
||
|
||
1. create a migration component which basically it's the same as the original [Migration](https://github.com/dektrium/yii2-rbac/blob/master/migrations/Migration.php) 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;
|
||
}
|
||
}
|
||
```
|
||
|
||
2. 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.
|