feat(shared): encapsulate UUID generation and parsing in UuidHelper

This commit is contained in:
Jérémy Munsch 2026-11-17 12:15:28 +01:00
parent 617d1f70e9
commit ad2c8f631b
No known key found for this signature in database
GPG key ID: 2AAECDA6B7330F91
4 changed files with 210 additions and 126 deletions

View file

@ -4,6 +4,7 @@ declare(strict_types=1);
namespace Shared\Helpers;
use Carbon\CarbonImmutable;
use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;
@ -17,6 +18,36 @@ final readonly class UuidHelper
// Static class
}
public static function fromString(string $uuid): UuidInterface
{
if (! Uuid::isValid($uuid)) {
throw InvalidUuidException::forValue($uuid);
}
return Uuid::fromString($uuid);
}
public static function v4(): UuidInterface
{
return Uuid::uuid4();
}
public static function v7(?\DateTimeInterface $dateTime = null): UuidInterface
{
return Uuid::uuid7($dateTime ?? CarbonImmutable::now());
}
public static function parse(string $value): UuidInterface
{
$trimmed = trim($value);
if (self::isValid($trimmed)) {
return self::fromString($trimmed);
}
return self::fromBase58($trimmed);
}
public static function isValid(string $uuid): bool
{
return Uuid::isValid($uuid);

View file

@ -4,7 +4,6 @@ declare(strict_types=1);
namespace Shared\ValueObjects;
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;
use Shared\Helpers\UuidHelper;
@ -30,6 +29,6 @@ final readonly class CrmHashcode implements \Stringable
public static function fromString(string $value): self
{
return new self(Uuid::fromString($value));
return new self(UuidHelper::fromString($value));
}
}

View file

