Download the PHP package managur/rick-role without Composer

Rick-Role

The Role Based Access Control library that's never gonna give you up, never gonna let you down, never run around and desert you

What is Rick-Role?

Rick-Role is a powerful, flexible Role Based Access Control (RBAC) library for PHP 8.4+ that provides a robust permission system through a voter-based architecture. It allows you to define complex permission rules whilst maintaining simplicity and performance.

Core Concepts

RBAC Fundamentals: In Rick-Role, roles are containers that hold permissions. User IDs are assigned roles, and through those roles, users gain access to specific permissions. Rick-Role does not store or manage user profile data—only the mapping of user IDs to roles and the permissions those roles grant. All user information (name, email, etc.) is managed by your application's own user system or IdP.

Voter Architecture: While simple permission checks are supported, Rick-Role offers you the opportunity to utilise a stack of "voters" that each make decisions about permissions. Each voter can allow, deny, or abstain from a decision. The final result is determined by a configurable strategy.

Voting Strategies: Rick-Role supports two strategies for combining voter decisions out of the box:

• DenyWinsStrategy (default): Deny decisions override allow decisions
• AllowWinsStrategy: Allow decisions override deny decisions

Hierarchical Roles: Rick-Role supports hierarchical roles where one role can extend another role to inherit its permissions. This allows you to create specialised roles that build upon existing ones. When evaluating access, permissions from direct and inherited roles are pooled, and the configured strategy (DenyWins or AllowWins) determines the outcome when there are conflicts.

Attribute Based Access Control (ABAC)

Whilst Rick-Role is a Role Based Access Control system at its core, the voter system allows decisions to be made based on other attributes, such as object state. This is implemented via your own voters which vote based not on whether a user has a given permission, but based on the subject passed in through the $onThis parameter.

Installation & Requirements

Requirements

• PHP 8.4+
• Composer

Installation

Install Rick-Role via Composer:

Quick Start

Here's a minimal example to get you started using a SQLite database:

Note: This example uses SQLite for simplicity. For production use with MySQL, PostgreSQL, or any other Doctrine-supported DB, see the Configuration section for database setup details.

This final example reads as "if Rick allows userId permission [on this] post". If $permission is a literal, or named accordingly, this can be as clear as possible for anyone reviewing the code later.

Core Concepts in Detail

RBAC Fundamentals

Rick-Role follows a standard RBAC model:

1. Permissions are individual actions (e.g., 'create post', 'delete user')
2. Roles are containers that hold multiple permissions
3. User IDs are assigned one or more roles (Rick-Role does not store user profiles—just the userId-to-role mapping)
4. Access is granted through the role-permission relationship

Note: Rick-Role does not manage user accounts or profiles. It only cares about the user ID (string or int) and which roles are assigned to that ID. All user information is managed by your application or IdP.

Voter Architecture

Voters are the decision-makers in Rick-Role. Each voter can:

• Allow: Grant permission for the action
• Deny: Block permission for the action
• Abstain: Decline to make a decision

Multiple voters form a "stack" that processes permission requests in order. The final decision depends on a combination of the configured stack and your chosen strategy.

Abstention should be considered the default response unless an absolute allow or deny is necessary. This allows later voters in the stack to make the appropriate decision instead.

It is recommended to run the DoctrineDefaultVoter (or equivalent) at the top—especially when using the default DenyWinsStrategy, as this ensures that the user actually has the underlying permission, regardless of other checks performed by other voters.

Voting Strategies

DenyWinsStrategy (Default)

With the default strategy, deny decisions override allow decisions, meaning that later voters will not vote:

AllowWinsStrategy

With the allow-wins strategy, allow decisions override deny decisions and will also immediately return:

Reason Objects

Rick-Role provides detailed information about permission decisions through reason objects:

Note: The $reasons parameter contains a chain of Reason objects, where each object represents a decision from a voter in the stack. The previous property links to the previous voter's decision, creating a complete audit trail of the permission check.

Configuration

Basic Setup

Database Setup

Rick-Role uses Doctrine ORM for database operations. Here are some setup examples:

SQLite (Better for development/testing)

MySQL (Better for production)

PostgreSQL (Better for production)

Then run migrations:

Migration System

Rick-Role uses Doctrine Migrations for database schema management. The migration system includes:

• Database-agnostic migrations: Work across all supported database platforms
• Proper naming convention: VersionYYYYMMDDHHMMSS_Description.php
• Rollback support: Each migration includes proper down() methods
• Configuration files: migrations.php and migrations-db.php for setup

Note: If you are already using Doctrine migrations you may wish to merge our migrations into your own. If you do not do this, you may need to run additional migrations in future if you update your Rick-Role installation.

