Search by

adachsoft / principal-contracts

Arkadiusz Adach

Resolve principals (accounts, groups and other pluggable types) to leaf principals and check membership, built on adachsoft/reference-contracts.

Package info

gitlab.com/a.adach/principal-contracts

Issues

pkg:composer/adachsoft/principal-contracts

Statistics

Installs: 5

Dependents: 0

Suggesters: 0

Stars: 0

v0.2.0 2026-11-22 17:58 UTC

This package is auto-updated.

Last update: 2026-11-22 16:58:26 UTC


README

adachsoft/principal-contracts provides the contracts and resolver for expanding open-ended principal references to concrete leaf principals and checking membership. It does not depend on authentication or access-control implementations.

Requirements

Installation

composer require adachsoft/principal-contracts

The only runtime dependency is adachsoft/reference-contracts, which provides immutable PrincipalReference and PrincipalReferenceCollection values.

Usage

What the resolver answers

A principal reference consists of an open type and an identifier, for example account:42, group:7, or role:admin. The library answers two domain questions:

  1. Which concrete leaf principals does a principal resolve to? For example, a group may resolve to its member accounts.
  2. Does a leaf principal belong to another principal, directly or through nested membership?

The core library does not define what groups, roles, or other principal types mean. Implementations plug in their own PrincipalTypeExpanderInterface for each type that needs expansion.

Composition

Configure a leaf expander for types such as accounts, and add expanders from optional domain packages for types that have members:

use AdachSoft\PrincipalContracts\CompositePrincipalResolver;
use AdachSoft\PrincipalContracts\LeafPrincipalExpander;
use AdachSoft\ReferenceContracts\PrincipalReference;
use AdachSoft\ReferenceContracts\PrincipalReferenceCollection;

$resolver = new CompositePrincipalResolver([
    new LeafPrincipalExpander(['account']),
    new GroupPrincipalExpander($groupRepository), // Provided by an optional group integration package.
]);

$accounts = $resolver->resolveAll(
    PrincipalReferenceCollection::fromStrings(['account:42', 'group:7']),
);

$isMember = $resolver->isMemberOf(
    PrincipalReference::fromString('account:43'),
    PrincipalReference::fromString('group:7'),
);

The first registered expander whose supports() method accepts a principal type handles that principal. Expansion is depth-first and preserves the order of first occurrence. Duplicate leaf principals are removed. Cycles are skipped, and the maximum nesting depth defaults to 10 non-leaf principals; pass a different positive value as the second constructor argument to CompositePrincipalResolver to change it.

A principal that is already a leaf resolves to itself. Membership checks also return true when the member and principal references are equal.

Adding a principal type

Implement PrincipalTypeExpanderInterface in the package that owns the type. supports() identifies the type, isLeaf() indicates whether it requires further expansion, and expand() returns its immediate members as a PrincipalReferenceCollection. For example, a group integration can return account and nested group references; the composite resolver will recursively resolve them.

No delivery-address, notification, authorization, or permission adapter is included. Those behaviors belong to their respective domain packages.

Exceptions

UnsupportedPrincipalTypeException is thrown when no registered expander handles a type encountered during resolution. Other failures are reported as PrincipalResolutionException; unexpected exceptions thrown by an expander are wrapped as its previous exception. A maximum-depth violation also raises PrincipalResolutionException. LeafPrincipalExpander and CompositePrincipalResolver reject invalid constructor arguments with InvalidArgumentException.

Reverse membership

Use PrincipalMembershipResolverInterface when domain code needs to find every principal that contains an account, directly or through nested groups. This supports queries such as findByPrincipals($memberships->membershipsOf($actor)) for resources shared with an actor. Each principal type that can contain others provides a PrincipalTypeMembershipProviderInterface; with no providers, the resolver returns only the original principal.

Providers return direct containers. CompositeMembershipResolver traverses them depth-first in provider registration order, keeps the first occurrence of each principal, skips cycles, and limits nesting to 10 levels by default.

use AdachSoft\PrincipalContracts\CompositeMembershipResolver;
use AdachSoft\ReferenceContracts\PrincipalReference;

$memberships = new CompositeMembershipResolver([
    new GroupMembershipProvider($groupRepository), // provided by adachsoft/principal-group
]);

$memberships->membershipsOf(PrincipalReference::fromString('account:42'));
// → [account:42, group:7, group:1]