unstoppablecarl/arbiter

Manage Laravel User abilities that target Users

Arbiter

Manage Laravel User abilities that target Users., _(*1)

![Latest Version][badge-release] ![Build Status][badge-build] [][coverage] ![Total Downloads][badge-downloads], _(*2)

About

Determining a way to authorize what actions can be performed by one User on another may seem like a simple problem at first. Most Role based permission modules are designed to allow multiple roles per user. This is an extremely powerful and flexible design pattern but creates a hard to define authorization case: When User-A can update users with Role-1, and User-B has Role-1 and Role-2, how should your application determine if User-A update User-B?, _(*3)

Arbiter provides a solution to this problem without getting in the way of an existing or separate multi-role based authorization system., _(*4)

Requirements

• PHP >= 5.5.9
• Laravel >= 5.2

Installation

The preferred method of installation is via Packagist and Composer. Run the following command to install the package and add it as a requirement to your project's composer.json:, _(*5)

composer require unstoppablecarl/arbiter

Overview

Each User has exactly one Primary Role. Primary Roles are used to determine what actions a user can perform on other users and vice-versa. Each Primary Role is identified with a unique name string., _(*6)

The UserWithPrimaryRole interface is implemented on the User model., _(*7)

<?php
interface UserWithPrimaryRole {

    /*
     * Get the Primary Role of this user.
     * @return string 
     */
    public function getPrimaryRoleName();
}

The developer implements the interface with a strategy for determining what the Primary Role of a user is., _(*8)

Primary Role Implementation Strategies

• Using an existing multi-role based system:
  • Define some roles as "Primary". Each User has exactly one Primary Role.
  • Define a numeric priority to each Role. The Primary Role of a User is the Role with the highest priority assigned to them.
• Users have exactly one Role which is used as the Primary Role. This is often a good starting point projects where it is unclear how complex the roles/permissions requirements will become.

Basic Usage

User

Implement the UserWithPrimaryRole Interface on your User model., _(*9)

See UnstoppableCarl\Arbiter\Contracts\UserWithPrimaryRole, _(*10)

<?php

namespace App;

use UnstoppableCarl\Arbiter\Contracts\UserWithPrimaryRole;

class User implements UserWithPrimaryRole
{
    public function getPrimaryRoleName()
    {
        // @TODO implement Primary Role strategy

        // simple example
        // not recommended
        return $this->primary_role ?: 'default_primary_role';
    }
} 

User Policy

Create App\Policies\UserPolicy and set it as the policy for the User model in App\Providers\AuthServiceProvider, _(*11)

See UserPolicy, _(*12)

<?php

namespace App\Policies;

use UnstoppableCarl\Arbiter\Policies\UserPolicy as ArbiterUserPolicy;

class UserPolicy extends ArbiterUserPolicy
{

}

User Authority

Create and bind an implementation of the UserAuthorityContract in your AuthServiceProvider or continue with the Config Based User Authority below., _(*13)

Config Based Implementation

Arbiter includes a simple config based UserAuthority implementation to quickly get your project up and running., _(*14)

ArbiterServiceProvider

Add the Service Provider to config/app.php, _(*15)

UnstoppableCarl\Arbiter\Providers\ArbiterServiceProvider::class,, _(*16)

Configure

Publish the config file., _(*17)

php artisan vendor:publish --provider=UnstoppableCarl\Arbiter\Providers\ArbiterServiceProvider, _(*18)

Primary Role Abilities can be configured in config/arbiter.php., _(*19)

Customizing The User Policy

The UserPolicy functionality is organized into seperate traits to allow use of only the functionality you want., _(*20)

• See
  • Concerns
  • UserPolicy

UserPolicy Trait: HasUserAuthority

HasUserAuthority, _(*21)

Adds a reference to the UserAuthority instance., _(*22)

• Required for HasAbilities and HasGetters traits.
• Gets the primary role of ability targets that implement the UserWithPrimaryRole interface via a toPrimaryRole method.

Trait: HasAbilities

HasAbilities, _(*23)

Adds the typical abilities of a UserPolicy matching them to the methods and abilities of the UserAuthority., _(*24)

• Requires HasUserAuthority trait.
• Methods
  • create
  • update
  • delete
  • view
  • changePrimaryRoleFrom
  • changePrimaryRoleTo
  • changePrimaryRole

Trait: HasGetters

HasGetters, _(*25)

Adds getters to allow retrieval of all primary roles a user can perform given abilities on., _(*26)

• Requires HasUserAuthority trait.
• Methods
  • getViewablePrimaryRoles
  • getCreatablePrimaryRoles
  • getChangeableFromPrimaryRoles
  • getChangeableToPrimaryRoles
  • getDeletablePrimaryRoles
  • getPrimaryRoles

Trait: HasTargetSelfOverrides

HasTargetSelfOverrides, _(*27)

Allows overriding the returned value of a UserPolicy ability check, when the source and target of the check are the same User. The ability check is overriden by using the before method behavior of Laravel Policies., _(*28)

• The $targetSelfOverrides property must be set to an implementation of the TargetSelfOverridesContract. In the included UserPolicy it is set via the constructor.
• TargetSelfOverrides is a minimal implementation included and used by default in the ArbiterServiceProvider.

Adding User Authority Abilities

The following shows how to add an ability to the UserPolicy that checks a custom ability set in the UserAuthority., _(*29)

<?php

namespace App\Policies;

use UnstoppableCarl\Arbiter\Contracts\UserWithPrimaryRole;
use UnstoppableCarl\Arbiter\Policies\UserPolicy as ArbiterUserPolicy;

class UserPolicy extends ArbiterUserPolicy
{
    /**
     * Can ban users with $target Primary Role
     * @param UserWithPrimaryRole $source
     * @param UserWithPrimaryRole|null $target
     * @return
     */
    public function ban(UserWithPrimaryRole $source, $target = null)
    {
        $source  = $this->toPrimaryRole($source);
        $target  = $this->toPrimaryRole($target);
        $ability = 'ban';
        return $this->userAuthority()->canOrAny($source, $ability, $target);
    }
}

Running Tests

Run Unit Tests, _(*30)

$ composer phpunit

Run Codesniffer (psr-2), _(*31)

$ composer phpcs

Run both, _(*32)

$ composer test

Contributing

Contributions and Pull Requests welcome!, _(*33)

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us., _(*34)

Authors

• Carl Olsen - Initial work - Unstoppable Carl

See also the list of contributors who participated in this project., _(*35)

License

This project is licensed under the MIT License - see the LICENSE.md file for details, _(*36)