diff --git a/docs/quickstart.rst b/docs/quickstart.rst index f61226ab..52444b89 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -92,6 +92,8 @@ without any special customization of the library. - Checks whether a string is a valid UUID. * - :php:meth:`Uuid::fromString() ` - Creates a UUID instance from a string UUID. + * - :php:meth:`Uuid::fromStrictString() ` + - Creates a UUID from a valid string representation. * - :php:meth:`Uuid::fromBytes() ` - Creates a UUID instance from a 16-byte string. * - :php:meth:`Uuid::fromInteger() ` diff --git a/docs/reference/uuid.rst b/docs/reference/uuid.rst index 27cbae16..031e4ce0 100644 --- a/docs/reference/uuid.rst +++ b/docs/reference/uuid.rst @@ -179,6 +179,14 @@ also provides constants used throughout the ramsey/uuid library. :param string $uuid: The string standard representation of a UUID :returntype: Ramsey\\Uuid\\UuidInterface + .. php:staticmethod:: fromStrictString($uuid) + + Creates a UUID from a valid string representation, validated against + the isValid method. + + :param string $uuid: The string standard representation of a UUID + :returntype: Ramsey\\Uuid\\UuidInterface + .. php:staticmethod:: fromBytes($bytes) Creates an instance of UuidInterface from a 16-byte string. diff --git a/docs/reference/uuidfactoryinterface.rst b/docs/reference/uuidfactoryinterface.rst index 8cb0c055..4678baf6 100644 --- a/docs/reference/uuidfactoryinterface.rst +++ b/docs/reference/uuidfactoryinterface.rst @@ -75,6 +75,14 @@ UuidFactoryInterface :param string $uuid: The string standard representation of a UUID :returntype: Ramsey\\Uuid\\UuidInterface + .. php:method:: fromStrictString($uuid) + + Creates a UUID from a valid string representation, validated against + the isValid method. + + :param string $uuid: The string standard representation of a UUID + :returntype: Ramsey\\Uuid\\UuidInterface + .. php:method:: fromBytes($bytes) Creates an instance of UuidInterface from a 16-byte string. diff --git a/src/Uuid.php b/src/Uuid.php index 0f05bbfb..fd682776 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -20,6 +20,7 @@ use Ramsey\Uuid\Converter\NumberConverterInterface; use Ramsey\Uuid\Converter\TimeConverterInterface; use Ramsey\Uuid\Exception\InvalidArgumentException; +use Ramsey\Uuid\Exception\InvalidUuidStringException; use Ramsey\Uuid\Exception\UnsupportedOperationException; use Ramsey\Uuid\Fields\FieldsInterface; use Ramsey\Uuid\Lazy\LazyUuidFromString; @@ -502,6 +503,25 @@ public static function fromString(string $uuid): UuidInterface return self::getFactory()->fromString($uuid); } + /** + * Creates a UUID from a valid string representation, validated against the isValid method + * + * @param string $uuid A valid UUID string representation + * + * @return UuidInterface A UuidInterface instance created from a valid UUID + * string representation + * + * @throws InvalidUuidStringException + */ + public static function fromStrictString(string $uuid): UuidInterface + { + if (! self::isValid($uuid)) { + throw new InvalidUuidStringException('Invalid UUID string: ' . $uuid); + } + + return self::fromString($uuid); + } + /** * Creates a UUID from a DateTimeInterface instance * diff --git a/src/UuidFactory.php b/src/UuidFactory.php index c7607a1b..368c7bf6 100644 --- a/src/UuidFactory.php +++ b/src/UuidFactory.php @@ -19,6 +19,7 @@ use Ramsey\Uuid\Codec\CodecInterface; use Ramsey\Uuid\Converter\NumberConverterInterface; use Ramsey\Uuid\Converter\TimeConverterInterface; +use Ramsey\Uuid\Exception\InvalidUuidStringException; use Ramsey\Uuid\Generator\DceSecurityGeneratorInterface; use Ramsey\Uuid\Generator\DefaultTimeGenerator; use Ramsey\Uuid\Generator\NameGeneratorInterface; @@ -270,6 +271,15 @@ public function fromString(string $uuid): UuidInterface return $this->codec->decode($uuid); } + public function fromStrictString(string $uuid): UuidInterface + { + if (! $this->getValidator()->validate($uuid)) { + throw new InvalidUuidStringException('Invalid UUID string: ' . $uuid); + } + + return $this->codec->decode($uuid); + } + /** * @pure */ diff --git a/src/UuidFactoryInterface.php b/src/UuidFactoryInterface.php index 5a83a797..63f7b9df 100644 --- a/src/UuidFactoryInterface.php +++ b/src/UuidFactoryInterface.php @@ -15,6 +15,7 @@ namespace Ramsey\Uuid; use DateTimeInterface; +use Ramsey\Uuid\Exception\InvalidUuidStringException; use Ramsey\Uuid\Type\Hexadecimal; use Ramsey\Uuid\Type\Integer as IntegerObject; use Ramsey\Uuid\Validator\ValidatorInterface; @@ -73,6 +74,18 @@ public function fromInteger(string $integer): UuidInterface; */ public function fromString(string $uuid): UuidInterface; + /** + * Creates a UUID from a valid string representation, validated against the isValid method + * + * @param string $uuid A valid UUID string representation + * + * @return UuidInterface A UuidInterface instance created from a valid UUID + * string representation + * + * @throws InvalidUuidStringException + */ + public function fromStrictString(string $uuid): UuidInterface; + /** * Returns the validator used by the factory */ diff --git a/tests/UuidFactoryTest.php b/tests/UuidFactoryTest.php index c9ee5f19..1c3abe7c 100644 --- a/tests/UuidFactoryTest.php +++ b/tests/UuidFactoryTest.php @@ -13,6 +13,7 @@ use Ramsey\Uuid\Codec\CodecInterface; use Ramsey\Uuid\Converter\NumberConverterInterface; use Ramsey\Uuid\Converter\TimeConverterInterface; +use Ramsey\Uuid\Exception\InvalidUuidStringException; use Ramsey\Uuid\FeatureSet; use Ramsey\Uuid\Generator\DceSecurityGeneratorInterface; use Ramsey\Uuid\Generator\DefaultNameGenerator; @@ -60,6 +61,32 @@ public function testFromStringParsesUuidInLowercase(): void $this->assertSame($uuidString, $uuid->toString()); } + public function testFromStrictStringWithInvalidUuidString(): void + { + $this->expectException(InvalidUuidStringException::class); + + $factory = new UuidFactory(new FeatureSet(true)); + + $factory->fromStrictString('00000000000000000000000000000000'); + } + + public function testFromStrictStringWithValidUuidString(): void + { + $factory = new UuidFactory(new FeatureSet(true)); + + $this->assertSame( + 'ff6f8cb0-c57d-11e1-9b21-0800200c9a66', + $factory->fromStrictString('ff6f8cb0-c57d-11e1-9b21-0800200c9a66') + ->toString() + ); + + $this->assertSame( + '00000000-0000-0000-0000-000000000000', + $factory->fromStrictString('00000000-0000-0000-0000-000000000000') + ->toString() + ); + } + public function testGettersReturnValueFromFeatureSet(): void { $codec = Mockery::mock(CodecInterface::class); diff --git a/tests/UuidTest.php b/tests/UuidTest.php index 415b0c3a..c996d0b1 100644 --- a/tests/UuidTest.php +++ b/tests/UuidTest.php @@ -73,6 +73,34 @@ public function testFromString(): void Uuid::fromString('ff6f8cb0-c57d-11e1-9b21-0800200c9a66') ->toString() ); + + $this->assertSame( + '00000000-0000-0000-0000-000000000000', + Uuid::fromString('00000000000000000000000000000000') + ->toString() + ); + } + + public function testFromStrictString(): void + { + $this->assertSame( + 'ff6f8cb0-c57d-11e1-9b21-0800200c9a66', + Uuid::fromStrictString('ff6f8cb0-c57d-11e1-9b21-0800200c9a66') + ->toString() + ); + + $this->assertSame( + '00000000-0000-0000-0000-000000000000', + Uuid::fromStrictString('00000000-0000-0000-0000-000000000000') + ->toString() + ); + } + + public function testFromStrictStringWithInvalidUuidString(): void + { + $this->expectException(InvalidUuidStringException::class); + + Uuid::fromStrictString('00000000000000000000000000000000'); } public function testFromHexadecimal(): void