Download the PHP package adamnicholson/judge without Composer
On this page you can find all versions of the php package adamnicholson/judge. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package judge
Judge
Authorization package for PHP.
Getting Started
Roles & Identities
"Roles" are things that users of your application can do. These are represented simply as text strings, and are usually things like "EDIT_ORDERS", "VIEW_LOGS", etc.
"Identities" represent the users of your application. Like roles, they are represented as a string. An identity could be some account specific key like an email address or user ID, or it could be something completely different like "console" or "API", or even "anonymous".
Keeping this mental separation between accounts and identities is key - Judge doesn't have any knowledge of, or care about, accounts or users.
To get started with some basic role-based auth, there is no setup required. Just instantiate Judge
, and allow
an an identity access to a role:
Simple enough? Good, now let's go a little deeper.
Role Contexts
Simple role-based permissions suit a lot of use cases, but often you hit their limits quickly when an application starts to grow. Say you have a role for "EDIT_ORDERS" which applies to all orders, but you need a single identity to have access to only edit 1 specific order. How would you do this?
In Judge, the way you would achieve this is by using role "contexts". A role context is a third parameter you can pass to allow()
, deny()
and check()
to add more specificity to your rule. In practice, a context is usually used for unique identifiers such as an order ID:
The benefit of role contexts is due to their ability to inherit rules. If an rule has not been explicity granted/revoked for the exact role+context combination, then Judge will fallback to check if the identity has been granted/revoked for that role without the context:
Role Inheritence
Roles & contexts together can solve many auth requirements, but larger systems may need more complex inheritance rules. Here is where we introduce role "parents".
Configuring a role parent looks like this:
If you call check()
but the identity has not been explicitly granted or revoked access to the role, but that role has a defined parent, then we fallback to check if a rule exists for the parent:
You can have as many levels in your role parent hierarchy as you like:
Identity Inheritence
Identity inheritence works just like role inheritence:
Putting it all together
Role contexts, role parents, and identity parents all stack, working together to give a truly robust authorisation system.
In order of precidence:
- Exact match of the identity-role-context combination passed
- Parent identities with the same role & context
- The identity + role passed without any context
- Parent identities with the same role without any context
- Parent roles with the original identity
- Parent roles with parent identities
Logic Flow
The Data Structure
Roles:
Role | ParentRole |
---|---|
ORDERS_EDIT | ORDERS_VIEW |
ORDERS_VIEW | ORDERS |
ORDERS | null |
Identities:
Identity | ParentIdentity |
---|---|
adam | customer_service |
paul | customer_service |
customer_service | null |
Rules:
Identity | Role | Context | State |
---|---|---|---|
adam | ORDERS_EDIT | 5 | GRANTED |
customer_service | ORDERS | null |
GRANTED |
paul | ORDERS_VIEW | 5 | REVOKED |
Persistence
The main problem with all of the examples so far is that roles & identities are not persisted across requests - meaning you'd need to reconfigure Judge to understand your identity/role hierarchies, and allow/deny all the relevant permissions, on every request.
These rules/roles/identities can be persisted between requests by using a Judge\Repository\Repository
, which can be passed to Judge::__construct()
as the first argument.
Judge ships with a number of Judge\Repository\Repository
implementations to use out of the box:
PDORepository
: Store data to a PDO compatible DB, like MySQL, SQLite, PostgreSQLFlatbaseRepository
: Store to a flat file databaseArrayRepository
: Store data in an array for the duration of this request
If you do not pass a
Repository
to Judge's constructor, thenArrayRepository
will be used by default.
PDORepository
Store data to a PDO compatible DB, like MySQL, SQLite, PostgreSQL
You may wish to use the PDORepository
in conjunction with the LazyRepositoryWrapper
, so that you do not have to instantiate a PDO
connection until it is actually requested.
ArrayRepository
Store data in an in-memory array for the duration of this process.
FlatbaseRepository
Store to a flat file database.