Skip to content

CkUuid

Job: read a UUID from any way people write it, and hand it back in the one spelling you can store, compare and derive from.

A UUID (universally unique identifier) is a 128-bit identifier written as 32 hex digits, like 08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f. The trouble is that systems spell the same identifier many ways: with hyphens, without them, wrapped in braces or parentheses, prefixed with urn:uuid:, in either casing. CkUuid reads all of those — plus a UUID object straight off another call — and writes back the lowercase hyphenated form, so two spellings of one identifier always match. One rule matters most here: there is no substitute fallback. An identifier names one specific thing, and an invented one is worse than none — it corrupts deduplication and audit trails. A value that cannot be used answers '' (string methods) or the nil UUID (the all-zeros one, as an object), and the all-zeros UUID itself counts as missing by default, because that is what databases and serializers emit when nobody set a value.

The object the typed methods hand back is a UuidInterface — the library's own copy of ramsey/uuid, SafeCoder\CommonKit\Packages\Ramsey\Uuid\UuidInterface. It is not the interface of a ramsey/uuid your application installs itself; the two never meet, in whatever versions. From there the identifier answers for itself: toString(), getBytes(), getFields(), equals(), compareTo().

Quick look

use SafeCoder\CommonKit\CkUuid;

CkUuid::Canonical('{08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F}');     // -> '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f'
CkUuid::ToUuid('junk');                                          // -> Uuid 00000000-0000-0000-0000-000000000000  (rejected: the nil UUID)
CkUuid::ToUuidOrNull('00000000-0000-0000-0000-000000000000');    // -> null  (all zeros = missing)
CkUuid::Version('08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f');         // -> 4
CkUuid::IsUuid('junk');                                          // -> false
CkUuid::SameUuid(
    a: '{08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F}',
    b: '08d3f9c65e4a4b8f9d2e7a1b3c5d7e9f'
);   // -> true
CkUuid::IsVersion(
    input: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f',
    versions: [4, 7]
);   // -> true
$id = CkUuid::NewV7();           // sorts by creation time
CkUuid::Explain('junk');         // -> 'not a UUID in a known shape'

Methods

Canonical

The one agreed spelling.

static function Canonical(
    mixed $input = null,
    bool $treatZerosAsMissing = true,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): string
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
treatZerosAsMissing bool true Counts the all-zeros UUID as missing rather than real. Pass false to read it as a real value.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering '', when the value cannot be used.

Returns

When Default With throwIfInvalid: true
The value is a UUID in any supported shape The canonical text: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f' The canonical text: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f'
Rejected: missing, oversized, not a UUID in a known shape, or — by default — all zeros Empty string Throws CkUuidException — carries Input, Expected and Reason

There is deliberately no substitute fallback — an invented identifier is worse than an empty one.

Reads a UUID from any supported shape and writes it lowercase, hyphenated, no braces — the form to store and compare.

use SafeCoder\CommonKit\CkUuid;

CkUuid::Canonical('{08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F}');         // -> '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f'
CkUuid::Canonical('08d3f9c65e4a4b8f9d2e7a1b3c5d7e9f');               // -> '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f'
CkUuid::Canonical('urn:uuid:08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f');  // -> '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f'
CkUuid::Canonical('00000000-0000-0000-0000-000000000000');           // -> ''  (zeros mean missing)
CkUuid::Canonical('not an id');                                      // -> ''  (rejected)

Format

One of the four everyday shapes.

static function Format(
    mixed $input = null,
    ?string $into = 'D',
    bool $treatZerosAsMissing = true,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): string
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
into ?string 'D' The shape to write: 'D' hyphenated, 'N' 32 bare digits, 'B' braced, 'P' parenthesized — always lowercase. Anything else is rejected.
treatZerosAsMissing bool true Counts the all-zeros UUID as missing rather than real. Pass false to read it as a real value.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering '', when the value or the shape cannot be used.

Returns

When Default With throwIfInvalid: true
The value is a UUID and into is one of the four shapes The formatted text: '08d3f9c65e4a4b8f9d2e7a1b3c5d7e9f' with into: 'N' The formatted text: '08d3f9c65e4a4b8f9d2e7a1b3c5d7e9f' with into: 'N'
Rejected: a bad value, or a shape that is not D, N, B or P Empty string Throws CkUuidException — carries Input, Expected and Reason

