UserCreationTrait.php

<?php

declare (strict_types=1);
namespace Drupal\Tests\user\Traits;

use Drupal\Core\Database\DatabaseExceptionWrapper;
use Drupal\Core\Entity\EntityStorageException;
use Drupal\Core\Session\AccountInterface;
use Drupal\KernelTests\KernelTestBase;
use Drupal\user\Entity\Role;
use Drupal\user\Entity\User;
use Drupal\user\RoleInterface;

/**
 * Provides test methods for user creation and authentication.
 *
 * This trait is meant to be used only by test classes.
 */
trait UserCreationTrait {
    
    /**
     * Creates a random user account and sets it as current user.
     *
     * Unless explicitly specified by setting the user ID to 1, a regular user
     * account will be created and set as current, after creating user account 1.
     * Additionally, this will ensure that at least the anonymous user account
     * exists regardless of the specified user ID.
     *
     * @param array $values
     *   (optional) An array of initial user field values.
     * @param array $permissions
     *   (optional) Array of permission names to assign to user. Note that the
     *   user always has the default permissions derived from the "authenticated
     *   users" role.
     * @param bool $admin
     *   (optional) Whether the user should be an administrator with all the
     *   available permissions.
     *
     * @return \Drupal\user\UserInterface
     *   A user account object.
     *
     * @throws \LogicException
     *   If attempting to assign additional roles to the anonymous user account.
     * @throws \Drupal\Core\Entity\EntityStorageException
     *   If the user could not be saved.
     */
    protected function setUpCurrentUser(array $values = [], array $permissions = [], $admin = FALSE) {
        $values += [
            'name' => $this->randomMachineName(),
        ];
        // In many cases the anonymous user account is fine for testing purposes,
        // however, if we need to create a user with a non-empty ID, we need also
        // the "sequences" table.
        if (!\Drupal::moduleHandler()->moduleExists('system')) {
            $values['uid'] = 0;
        }
        // Creating an administrator or assigning custom permissions would result in
        // creating and assigning a new role to the user. This is not possible with
        // the anonymous user account.
        if (($admin || $permissions) && isset($values['uid']) && is_numeric($values['uid']) && $values['uid'] == 0) {
            throw new \LogicException('The anonymous user account cannot have additional roles.');
        }
        $original_permissions = $permissions;
        $original_admin = $admin;
        $original_values = $values;
        $autocreate_user_1 = !isset($values['uid']) || $values['uid'] > 1;
        // No need to create user account 1 if it already exists.
        try {
            $autocreate_user_1 = $autocreate_user_1 && !User::load(1);
        } catch (DatabaseExceptionWrapper $e) {
            // Missing schema, it will be created later on.
        }
        // Save the user entity object and created its schema if needed.
        try {
            if ($autocreate_user_1) {
                $permissions = [];
                $admin = FALSE;
                $values = [];
            }
            $user = $this->createUser($permissions, NULL, $admin, $values);
        } catch (EntityStorageException $e) {
            if ($this instanceof KernelTestBase) {
                $this->installEntitySchema('user');
                $user = $this->createUser($permissions, NULL, $admin, $values);
            }
            else {
                throw $e;
            }
        }
        // Ensure the anonymous user account exists.
        if (!User::load(0)) {
            $values = [
                'uid' => 0,
                'status' => 0,
                'name' => '',
            ];
            User::create($values)->save();
        }
        // If we automatically created user account 1, we need to create a regular
        // user account before setting up the current user service to avoid
        // potential false positives caused by access control bypass.
        if ($autocreate_user_1) {
            $user = $this->createUser($original_permissions, NULL, $original_admin, $original_values);
        }
        $this->setCurrentUser($user);
        return $user;
    }
    
    /**
     * Switch the current logged in user.
     *
     * @param \Drupal\Core\Session\AccountInterface $account
     *   The user account object.
     */
    protected function setCurrentUser(AccountInterface $account) {
        \Drupal::currentUser()->setAccount($account);
    }
    
