adachsoft / reference-contracts
Immutable PHP value objects for principal and subject references shared across packages.
Requires
- php: ^8.3
Requires (Dev)
- adachsoft/php-code-style: ^0.7
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.19
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A small PHP library that provides immutable, validated references to principals (who acts) and subjects (what an object is about). Use the same reference format across packages without coupling those packages to one another's domain models.
Features
- Immutable
PrincipalReferenceandSubjectReferencevalue objects. - Parsing and serialization using the
type:idformat. - Open reference types, including dotted names such as
homeiot.device. PrincipalReferenceCollectionfor ordered, unique principal references.- Validation of type names and identifiers with a dedicated
InvalidReferenceException.
Requirements
- PHP ^8.3
Installation
composer require adachsoft/reference-contracts
Usage
use AdachSoft\ReferenceContracts\PrincipalReference;
use AdachSoft\ReferenceContracts\SubjectReference;
$owner = PrincipalReference::fromString('account:42');
$task = new SubjectReference('task', 'task1296');
echo $owner; // account:42
echo $task->toString(); // task:task1296
See the examples for collection and validation examples.
Validation rules
A type must contain lowercase ASCII letters, digits, and underscores, with optional dot-separated segments. An identifier must be non-empty, contain no whitespace, and be at most 255 Unicode characters. Colons are allowed in identifiers; parsing splits a serialized reference at its first colon.