The value itself is read the way Canonical reads one.

For systems that store one of the other spellings. The into parameter names the shape: 'D' hyphenated (the default), 'N' 32 bare digits, 'B' braced, 'P' parenthesized — always lowercase.

use SafeCoder\CommonKit\CkUuid;

CkUuid::Format(
    input: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f',
    into: 'D'
);   // -> '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f'

CkUuid::Format(
    input: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f',
    into: 'N'
);   // -> '08d3f9c65e4a4b8f9d2e7a1b3c5d7e9f'

CkUuid::Format(
    input: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f',
    into: 'B'
);   // -> '{08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f}'

CkUuid::Format(
    input: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f',
    into: 'P'
);   // -> '(08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f)'

The two typed readers, ToUuid and ToUuidOrNull, both take treatZerosAsMissing (default true). Switch it off only when the all-zeros value really means something in your data:

use SafeCoder\CommonKit\CkUuid;

CkUuid::ToUuidOrNull(
    input: '00000000-0000-0000-0000-000000000000',
    treatZerosAsMissing: false
);   // -> Uuid 00000000-0000-0000-0000-000000000000  (the nil UUID, read as a real value)

ToUuid

The typed reader.

static function ToUuid(
    mixed $input = null,
    bool $treatZerosAsMissing = true,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): UuidInterface
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
treatZerosAsMissing bool true Counts the all-zeros UUID as missing rather than real. Pass false to read it as a real value — and lose the unambiguous sentinel.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering the nil UUID, when the value cannot be used.

Returns

When Default With throwIfInvalid: true
The value is a UUID in any supported shape The UUID object for 08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f The UUID object for 08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f
Rejected: missing, oversized, not a UUID in a known shape, or — by default — all zeros The nil UUID Throws CkUuidException — carries Input, Expected and Reason

No fallback parameter, on purpose — rejection is always the nil UUID, never a made-up id.

ToUuid reads the same shapes but answers a UUID object — for database keys, array lookups and comparisons, and for a long chain of calls on the identifier itself.

use SafeCoder\CommonKit\CkUuid;

CkUuid::ToUuid('{08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F}');        // -> Uuid 08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f
CkUuid::ToUuid('junk');                                          // -> Uuid 00000000-0000-0000-0000-000000000000  (rejected: the nil UUID)

ToUuidOrNull

Null when there is nothing usable.

static function ToUuidOrNull(
    mixed $input = null,
    bool $treatZerosAsMissing = true
): ?UuidInterface
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
treatZerosAsMissing bool true Reads the all-zeros UUID as missing, so it comes back as null too. Pass false to hand it back as the nil UUID.

Returns

When You get
The value is a UUID in any supported shape The UUID object for 08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f
Missing, unreadable, or a sentinel: null, 'junk', an unsupported type, or — by default — the all-zeros UUID null — this method never throws

An honest nothing is never an error, and neither is anything else — null is the answer for whatever cannot be used.

Works like ToUuid but answers null instead when there is nothing usable: a missing value, one that cannot be read, or — by default — the all-zeros UUID. That way a nullable database column receives NULL rather than a zero identifier, and === null replaces comparing against the sentinel.

use SafeCoder\CommonKit\CkUuid;

CkUuid::ToUuidOrNull('junk');                                    // -> null
CkUuid::ToUuidOrNull(null);                                      // -> null  (nothing there — an honest answer)
CkUuid::ToUuidOrNull('00000000-0000-0000-0000-000000000000');    // -> null  (zeros mean missing)

FromName

The same UUID from the same name, every time.

static function FromName(
    mixed $name = null,
    mixed $space = null,
    int $version = 5,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): UuidInterface
Parameter Type Default What it does
name mixed null The name to derive from: text, or a whole number written invariantly. At most CkSettings::MaxUuidNameLength (1,024) characters — over that is rejected, never truncated.
space mixed null The name-space UUID, in any shape Canonical reads — one of the RFC spaces (CkUuid::NamespaceDns, CkUuid::NamespaceUrl…) or, better for your own ids, one minted once per id family.
version int 5 5 (SHA-1, recommended) or 3 (MD5, legacy interop only). Anything else is rejected.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering the nil UUID, when a value cannot be used.

Returns

