<?php

namespace app\ht\exts\rbac;

/**
 * @author Nemo Luo <378107001@qq,com>
 * @since 2.0
 */
interface ManagerInterface
{
    /**
     * Checks if the user has the specified permission.
     * @param string|integer $userId the user ID. This should be either an integer or a string representing
     * the unique identifier of a user. See [[\yii\web\User::id]].
     * @param string $permissionName the name of the permission to be checked against
     * @param array $params name-value pairs that will be passed to the rules associated
     * with the roles and permissions assigned to the user.
     * @return boolean whether the user has the specified permission.
     * @throws \yii\base\InvalidParamException if $permissionName does not refer to an existing permission
     */
    public function checkAccess($userId, $permissionName, $params);

    /**
     * Creates a new Role object.
     * Note that the newly created role is not added to the RBAC system yet.
     * You must fill in the needed data and call [[add()]] to add it to the system.
     * @param string $name the role name
     * @return Role the new Role object
     */
    public function createRole($roleId);


    /**
     * Adds a role to the RBAC system.
     * @param Role $object
     * @return boolean whether the role is successfully added to the system
     * @throws \Exception if data validation or saving fails (such as the name of the role is not unique)
     */
    public function addRole($object);

    /**
     * Removes a role from the RBAC system.
     * @param Role $object
     * @return boolean whether the role is successfully removed
     */
    public function removeRole($object);

    /**
     * Updates the specified role in the system.
     * @param string $name the old name of the role, permission or rule
     * @param Role| $object
     * @return boolean whether the update is successful
     * @throws \Exception if data validation or saving fails (such as the name of the role is not unique)
     */
    public function updateRole($roleId, $object);

    /**
     * Returns the named role.
     * @param string $name the role name.
     * @return null|Role the role corresponding to the specified name. Null is returned if no such role.
     */
    public function getRole($roleId);

    /**
     * Returns all roles in the system.
     * @return Role[] all roles in the system. The array is indexed by the role names.
     */
    public function getRoles();

    /**
     * Returns the roles that are assigned to the user via [[assign()]].
     * Note that child roles that are not assigned directly to the user will not be returned.
     * @param string|integer $userId the user ID (see [[\yii\web\User::id]])
     * @return Role[] all roles directly assigned to the user. The array is indexed by the role names.
     */
    public function getRolesByUser($userId);

    /**
     * Returns the named permission.
     * @param string $name the permission name.
     * @return null|Perm the permission corresponding to the specified name. Null is returned if no such permission.
     */
    public function getPerm($permId);

    /**
     * Returns all permissions in the system.
     * @return Perm[] all permissions in the system. The array is indexed by the permission names.
     */
    public function getPerms();

    /**
     * Returns all permissions that the specified role represents.
     * @param string $roleName the role name
     * @return Perm[] all permissions that the role represents. The array is indexed by the permission names.
     */
    public function getPermsByRole($roleId);

    /**
     * Returns all permissions that the user has.
     * @param string|integer $userId the user ID (see [[\yii\web\User::id]])
     * @return Perm[] all permissions that the user has. The array is indexed by the permission names.
     */
    public function getPermsByUser($userId);

    /**
     * Assigns a role to a user.
     *
     * @param Role $role
     * @param string|integer $userId the user ID (see [[\yii\web\User::id]])
     * @return Assignment the role assignment information.
     * @throws \Exception if the role has already been assigned to the user
     */
    public function assign($role, $userId);

    /**
     * Returns the assignment information regarding a role and a user.
     * @param string $roleName the role name
     * @param string|integer $userId the user ID (see [[\yii\web\User::id]])
     * @return null|Assignment the assignment information. Null is returned if
     * the role is not assigned to the user.
     */
    public function getAssignment($roleId, $userId);

    /**
     * Returns all role assignment information for the specified user.
     * @param string|integer $userId the user ID (see [[\yii\web\User::id]])
     * @return Assignment[] the assignments indexed by role names. An empty array will be
     * returned if there is no role assigned to the user.
     */
    public function getAssignments($userId);

    /**
     * Revokes a role from a user.
     * @param Role $role
     * @param string|integer $userId the user ID (see [[\yii\web\User::id]])
     * @return boolean whether the revoking is successful
     */
    public function revoke($role, $userId);

    /**
     * Revokes all roles from a user.
     * @param mixed $userId the user ID (see [[\yii\web\User::id]])
     * @return boolean whether the revoking is successful
     */
    public function revokeAll($userId);


    /**
     * Returns all user IDs assigned to the role specified.
     * @param string $roleName
     * @return array array of user ID strings
     * @since 2.0.7
     */
    public function getUserIdsByRole($roleId);

}