Search by

adachsoft / reference-contracts

Arkadiusz Adach

Immutable PHP value objects for principal and subject references shared across packages.

Package info

gitlab.com/a.adach/reference-contracts

Issues

pkg:composer/adachsoft/reference-contracts

Statistics

Installs: 36

Dependents: 1

Suggesters: 0

Stars: 0

v0.1.0 2026-11-22 08:44 UTC

This package is auto-updated.

Last update: 2026-11-22 07:44:26 UTC


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 PrincipalReference and SubjectReference value objects.
  • Parsing and serialization using the type:id format.
  • Open reference types, including dotted names such as homeiot.device.
  • PrincipalReferenceCollection for 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.