freyr / identity
A PHP library for Identity concept.
Requires
- php: ^8.2
- symfony/polyfill-php84: ^1.31
- symfony/uid: ^6.4 || ^7.2 || ^8.0
Requires (Dev)
- ergebnis/composer-normalize: ^2.45
- infection/infection: ^0.32.6 || ^0.35.10
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.1
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-strict-rules: ^2.0
- phpstan/phpstan-symfony: ^2.0
- phpunit/phpunit: ^11.0 || ^12.0 || ^13.0
- rector/rector: ^2.8
- symplify/easy-coding-standard: ^13.3.17
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-15 21:21:29 UTC
README
Monotonic identity objects for PHP domain models, readable as a ULID and as a UUID v7. Provides an immutable Id value object and an IdCollection for working with sets of identifiers.
Installation
composer require freyr/identity
Requires PHP 8.2 or later. CI tests PHP 8.2, 8.3, 8.4 and 8.5.
Usage
Id
Create, convert and compare identifiers.
use Freyr\Identity\Id; $id = Id::new(); $id = Id::fromString('01ARYZ6S41TSV4RRFFQ69G5FAV'); // ULID string $id = Id::fromString('01563df3-6481-d676-4c61-efb99302bd5b'); // UUID string $id = Id::fromBinary($bytes); (string) $id; // ULID string (26 chars, Crockford Base32) $id->toUuid(); // UUID string (36 chars, RFC 4122) $id->toBinary(); // 16-byte binary $id->sameAs($other); // same 128 bits; the class is not compared $id->equalTo($other); // same 128 bits and same class
Create an Id with new(), fromString() or fromBinary(). The constructor is private.
ULID and UUID v7
An Id holds 128 bits. The ULID string, the UUID string and the binary form are three views of the same bits, and sameAs() compares the bits: an Id from a ULID string is the same as an Id from the UUID string of that ULID.
Id::new() creates the bits in the UUID v7 layout. The result is a valid ULID and a valid UUID v7 at the same time, with the same timestamp and the same monotonic order in the two forms. Store it as BINARY(16) with toBinary(), or in a uuid column with toUuid().
fromString() detects the format and accepts a ULID string or a UUID string of any version. An identifier that was not created in the UUID v7 layout — an Id from version 1 of this library, or a plain ULID from another source — still has a toUuid() form that a database accepts, but that form is not a valid UUID v7.
Extend for typed identifiers.
class UserId extends Id {} class OrderId extends Id {} $userId = UserId::new(); $orderId = OrderId::fromString((string) $userId); $userId->sameAs($orderId); // true $userId->equalTo($orderId); // false
A subclass cannot define a constructor or read the internal ULID.
IdCollection
Immutable collection with standard operations.
use Freyr\Identity\IdCollection; $collection = IdCollection::fromArray([$id1, $id2]); $collection = IdCollection::empty(); $collection->add($id); $collection->remove($id); $collection->contains($id); $collection->merge($other); $collection->intersect($other); $collection->filter(fn (Id $id) => /* ... */); $collection->map(fn (Id $id) => /* ... */); $collection->first(); $collection->last(); $collection->count(); $collection->isEmpty(); $collection->toArray(); $collection->toStringArray(); $collection->toBinaryArray();
All mutating methods return new instances.
Upgrade from 1.x to 2.0
Version 2.0 has two breaking changes in Id:
- The constructor is
final private. Replacenew UserId($ulid)in a subclass or a factory withUserId::fromString()orUserId::fromBinary(), and remove each constructor that a subclass defines. - The internal ULID is
private readonly. A subclass cannot read$this->id; use(string) $id,toBinary()ortoUuid().
Version 2.0 also adds equalTo() and toUuid(), creates new identifiers in the UUID v7 layout, and allows symfony/uid 8. Stored identifiers stay valid: the ULID string and the 16 bytes of an identifier do not change.
Doctrine
examples/DoctrineIdType.php is a Doctrine DBAL 4 type that stores an Id as 16 bytes. Copy it into your project; the library has no dependency on Doctrine.
Development
The tools run in Docker.
make install # install the dependencies make test # PHPUnit make qa # all CI checks
make qa runs the tests, the line coverage, mutation testing (Infection), PHPStan, ECS, Rector and the Composer checks. CI enforces:
- 100% line coverage;
- a mutation score (MSI) of 98% or more — a test must fail when the code changes, so assert exact values;
- PHPStan at max level on
src/andtests/; - tests on PHP 8.2, 8.3, 8.4 and 8.5, and on PHP 8.2 with the lowest dependency versions.
Contributing
All changes go through a pull request with a Conventional Commits title. The PR is squash-merged, so its title becomes the commit on main and sets the next version:
| PR title | Release |
|---|---|
feat: … |
minor |
fix: …, perf: …, revert: … |
patch |
feat!: …, or BREAKING CHANGE: in the PR body |
major — only with the explicit approval of the maintainer |
docs:, test:, ci:, build:, refactor:, chore:, style: |
none |
A breaking change always goes out as a major release, never as a minor or a patch release. A change is breaking when code that uses the public or protected API of version N can fail with version N+1: a removed or renamed method, a narrower visibility, a changed signature, or a different result for the same input.
A change only to tests, docs or Markdown files makes no release. After the merge, the release job pushes the tag vX.Y.Z and creates the GitHub release; Packagist picks up the tag. Do not create tags by hand. The GitHub releases are the changelog.
Required checks: pr-title, version and ci-gate.
Licence
MIT