Available Migration Commands:

From within the Rick-Role directory:

Usage Examples

Basic Permission Checks

Named Arguments

The arguments in the allows() and disallows() methods are named in such a way that we believe they make your code even more readable, and we recommend their use, though they are of course entirely optional. Compare these examples:

Don't forget that the optional reasons out-parameter is also available on the because named argument.

Hierarchical Roles

Rick-Role supports hierarchical roles where one role can extend another role to inherit its permissions.

Here is an example using the Rick-Role CLI:

For more commands and options, see the CLI guide: CLI.md.

Hierarchical Role Rules:

• Multiple inheritance is supported (a role can extend multiple roles)
• The current voting strategy applies when resolving allow/deny conflicts

Custom Voters

Create custom voters for specialised permission logic:

Voters can optionally check the provided $permission and $subject to see whether they are designed to actually perform the requested check. If not, they should return a VoteResult::abstain() to delegate to a different voter within the configured stack.

Complex Permission Scenarios

It's discouraged to check multiple permissions for a single operation, but we understand that it is sometimes necessary. If that is the case, simply query Rick-Role for all relevant permissions and check that both are allowed:

You may also wish to perform an action based on the reason why the user was allowed (or denied), which you can do by interrogating the out-parameter $reasons object in this example:

API Reference

Configuration Methods

addVoter(VoterInterface $voter): self

Add a single voter to the stack in order for it to assist Rick in making decisions.

setVoters(array $voters): self

Empty the voter stack and replace it with this array of voters.

setStrategy(StrategyInterface $strategy): self

Determine whether Rick should consider an allow to be more significant than a deny, or vice versa.

setLogger(LoggerInterface $logger): self

Configure a PSR-3 logger for audit logging. When a logger is provided, Rick-Role will log all permission checks with detailed context.

Log Levels Used:

• INFO: Final permission decisions (allow/deny)
• DEBUG: Individual voter decisions and reasoning chains
• WARNING: Denied permissions

Rick Methods

allows(string|int $userId, string|\Stringable $to, mixed $onThis = null, ?Reason &$because = null): bool

Checks if a user has permission to perform an action.

• $userId: User identifier (string or integer)
• $to: Permission string (e.g., 'create post', 'delete user')
• $onThis: Optional subject context
• $because: Optional reason object passed by reference for detailed decision info

disallows(string|int $userId, string|\Stringable $to, mixed $onThis = null, ?Reason &$because = null): bool

Checks if a user does not have permission to perform an action.

doesNotAllow(string|int $userId, string|\Stringable $to, mixed $onThis = null, ?Reason &$because = null): bool

Alias for disallows() - alternative reading preference.

Reason Object

The reason object provides detailed information about permission decisions:

Note: The $reasons parameter contains a chain of Reason objects, where each object represents a decision from a voter in the stack. The previous property links to the previous voter's decision, creating a complete audit trail of the permission check.

Permission Parameter Type

The $permission parameter in all permission-checking methods (e.g., Rick::allows(), Rick::disallows(), and all VoterInterface::vote() implementations) accepts either a string or any object implementing the Stringable interface.

Example: Using a Stringable Permission

This allows for more expressive permission objects, such as enums or value objects, as long as they implement __toString().

Audit Logging

Rick-Role provides comprehensive audit logging through PSR-3 compatible loggers. When a logger is configured, Rick-Role will log all permission checks with detailed context:

Log Levels:

• INFO: Final permission decisions (allow/deny) - useful for production monitoring
• DEBUG: Individual voter decisions and reasoning chains - useful for debugging
• WARNING: Denied permissions - useful for security monitoring

Example with Monolog:

Log Output Example:

Log Context Fields:

• DEBUG (per-voter "Voter decision"):

  • user_id
  • permission
  • voter
  • decision
  • message

• INFO (final "Permission check completed"):

  • user_id
  • permission
  • subject
  • decision
  • allowed
  • duration_ms
  • voter_count
  • strategy
  • reason
• Optional (DEBUG aggregate):
  • voter_decisions: Array of individual voter decisions

CLI Usage

Rick-Role includes a command-line interface for managing roles, permissions, and user assignments.

For detailed CLI usage instructions, please see CLI.md.

Development

For information about contributing to Rick-Role, setting up a development environment, and running tests, please see CONTRIBUTING.md.

Security

If you discover any security-related issues, please see SECURITY.md for information on how to report them.

License

Rick-Role is open-sourced software licensed under the MIT license.

Changelog

Please see the GitHub releases for information on what has changed recently.

Rick-Role: Because your application's security should never give you up, never let you down, never run around and desert you.