@ -4,6 +4,7 @@ declare(strict_types=1);
namespace Tests\Unit\Shared\Helpers;
use Carbon\CarbonImmutable;
use Ramsey\Uuid\Lazy\LazyUuidFromString;
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;
@ -12,97 +13,148 @@ use Shared\Helpers\UuidHelper;
covers(UuidHelper::class);
it('validates uuid strings with isValid', function (): void {
// GIVEN
$v4 = Uuid::uuid4()->toString();
$v7 = Uuid::uuid7()->toString();
$invalid = 'not-a-uuid';
describe('UuidHelper', function (): void {
it('validates uuid strings with isValid', function (): void {
// GIVEN
$v4 = Uuid::uuid4()->toString();
$v7 = Uuid::uuid7()->toString();
$invalid = 'not-a-uuid';
// WHEN & THEN
expect(UuidHelper::isValid($v4))->toBeTrue()
->and(UuidHelper::isValid($v7))->toBeTrue()
->and(UuidHelper::isValid($invalid))->toBeFalse();
});
it('roundtrips v4 and v7 uuids through base58 including surrounding whitespace', function (): void {
// GIVEN
$v4 = Uuid::uuid4();
$v7 = Uuid::uuid7();
// WHEN
$v4Base58 = UuidHelper::toBase58($v4);
$v7Base58 = UuidHelper::toBase58($v7);
$decodedV4 = UuidHelper::fromBase58(" {$v4Base58} \n");
$decodedV7 = UuidHelper::fromBase58("\t{$v7Base58} ");
// THEN
expect($decodedV4->toString())->toBe($v4->toString())
->and($decodedV7->toString())->toBe($v7->toString());
});
it('rejects invalid base58 inputs', function (string $input): void {
// GIVEN / WHEN / THEN
expect(static fn (): UuidInterface => UuidHelper::fromBase58($input))
->toThrow(InvalidUuidException::class);
})->with([
'empty string' => [''],
'too short' => ['12345678901234567890'],
'too long' => ['12345678901234567890123'],
'ambiguous chars 0OIl' => ['0OIl123456789012345678'],
'invalid payload' => ['zzzzzzzzzzzzzzzzzzzzzz'],
]);
it('detects uuid versions for v4, v7, and v1', function (): void {
// GIVEN
$v4 = Uuid::uuid4();
$v7 = Uuid::uuid7();
$v1 = Uuid::uuid1();
// WHEN & THEN
expect(UuidHelper::version($v4))->toBe(4)
->and(UuidHelper::isV4($v4))->toBeTrue()
->and(UuidHelper::isV7($v4))->toBeFalse()
->and(UuidHelper::version($v7))->toBe(7)
->and(UuidHelper::isV4($v7))->toBeFalse()
->and(UuidHelper::isV7($v7))->toBeTrue()
->and(UuidHelper::version($v1))->toBe(1)
->and(UuidHelper::isV4($v1))->toBeFalse()
->and(UuidHelper::isV7($v1))->toBeFalse();
});
it('passes validateUuid for valid uuid and throws for invalid UuidInterface', function (): void {
// GIVEN
$valid = Uuid::uuid4();
$invalid = new LazyUuidFromString('invalid');
// WHEN
UuidHelper::validateUuid($valid);
// THEN
expect(static function () use ($invalid): void {
UuidHelper::validateUuid($invalid);
})->toThrow(InvalidUuidException::class);
});
it('extracts exact utc datetime with millisecond precision from v7 uuid', function (): void {
// GIVEN
$expected = new \DateTimeImmutable('2025-06-15 12:34:56.789000', new \DateTimeZone('UTC'));
$v7 = Uuid::uuid7($expected);
// WHEN
$actual = UuidHelper::toDateTime($v7);
// THEN
expect($actual->getTimezone()->getName())->toBe('UTC')
->and($actual->format('Y-m-d H:i:s.v'))->toBe($expected->format('Y-m-d H:i:s.v'));
});
it('throws InvalidUuidException when extracting datetime from non-v7 uuid', function (): void {
// GIVEN
$v4 = Uuid::uuid4();
// WHEN & THEN
expect(static fn (): \DateTimeImmutable => UuidHelper::toDateTime($v4))
->toThrow(InvalidUuidException::class);
// WHEN & THEN
expect(UuidHelper::isValid($v4))->toBeTrue()
->and(UuidHelper::isValid($v7))->toBeTrue()
->and(UuidHelper::isValid($invalid))->toBeFalse();
});
it('roundtrips v4 and v7 uuids through base58 including surrounding whitespace', function (): void {
// GIVEN
$v4 = Uuid::uuid4();
$v7 = Uuid::uuid7();
// WHEN
$v4Base58 = UuidHelper::toBase58($v4);
$v7Base58 = UuidHelper::toBase58($v7);
$decodedV4 = UuidHelper::fromBase58(" {$v4Base58} \n");
$decodedV7 = UuidHelper::fromBase58("\t{$v7Base58} ");
// THEN
expect($decodedV4->toString())->toBe($v4->toString())
->and($decodedV7->toString())->toBe($v7->toString());
});
it('rejects invalid base58 inputs', function (string $input): void {
// GIVEN / WHEN / THEN
expect(static fn (): UuidInterface => UuidHelper::fromBase58($input))
->toThrow(InvalidUuidException::class);
})->with([
'empty string' => [''],
'too short' => ['12345678901234567890'],
'too long' => ['12345678901234567890123'],
'ambiguous chars 0OIl' => ['0OIl123456789012345678'],
'invalid payload' => ['zzzzzzzzzzzzzzzzzzzzzz'],
]);
it('detects uuid versions for v4, v7, and v1', function (): void {
// GIVEN
$v4 = Uuid::uuid4();
$v7 = Uuid::uuid7();
$v1 = Uuid::uuid1();
// WHEN & THEN
expect(UuidHelper::version($v4))->toBe(4)
->and(UuidHelper::isV4($v4))->toBeTrue()
->and(UuidHelper::isV7($v4))->toBeFalse()
->and(UuidHelper::version($v7))->toBe(7)
->and(UuidHelper::isV4($v7))->toBeFalse()
->and(UuidHelper::isV7($v7))->toBeTrue()
->and(UuidHelper::version($v1))->toBe(1)
->and(UuidHelper::isV4($v1))->toBeFalse()
->and(UuidHelper::isV7($v1))->toBeFalse();
});
it('passes validateUuid for valid uuid and throws for invalid UuidInterface', function (): void {
// GIVEN
$valid = Uuid::uuid4();
$invalid = new LazyUuidFromString('invalid');
// WHEN
UuidHelper::validateUuid($valid);
// THEN
expect(static function () use ($invalid): void {
UuidHelper::validateUuid($invalid);
})->toThrow(InvalidUuidException::class);
});
it('extracts exact utc datetime with millisecond precision from v7 uuid', function (): void {
// GIVEN
$expected = new \DateTimeImmutable('2025-06-15 12:34:56.789000', new \DateTimeZone('UTC'));
$v7 = Uuid::uuid7($expected);
// WHEN
$actual = UuidHelper::toDateTime($v7);
// THEN
expect($actual->getTimezone()->getName())->toBe('UTC')
->and($actual->format('Y-m-d H:i:s.v'))->toBe($expected->format('Y-m-d H:i:s.v'));
});
it('throws InvalidUuidException when extracting datetime from non-v7 uuid', function (): void {
// GIVEN
$v4 = Uuid::uuid4();
// WHEN & THEN
expect(static fn (): \DateTimeImmutable => UuidHelper::toDateTime($v4))
->toThrow(InvalidUuidException::class);
});
it('generates a v7 uuid using CarbonImmutable::now when no datetime is provided', function (): void {
// GIVEN
$frozen = CarbonImmutable::parse('2026-11-16 12:34:56.000', 'UTC');
CarbonImmutable::setTestNow($frozen);
try {
// WHEN
$uuid = UuidHelper::v7();
// THEN
expect(UuidHelper::isV7($uuid))->toBeTrue()
->and(UuidHelper::toDateTime($uuid)->format('Y-m-d H:i:s'))->toBe('2026-11-16 12:34:56');
} finally {
CarbonImmutable::setTestNow();
}
});
it('generates a v7 uuid using the provided datetime', function (): void {
// GIVEN
$dateTime = new \DateTimeImmutable('2025-05-01 08:15:30', new \DateTimeZone('UTC'));
// WHEN
$uuid = UuidHelper::v7($dateTime);
// THEN
expect(UuidHelper::isV7($uuid))->toBeTrue()
->and(UuidHelper::toDateTime($uuid)->format('Y-m-d H:i:s'))->toBe('2025-05-01 08:15:30');
});
it('generates a v4 uuid with UuidHelper::v4', function (): void {
// WHEN
$uuid = UuidHelper::v4();
// THEN
expect(UuidHelper::isV4($uuid))->toBeTrue();
});
it('parses both rfc4122 and base58 uuids with UuidHelper::parse and throws on invalid input', function (): void {
// GIVEN
$v7 = UuidHelper::v7();
$base58 = UuidHelper::toBase58($v7);
// WHEN & THEN
expect(UuidHelper::parse($v7->toString())->toString())->toBe($v7->toString())
->and(UuidHelper::parse($base58)->toString())->toBe($v7->toString())
->and(static fn (): UuidInterface => UuidHelper::parse('invalid-uuid'))
->toThrow(InvalidUuidException::class);
});
});

View file

@ -4,42 +4,44 @@ declare(strict_types=1);
namespace Tests\Unit\Shared\ValueObjects;
use Ramsey\Uuid\Exception\InvalidUuidStringException;
use Ramsey\Uuid\Uuid;
use Shared\Exceptions\InvalidUuidException;
use Shared\Helpers\UuidHelper;
use Shared\ValueObjects\CrmHashcode;
covers(CrmHashcode::class);
it('instantiates from Uuid v4 and fromString with matching value and string cast', function (): void {
// GIVEN
$uuid = Uuid::uuid4();
$v4String = $uuid->toString();
describe('CrmHashcode', function (): void {
it('instantiates from Uuid v4 and fromString with matching value and string cast', function (): void {
// GIVEN
$uuid = UuidHelper::v4();
$v4String = $uuid->toString();
// WHEN
$fromUuid = new CrmHashcode($uuid);
$fromString = CrmHashcode::fromString($v4String);
// WHEN
$fromUuid = new CrmHashcode($uuid);
$fromString = CrmHashcode::fromString($v4String);
// THEN
expect($fromUuid->value)->toBe($v4String)
->and((string) $fromUuid)->toBe($v4String)
->and($fromString->value)->toBe($v4String)
->and((string) $fromString)->toBe($v4String);
});
it('rejects non-v4 uuids with DomainException', function (): void {
// GIVEN
$v7 = Uuid::uuid7();
$v1 = Uuid::uuid1();
// WHEN & THEN
expect(static fn (): CrmHashcode => new CrmHashcode($v7))
->toThrow(\DomainException::class)
->and(static fn (): CrmHashcode => new CrmHashcode($v1))
->toThrow(\DomainException::class);
});
it('throws InvalidUuidStringException when fromString receives invalid uuid', function (): void {
// GIVEN / WHEN / THEN
expect(static fn (): CrmHashcode => CrmHashcode::fromString('not-a-uuid'))
->toThrow(InvalidUuidStringException::class);
// THEN
expect($fromUuid->value)->toBe($v4String)
->and((string) $fromUuid)->toBe($v4String)
->and($fromString->value)->toBe($v4String)
->and((string) $fromString)->toBe($v4String);
});
it('rejects non-v4 uuids with DomainException', function (): void {
// GIVEN
$v7 = UuidHelper::v7();
$v1 = UuidHelper::fromString('00000000-0000-1000-8000-000000000000');
// WHEN & THEN
expect(static fn (): CrmHashcode => new CrmHashcode($v7))
->toThrow(\DomainException::class)
->and(static fn (): CrmHashcode => new CrmHashcode($v1))
->toThrow(\DomainException::class);
});
it('throws InvalidUuidException when fromString receives invalid uuid', function (): void {
// GIVEN / WHEN / THEN
expect(static fn (): CrmHashcode => CrmHashcode::fromString('not-a-uuid'))
->toThrow(InvalidUuidException::class);
});
});