diff --git a/src/Codec/CodecInterface.php b/src/Codec/CodecInterface.php index 45b3250..812bf41 100644 --- a/src/Codec/CodecInterface.php +++ b/src/Codec/CodecInterface.php @@ -29,6 +29,8 @@ interface CodecInterface * * @return string Hexadecimal string representation of a UUID * + * @psalm-return non-empty-string + * * @psalm-pure */ public function encode(UuidInterface $uuid): string; @@ -41,6 +43,8 @@ interface CodecInterface * * @return string Binary string representation of a UUID * + * @psalm-return non-empty-string + * * @psalm-pure */ public function encodeBinary(UuidInterface $uuid): string; diff --git a/src/Codec/OrderedTimeCodec.php b/src/Codec/OrderedTimeCodec.php index 8dc4ebe..540dd57 100644 --- a/src/Codec/OrderedTimeCodec.php +++ b/src/Codec/OrderedTimeCodec.php @@ -46,6 +46,9 @@ class OrderedTimeCodec extends StringCodec * * @inheritDoc * @psalm-pure + * @psalm-return non-empty-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty */ public function encodeBinary(UuidInterface $uuid): string { diff --git a/src/Codec/StringCodec.php b/src/Codec/StringCodec.php index 64455bf..478daad 100644 --- a/src/Codec/StringCodec.php +++ b/src/Codec/StringCodec.php @@ -65,6 +65,9 @@ class StringCodec implements CodecInterface /** * @psalm-pure + * @psalm-return non-empty-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty */ public function encodeBinary(UuidInterface $uuid): string { diff --git a/src/Codec/TimestampFirstCombCodec.php b/src/Codec/TimestampFirstCombCodec.php index 5ea4d62..4ab58eb 100644 --- a/src/Codec/TimestampFirstCombCodec.php +++ b/src/Codec/TimestampFirstCombCodec.php @@ -45,6 +45,9 @@ class TimestampFirstCombCodec extends StringCodec { /** * @psalm-pure + * @psalm-return non-empty-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty */ public function encode(UuidInterface $uuid): string { @@ -62,6 +65,9 @@ class TimestampFirstCombCodec extends StringCodec /** * @psalm-pure + * @psalm-return non-empty-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty */ public function encodeBinary(UuidInterface $uuid): string { diff --git a/src/Converter/Number/GenericNumberConverter.php b/src/Converter/Number/GenericNumberConverter.php index fe5e6c5..cf37b97 100644 --- a/src/Converter/Number/GenericNumberConverter.php +++ b/src/Converter/Number/GenericNumberConverter.php @@ -37,6 +37,9 @@ class GenericNumberConverter implements NumberConverterInterface /** * @inheritDoc * @psalm-pure + * @psalm-return numeric-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty */ public function fromHex(string $hex): string { @@ -46,6 +49,9 @@ class GenericNumberConverter implements NumberConverterInterface /** * @inheritDoc * @psalm-pure + * @psalm-return non-empty-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty */ public function toHex(string $number): string { diff --git a/src/Converter/NumberConverterInterface.php b/src/Converter/NumberConverterInterface.php index 9ecea88..5963d48 100644 --- a/src/Converter/NumberConverterInterface.php +++ b/src/Converter/NumberConverterInterface.php @@ -31,6 +31,8 @@ interface NumberConverterInterface * * @return string String representation of an integer * + * @psalm-return numeric-string + * * @psalm-pure */ public function fromHex(string $hex): string; @@ -45,6 +47,8 @@ interface NumberConverterInterface * * @return string Hexadecimal string * + * @psalm-return non-empty-string + * * @psalm-pure */ public function toHex(string $number): string; diff --git a/src/Uuid.php b/src/Uuid.php index 9dc484a..e4489fe 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -227,6 +227,7 @@ class Uuid implements UuidInterface $this->timeConverter = $timeConverter; } + /** @psalm-return non-empty-string */ public function __toString(): string { return $this->toString(); @@ -289,6 +290,7 @@ class Uuid implements UuidInterface return $this->compareTo($other) === 0; } + /** @psalm-return non-empty-string */ public function getBytes(): string { return $this->codec->encodeBinary($this); @@ -299,16 +301,23 @@ class Uuid implements UuidInterface return $this->fields; } + /** + * @psalm-return non-empty-string + * @psalm-suppress MoreSpecificReturnType we know that the retrieved `string` is never empty + * @psalm-suppress LessSpecificReturnStatement we know that the retrieved `string` is never empty + */ public function getHex(): string { return str_replace('-', '', $this->toString()); } + /** @psalm-return non-empty-string */ public function getInteger(): string { return $this->numberConverter->fromHex($this->getHex()); } + /** @psalm-return non-empty-string */ public function toString(): string { return $this->codec->encode($this); diff --git a/src/UuidInterface.php b/src/UuidInterface.php index 8eb3ff3..0296e7d 100644 --- a/src/UuidInterface.php +++ b/src/UuidInterface.php @@ -61,6 +61,8 @@ interface UuidInterface extends /** * Returns the binary string representation of the UUID + * + * @psalm-return non-empty-string */ public function getBytes(): string; @@ -71,21 +73,29 @@ interface UuidInterface extends /** * Returns the hexadecimal string representation of the UUID + * + * @psalm-return non-empty-string */ public function getHex(): string; /** * Returns the integer value of the UUID as a string + * + * @psalm-return non-empty-string */ public function getInteger(): string; /** * Returns a string representation of the UUID + * + * @psalm-return non-empty-string */ public function toString(): string; /** * Casts the UUID to a string representation + * + * @psalm-return non-empty-string */ public function __toString(): string; } diff --git a/tests/static-analysis/UuidIsNeverEmpty.php b/tests/static-analysis/UuidIsNeverEmpty.php new file mode 100644 index 0000000..524eb5b --- /dev/null +++ b/tests/static-analysis/UuidIsNeverEmpty.php @@ -0,0 +1,48 @@ + + * @license http://opensource.org/licenses/MIT MIT + */ + +declare(strict_types=1); + +namespace Ramsey\Uuid\StaticAnalysis; + +use Ramsey\Uuid\UuidInterface; + +/** + * This is a static analysis fixture to verify that the API signature + * of a UUID does not return empty strings for methods that never will do so. + */ +final class UuidIsNeverEmpty +{ + /** @psalm-return non-empty-string */ + public function bytesAreNeverEmpty(UuidInterface $uuid): string + { + return $uuid->getBytes(); + } + + /** @psalm-return non-empty-string */ + public function hexIsNeverEmpty(UuidInterface $uuid): string + { + return $uuid->getHex(); + } + + /** @psalm-return non-empty-string */ + public function integerIsNeverEmpty(UuidInterface $uuid): string + { + return $uuid->getInteger(); + } + + /** @psalm-return non-empty-string */ + public function stringIsNeverEmpty(UuidInterface $uuid): string + { + return $uuid->toString(); + } +}