[BC break] Added the support of multiple users

[ezimuel]

This PR adds the support of multiple users, as suggested by #1. I updated the UserInterface changing the getUserRole() in getUserRoles(). Moreover, I added the following method to UserRepositoryInterface:

/**
 * Get the user roles if present
 *
 * @param string $username
 * @return array|null
 */
 public function getRolesFromUser(string $username): ?array;

This new function returns the roles of a user specified by $username. If the user has only one role, the result will be an array of one element. If the user does not have a role, the result will be null.
See the UserRepository\Htpasswd and UserRepository\PdoDatabase implementations.

[MidnightDesign]

Why not @return string[]|null?

[ezimuel]

Sure, thanks!

[MidnightDesign]

Why should this return null instead of an empty array?

[ezimuel]

A null value indicates that the roles are not defined. An empty array can indicate that the roles are used but the user does not have a role.

[MidnightDesign]

Do you think this could make a difference for a consumer of the interface?

[ezimuel]

@MidnightDesign not a big difference for the API but it matters from a semantic point of view, and we are also using a new feature of PHP 7.1.

[weierophinney]

I tend to agree with @MidnightDesign here. If the value type varies, you then need to add conditionals to your consumer:

$roles = $user->getUserRoles();
if (null === $roles) {
    // process differently
} else {
    foreach ($roles as $role) {
        // ...
    }
}

// or:
$roles = $user->getUserRoles() ?: [];
foreach ($roles as $role) {
    // ...
}

While the latter is succinct, it requires having the extra knowledge that a null value is possible, and an extra operation to ensure we have a list of roles once called. Compare this to always expecting an array:

foreach ($user->getUserRoles() as $role) {
     // ...
}

The above has the benefit of not requiring an intermediary variable prior to iteration. Additionally, if an empty array is returned, no iteration happens at all.

This was a design decision we approached with PSR-7 as well. I'd originally advocated for null returns for empty lists, but a number of folks showed me that consistency of return type has a ton of value.

[weierophinney]

@ezimuel I've rebased your branch and pushed the changes; unfortunately, I did it after a local merge, so there's a new merge commit.

I've also noted that I agree with changing the return value of getUserRoles() to simply array, and noting in the annotations @return string[].

[ezimuel]

@weierophinney ok for using a simple empty array as response, even if from a semantic point of view is a different output type.