    /**
     * Create a user with a given set of permissions.
     *
     * @param array $permissions
     *   Array of permission names to assign to user. Note that the user always
     *   has the default permissions derived from the "authenticated users" role.
     * @param string $name
     *   The user name.
     * @param bool $admin
     *   (optional) Whether the user should be an administrator
     *   with all the available permissions.
     * @param array $values
     *   (optional) An array of initial user field values.
     *
     * @return \Drupal\user\Entity\User|false
     *   A fully loaded user object with pass_raw property, or FALSE if account
     *   creation fails.
     *
     * @throws \Drupal\Core\Entity\EntityStorageException
     *   If the user creation fails.
     */
    protected function createUser(array $permissions = [], $name = NULL, $admin = FALSE, array $values = []) {
        // Create a role with the given permission set, if any.
        $rid = FALSE;
        if ($permissions) {
            $rid = $this->createRole($permissions);
            if (!$rid) {
                return FALSE;
            }
        }
        // Create a user assigned to that role.
        $edit = $values;
        if ($name) {
            $edit['name'] = $name;
        }
        elseif (!isset($values['name'])) {
            $edit['name'] = $this->randomMachineName();
        }
        $edit += [
            'mail' => $edit['name'] . '@example.com',
            'pass' => \Drupal::service('password_generator')->generate(),
            'status' => 1,
        ];
        if ($rid) {
            $edit['roles'] = [
                $rid,
            ];
        }
        if ($admin) {
            $edit['roles'][] = $this->createAdminRole();
        }
        $account = User::create($edit);
        $account->save();
        $valid_user = $account->id() !== NULL;
        $this->assertTrue($valid_user, "User created with name {$edit['name']} and pass {$edit['pass']}");
        if (!$valid_user) {
            return FALSE;
        }
        // Add the raw password so that we can log in as this user.
        $account->pass_raw = $edit['pass'];
        // Support BrowserTestBase as well.
        $account->passRaw = $account->pass_raw;
        return $account;
    }
    
    /**
     * Creates an administrative role.
     *
     * @param string $rid
     *   (optional) The role ID (machine name). Defaults to a random name.
     * @param string $name
     *   (optional) The label for the role. Defaults to a random string.
     * @param int $weight
     *   (optional) The weight for the role. Defaults to NULL which sets the
     *   weight to maximum + 1.
     *
     * @return string
     *   Role ID of newly created role, or FALSE if role creation failed.
     */
    protected function createAdminRole($rid = NULL, $name = NULL, $weight = NULL) {
        $rid = $this->createRole([], $rid, $name, $weight);
        if ($rid) {
            
            /** @var \Drupal\user\RoleInterface $role */
            $role = Role::load($rid);
            $role->setIsAdmin(TRUE);
            $role->save();
        }
        return $rid;
    }
    
    /**
     * Creates a role with specified permissions.
     *
     * @param array $permissions
     *   Array of permission names to assign to role.
     * @param string $rid
     *   (optional) The role ID (machine name). Defaults to a random name.
     * @param string $name
     *   (optional) The label for the role. Defaults to a random string.
     * @param int $weight
     *   (optional) The weight for the role. Defaults to NULL which sets the
     *   weight to maximum + 1.
     *
     * @return string
     *   Role ID of newly created role, or FALSE if role creation failed.
     */
    protected function createRole(array $permissions, $rid = NULL, $name = NULL, $weight = NULL) {
        // Generate a random, lowercase machine name if none was passed.
        if (!isset($rid)) {
            $rid = $this->randomMachineName(8);
        }
        // Generate a random label.
        if (!isset($name)) {
            // In the role UI role names are trimmed and random string can start or
            // end with a space.
            $name = trim($this->randomString(8));
        }
        // Check the all the permissions strings are valid.
        if (!$this->checkPermissions($permissions)) {
            return FALSE;
        }
        // Create new role.
        $role = Role::create([
            'id' => $rid,
            'label' => $name,
        ]);
        if (isset($weight)) {
            $role->set('weight', $weight);
        }
        $result = $role->save();
        $this->assertSame(SAVED_NEW, $result, "Created role ID {$role->id()} with name {$role->label()}.");
        if ($result === SAVED_NEW) {
            // Grant the specified permissions to the role, if any.
            if (!empty($permissions)) {
                $this->grantPermissions($role, $permissions);
                $assigned_permissions = Role::load($role->id())
                    ->getPermissions();
                $missing_permissions = array_diff($permissions, $assigned_permissions);
                $this->assertEmpty($missing_permissions);
            }
            return $role->id();
        }
        else {
            return FALSE;
        }
    }
    
    /**
     * Checks whether a given list of permission names is valid.
     *
     * @param array $permissions
     *   The permission names to check.
     *
     * @return bool
     *   TRUE if the permissions are valid, FALSE otherwise.
     */
    protected function checkPermissions(array $permissions) {
        $available = array_keys(\Drupal::service('user.permissions')->getPermissions());
        $valid = TRUE;
        foreach ($permissions as $permission) {
            if (!in_array($permission, $available)) {
                $this->fail("Invalid permission {$permission}.");
                $valid = FALSE;
            }
        }
        return $valid;
    }
    
    /**
     * Grant permissions to a user role.
     *
     * @param \Drupal\user\RoleInterface $role
     *   The user role entity to alter.
     * @param array $permissions
     *   (optional) A list of permission names to grant.
     */
    protected function grantPermissions(RoleInterface $role, array $permissions) {
        foreach ($permissions as $permission) {
            $role->grantPermission($permission);
        }
        $role->trustData()
            ->save();
    }

}