When Default With throwIfInvalid: true
The name and name space are usable The derived UUID: 2ed6657d-e927-568b-95e1-2665a8aea6a2 for 'www.example.com' in NamespaceDns The derived UUID: 2ed6657d-e927-568b-95e1-2665a8aea6a2 for 'www.example.com' in NamespaceDns
Rejected: a missing or oversized name, a name space that cannot be read, or a version other than 5 and 3 The nil UUID Throws CkUuidException — carries Input, Expected and Reason

A bad ingredient never derives a wrong id — it is rejected instead.

Derives a name-based UUID from two ingredients: a name space (itself a UUID, marking which family of ids you are in) and a name. The derivation is deterministic — the same name space and name always give the same UUID, on every platform and in every language. That is the point: an identifier can be computed instead of stored. "Which event UUID belongs to claim 12345" needs no mapping table — derive it again and you get the same answer, which also makes retries and reruns safe, since the same occurrence always produces the same id.

The default is version 5, which hashes with SHA-1 (a hash is a fixed-size fingerprint computed from data); pass version: 3 for MD5, only when you must match a system that already derives with it. The class ships the RFC 9562 name spaces as constants — CkUuid::NamespaceDns, CkUuid::NamespaceUrl, CkUuid::NamespaceOid, CkUuid::NamespaceX500 — but for your own ids it is better to mint one fresh UUID per id family, once, and hard-code it.

use SafeCoder\CommonKit\CkUuid;

CkUuid::FromName(
    name: 'www.example.com',
    space: CkUuid::NamespaceDns
);   // -> Uuid 2ed6657d-e927-568b-95e1-2665a8aea6a2  (here, in Python, everywhere)

CkUuid::FromName(
    name: 'www.example.com',
    space: CkUuid::NamespaceDns,
    version: 3
);   // -> Uuid 5df41881-3aed-3515-88a7-2f4a814cf09e  (the MD5 variant)

The name is hashed exactly as given, byte for byte — no trimming, no case-folding — because a derived identifier must match what every other system derives from the same name. A whole number works as a name too (written invariantly), and a name over 1,024 characters is rejected rather than truncated, since truncating would change the id. Text that is not well-formed UTF-8 is refused rather than repaired, so two different broken names cannot derive one id.

Version

Which kind of UUID this is.

static function Version(
    mixed $input = null,
    int $fallback = 0,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): int
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
fallback int 0 What comes back when the value cannot be used — 0 by default, which no version is.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering the fallback, when the value cannot be used.

Returns

When Default With throwIfInvalid: true
The value is a UUID The version digit: 4 The version digit: 4
Rejected: missing, not a UUID in a known shape, or all zeros — always missing here The fallback (default 0) Throws CkUuidException — carries Input, Expected and Reason

The one method with a fallback parameter — it answers a plain int, not an identity.

Reads the UUID's version digit: 4 is random, 5 and 3 are name-based, 7 is time-ordered, 1 is the classic time-and-MAC kind. The digit is taken as written; whether it means anything is IsStandard's question.

use SafeCoder\CommonKit\CkUuid;

CkUuid::Version('08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f');   // -> 4  (random)

CkUuid::Version(CkUuid::FromName(
    name: 'www.example.com',
    space: CkUuid::NamespaceDns
));                                                        // -> 5  (name-based)

CkUuid::Version('junk');                                   // -> 0  (the default fallback)

IsUuid

Does it read as a UUID at all?

static function IsUuid(
    mixed $input = null,
    bool $treatZerosAsMissing = true,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): bool
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
treatZerosAsMissing bool true Counts the all-zeros UUID as missing rather than real.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering false, when the value is not a UUID.

Returns

When Default With throwIfInvalid: true
The value reads as a UUID under the readers' rules true true
Rejected: missing, not a UUID in a known shape, a wrong type, or all zeros with the default on false Throws CkUuidException — carries Input, Expected and Reason

The yes-or-no form of Canonical and ToUuid: the four text shapes, the urn:uuid: prefix, any casing, a UUID object. When the value is going to be stored, read it with ToUuidOrNull instead and check for null — same question, and you get the value back.

use SafeCoder\CommonKit\CkUuid;

CkUuid::IsUuid('{08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F}');   // -> true
CkUuid::IsUuid('00000000-0000-0000-0000-000000000000');     // -> false  (missing by default)
CkUuid::IsUuid('junk');                                     // -> false

