feat(shared): encapsulate UUID generation and parsing in UuidHelper
This commit is contained in:
parent
617d1f70e9
commit
ad2c8f631b
4 changed files with 210 additions and 126 deletions
|
|
@ -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);
|
||||
|
|
|
|||
|
|
@ -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));
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue