diff --git a/shared/Helpers/UuidHelper.php b/shared/Helpers/UuidHelper.php index 1af7a150..2d80f320 100644 --- a/shared/Helpers/UuidHelper.php +++ b/shared/Helpers/UuidHelper.php @@ -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); diff --git a/shared/ValueObjects/CrmHashcode.php b/shared/ValueObjects/CrmHashcode.php index 49e4a9d4..04850c0e 100644 --- a/shared/ValueObjects/CrmHashcode.php +++ b/shared/ValueObjects/CrmHashcode.php @@ -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)); } } diff --git a/tests/Unit/Shared/Helpers/UuidHelperTest.php b/tests/Unit/Shared/Helpers/UuidHelperTest.php index 53a80543..a72c6122 100644 --- a/tests/Unit/Shared/Helpers/UuidHelperTest.php +++ b/tests/Unit/Shared/Helpers/UuidHelperTest.php @@ -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); + }); }); diff --git a/tests/Unit/Shared/ValueObjects/CrmHashcodeTest.php b/tests/Unit/Shared/ValueObjects/CrmHashcodeTest.php index 99f5e973..62300f30 100644 --- a/tests/Unit/Shared/ValueObjects/CrmHashcodeTest.php +++ b/tests/Unit/Shared/ValueObjects/CrmHashcodeTest.php @@ -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); + }); });