IsNil

Is it the all-zeros UUID?

static function IsNil(
    mixed $input = null,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): bool
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering false, when the value is not a UUID.

Returns

When Default With throwIfInvalid: true
The value reads as a UUID and is 00000000-0000-0000-0000-000000000000 true true
Any other UUID false false
Rejected: not a UUID false Throws CkUuidException — carries Input, Expected and Reason

RFC 9562 calls it the nil UUID; it is what databases and serializers emit when nobody set a value, the 1900-01-01 of identifiers. The readers turn it into "missing" silently; this method says so out loud, for data-quality checks and for telling "nobody set it" from "not an id" — and for testing what a rejected read handed back. The same job CkDate::IsPlaceholder does for dates.

use SafeCoder\CommonKit\CkUuid;

CkUuid::IsNil('00000000-0000-0000-0000-000000000000');   // -> true
CkUuid::IsNil(CkUuid::ToUuid('junk'));                   // -> true   (a rejected read is the nil UUID)
CkUuid::IsNil('junk');                                   // -> false  (not a UUID at all)

IsCanonical

Is it written in the canonical spelling?

static function IsCanonical(
    mixed $input = null,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): bool
Parameter Type Default What it does
input mixed null The raw value.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering false, when the value is not canonical UUID text.

Returns

When Default With throwIfInvalid: true
Text that is exactly the lowercase, hyphenated, 36-character form true true
A UUID in another dressing — braces, bare digits, upper case, urn:uuid: — or a UUID object false Throws — the reason says it is a UUID in another form
Rejected: not a UUID at all false Throws CkUuidException — carries Input, Expected and Reason

A shape check for API contracts and columns that must hold canonical text, the same idea as CkCountry::IsAlpha2. Surrounding whitespace and markup are cleaned away first; then the spelling must be exactly what Canonical would write. This one judges text and nothing else: a UUID object already carries its value and is not a spelling, so it answers false too. The all-zeros UUID is canonical-shaped, so true here — whether it means anything is IsUuid's question. To accept any shape and store the canonical spelling, read the value with Canonical instead.

use SafeCoder\CommonKit\CkUuid;

CkUuid::IsCanonical('08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f');     // -> true
CkUuid::IsCanonical('08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F');     // -> false  (upper case)
CkUuid::IsCanonical('{08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f}');   // -> false  (braces)

IsStandard

Is it an RFC 9562 UUID?

static function IsStandard(
    mixed $input = null,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): bool
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering false, when the value is not a UUID.

Returns

When Default With throwIfInvalid: true
The value reads as a UUID whose variant bits are the standard 10xx true true
Another variant: the legacy Microsoft or NCS layouts, the reserved variant, all ones false false
Rejected: not a UUID, or all zeros — always missing here false Throws CkUuidException — carries Input, Expected and Reason

The variant is what makes the Version digit meaningful: Version reads the digit as written, and a random sixteen bytes dressed as a UUID has one too. Pair the two when an id must be a real RFC 9562 UUID of a given kind.

use SafeCoder\CommonKit\CkUuid;

CkUuid::IsStandard('08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f');   // -> true   (variant 9)
CkUuid::IsStandard('08d3f9c6-5e4a-4b8f-cd2e-7a1b3c5d7e9f');   // -> false  (variant c: the Microsoft layout)
CkUuid::IsStandard(CkUuid::NewV7());                          // -> true

IsVersion

Is it one of these kinds?

static function IsVersion(
    mixed $input = null,
    mixed ...$versions
): bool
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
versions mixed ... (empty) The version digits to accept, 1 to 8 — each argument a digit, or a list of digits. An entry that is not a whole number accepts nothing.

Returns

When You get
The value reads as a UUID and its version digit is listed true
It is not a UUID, the digit is not listed, the list is empty, or the value is all zeros false — an answer, not a failure; it never throws

For "random or time-ordered ids only": IsVersion($id, 4, 7). Read the way Version reads it — the digit as written, zeros always missing. A variadic list must be last, so there is no throwIfInvalid; call Version with it first when you need the exception. Pair with IsStandard when the digit must be meaningful.

use SafeCoder\CommonKit\CkUuid;

CkUuid::IsVersion(
    input: '08d3f9c6-5e4a-4b8f-9d2e-7a1b3c5d7e9f',
    versions: [4, 7]
);   // -> true

CkUuid::IsVersion(
    input: '2ed6657d-e927-568b-95e1-2665a8aea6a2',
    versions: [4, 7]
);   // -> false  (a v5)

IsFromName

Does this id still match its natural key?

static function IsFromName(
    mixed $input = null,
    mixed $name = null,
    mixed $space = null,
    int $version = 5,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): bool
Parameter Type Default What it does
input mixed null The UUID to check: text in any everyday shape, or a UUID object.
name mixed null The name to derive from: text, or a whole number written invariantly. Hashed exactly as given.
space mixed null The name space UUID, in any shape Canonical reads.
version int 5 5 (SHA-1) or 3 (MD5), matching how the id was derived.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says which part cannot be used and why, instead of answering false.

Returns

When Default With throwIfInvalid: true
The value reads as a UUID and equals the one FromName derives true true
It reads, and is a different UUID false false
Rejected: the value is not a UUID, or the name, space or version cannot be used false Throws CkUuidException — carries Input, Expected and Reason

FromName($name, $space)->equals(ToUuid($input)) as one call, with the same rules on every part: the name is never cleaned, so ' claim-1 ' and 'claim-1' derive different ids. For verifying a stored id against the record's natural key, and for checking that another system derived the id the same way.

use SafeCoder\CommonKit\CkUuid;

CkUuid::IsFromName(
    input: '2ed6657d-e927-568b-95e1-2665a8aea6a2',
    name: 'www.example.com',
    space: CkUuid::NamespaceDns
);   // -> true

CkUuid::IsFromName(
    input: '2ed6657d-e927-568b-95e1-2665a8aea6a2',
    name: 'WWW.EXAMPLE.COM',
    space: CkUuid::NamespaceDns
);   // -> false  (the name is hashed as given)

SameUuid

The same id, whatever the dressing?

static function SameUuid(
    mixed $a = null,
    mixed $b = null,
    bool $treatZerosAsMissing = true,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): bool
Parameter Type Default What it does
a mixed null The first value: text in any shape, or a UUID object.
b mixed null The second value, read the same way.
treatZerosAsMissing bool true Counts the all-zeros UUID as missing, so two missing ids are not the same id. Switch it off to let two nil values match.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says which value is not a UUID and why, instead of answering false.

Returns

When Default With throwIfInvalid: true
Both read as UUIDs and are equal true true
Both read, and differ false false
Rejected: either value is not a UUID false Throws CkUuidException — carries Input, Expected and Reason

{08D3F9C6-…} from a database tool, the bare digits from a URL and a UUID object off another call all match one another. Two values that are not UUIDs are never the same — two rejected values are two unknowns, not one identity — and by default neither are two nil values, since missing is not an identity.

use SafeCoder\CommonKit\CkUuid;

CkUuid::SameUuid(
    a: '{08D3F9C6-5E4A-4B8F-9D2E-7A1B3C5D7E9F}',
    b: '08d3f9c65e4a4b8f9d2e7a1b3c5d7e9f'
);   // -> true

CkUuid::SameUuid(
    a: CkUuid::ToUuid('junk'),
    b: '00000000-0000-0000-0000-000000000000'
);   // -> false  (two missing)

NewV7

An id that sorts by time.

static function NewV7(
    mixed $at = null,
    bool $throwIfInvalid = CkSettings::DefaultThrowIfInvalid
): UuidInterface
Parameter Type Default What it does
at mixed null The moment to stamp, read as CkDate::ToCarbon reads one; null for now.
throwIfInvalid bool CkSettings::DefaultThrowIfInvalid (false) Pass true to throw a CkUuidException that says why, instead of answering the nil UUID, when at is not a date or lies before 1970, the epoch the id counts from.

Returns

When Default With throwIfInvalid: true
No moment, or a readable one A new RFC 9562 version 7 UUID The UUID
Rejected: at unreadable or out of range The nil UUID Throws CkUuidException — carries Input, Expected and Reason

The moment sits in the first 48 bits and random bits follow, so ids made in sequence sort in sequence — what a database index wants, and what a random version 4 does not give it. Two ids minted in the same millisecond still sort in the order they were made: the bits after the moment carry a counter that rises within a millisecond and is random again in the next one. Pin at in tests and for back-dated records.

use SafeCoder\CommonKit\CkUuid;

$id = CkUuid::NewV7();                               // now
$old = CkUuid::NewV7(at: '2026-08-31T14:05:00Z');    // sorts before $id
CkUuid::Version(CkUuid::NewV7());                    // -> 7

Explain

Why not — in words, without an exception.

static function Explain(
    mixed $input = null,
    bool $treatZerosAsMissing = true
): string
Parameter Type Default What it does
input mixed null The value: text in any everyday shape, or a UUID object.
treatZerosAsMissing bool true Counts the all-zeros UUID as missing.

Returns

When You get
The value passes the reader ''
It does not The reason, the same words the exception would carry — an answer, not a failure; it never throws

The form-friendly twin of throwIfInvalid: the message to show beside the field, without a try and catch. Every class with a reader has one, on the reader's own rules, so the reason is exactly what the reader would say.

use SafeCoder\CommonKit\CkUuid;

CkUuid::Explain('junk');                                     // -> 'not a UUID in a known shape'
CkUuid::Explain('00000000-0000-0000-0000-000000000000');     // -> 'the all-zeros UUID that means missing'
CkUuid::Explain(123);                                        // -> 'a Int32 is not a UUID'

Good to know

  • ToUuid has no fallback parameter — on purpose. An identifier names one specific thing; an invented identity is worse than none. Rejection is always the nil UUID, so you can catch it with IsNil — never a made-up id that quietly corrupts deduplication.
  • All zeros means missing, by default. 00000000-0000-0000-0000-000000000000 is what databases and serializers emit when nobody set a value — the 1900-01-01 of identifiers. Every reader takes treatZerosAsMissing (default true) except Version, IsStandard and IsVersion, which always count zeros as missing; ToUuidOrNull turns that missing value into an honest null, and IsNil is the one method that answers true to it.
  • The validators answer false, never the nil UUID. IsUuid, IsNil, IsCanonical, IsStandard, IsVersion, IsFromName and SameUuid answer false both for "no" and for "not a UUID"; pass throwIfInvalid: true when the difference matters. IsVersion never takes the flag.
  • IsCanonical judges the shape, Canonical reads any. IsCanonical('{…}') is false while Canonical('{…}') reads it fine. Use the validator where a field must already hold canonical text; use the reader everywhere else.
  • With the default on, the nil UUID is an unambiguous signal. No valid read can produce it, so CkUuid::IsNil($result) reliably means "rejected". Turn treatZerosAsMissing off and that signal becomes ambiguous — prefer Canonical and its '' there.
  • Four shapes in, plus the urn:uuid: prefix. Bare digits, hyphenated, braced, parenthesized, any casing. The exotic hex-struct 'X' form ({0x08d3f9c6,0x5e4a,...}) is source code, not data, and is rejected — in reading and as a Format shape.
  • Only text or a UUID object is a UUID. A string, an object that writes itself as text, or a UUID object the library handed out is read; an int, a float, a bool, an array or any other object is refused with "a Int32 is not a UUID" and the like — a UUID is 32 hexadecimal digits, and no number is written that way.
  • FromName never cleans the name. ' Claim-1 ' and 'claim-1' derive different UUIDs; normalise the name yourself, consistently, before deriving.
  • A UUID object reads directly. What ToUuid, FromName or NewV7 handed out goes straight back in — no toString() needed. CkDictionary uses the same reading for ToUuid on payload bags, and CkSentinel applies the same all-zeros verdict on the way to storage.
  • Non-empty in, empty out means rejected for Canonical and Format — the standard CommonKit signal (see How it works).

If you want errors instead

Pass throwIfInvalid: true and a value that cannot be used raises a CkUuidException (from SafeCoder\CommonKit\Exceptions) instead of returning the rejection value. The exception carries the Input, what was Expected and a short Reason, flattened into a one-line message.

use SafeCoder\CommonKit\CkUuid;

CkUuid::ToUuid(
    input: 'junk',
    throwIfInvalid: true
);   // throws CkUuidException — the message says why

ToUuidOrNull has no throwIfInvalid parameter and never throws — null is its answer for anything unusable. When a bad value should be an error, read it with ToUuid and the flag instead.