From 4b7374129c8b0899bbb2e5e30abffe2daa55a42b Mon Sep 17 00:00:00 2001 From: Marco Perone Date: Mon, 9 Jul 2018 09:04:12 +0200 Subject: [PATCH] add annotations for thrown exceptions --- src/Codec/CodecInterface.php | 3 +++ src/Codec/GuidStringCodec.php | 2 ++ src/Codec/OrderedTimeCodec.php | 1 + src/Codec/StringCodec.php | 3 +++ src/Codec/TimestampFirstCombCodec.php | 2 ++ src/Converter/NumberConverterInterface.php | 2 ++ src/Converter/Time/DegradedTimeConverter.php | 2 +- src/Converter/TimeConverterInterface.php | 2 ++ src/DegradedUuid.php | 3 +++ src/Generator/CombGenerator.php | 3 +++ src/Generator/DefaultTimeGenerator.php | 6 +++++ src/Generator/RandomBytesGenerator.php | 1 + src/Generator/RandomGeneratorInterface.php | 3 +++ src/Generator/TimeGeneratorInterface.php | 4 +++ src/Provider/Node/FallbackNodeProvider.php | 1 + src/Provider/Node/RandomNodeProvider.php | 1 + src/Provider/NodeProviderInterface.php | 1 + src/Uuid.php | 26 ++++++++++++++++++++ src/UuidFactory.php | 22 +++++++++++++++++ src/UuidFactoryInterface.php | 18 ++++++++++++-- src/UuidInterface.php | 3 +++ 21 files changed, 106 insertions(+), 3 deletions(-) diff --git a/src/Codec/CodecInterface.php b/src/Codec/CodecInterface.php index f0dde95..6ea2054 100644 --- a/src/Codec/CodecInterface.php +++ b/src/Codec/CodecInterface.php @@ -42,6 +42,7 @@ interface CodecInterface * * @param string $encodedUuid * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function decode($encodedUuid); @@ -50,6 +51,8 @@ interface CodecInterface * * @param string $bytes * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException + * @throws \InvalidArgumentException if string has not 16 characters */ public function decodeBytes($bytes); } diff --git a/src/Codec/GuidStringCodec.php b/src/Codec/GuidStringCodec.php index 380d94e..864980b 100644 --- a/src/Codec/GuidStringCodec.php +++ b/src/Codec/GuidStringCodec.php @@ -60,6 +60,7 @@ class GuidStringCodec extends StringCodec * * @param string $encodedUuid * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function decode($encodedUuid) { @@ -75,6 +76,7 @@ class GuidStringCodec extends StringCodec * * @param string $bytes * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function decodeBytes($bytes) { diff --git a/src/Codec/OrderedTimeCodec.php b/src/Codec/OrderedTimeCodec.php index cbbb75e..3257759 100644 --- a/src/Codec/OrderedTimeCodec.php +++ b/src/Codec/OrderedTimeCodec.php @@ -50,6 +50,7 @@ class OrderedTimeCodec extends StringCodec * * @param string $bytes * @return UuidInterface + * @throws \InvalidArgumentException if string has not 16 characters */ public function decodeBytes($bytes) { diff --git a/src/Codec/StringCodec.php b/src/Codec/StringCodec.php index 4618196..7f35206 100644 --- a/src/Codec/StringCodec.php +++ b/src/Codec/StringCodec.php @@ -74,6 +74,7 @@ class StringCodec implements CodecInterface * * @param string $encodedUuid * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function decode($encodedUuid) { @@ -88,6 +89,7 @@ class StringCodec implements CodecInterface * * @param string $bytes * @return UuidInterface + * @throws \InvalidArgumentException if string has not 16 characters */ public function decodeBytes($bytes) { @@ -115,6 +117,7 @@ class StringCodec implements CodecInterface * * @param string $encodedUuid * @return array + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ protected function extractComponents($encodedUuid) { diff --git a/src/Codec/TimestampFirstCombCodec.php b/src/Codec/TimestampFirstCombCodec.php index c443438..2c4ded8 100644 --- a/src/Codec/TimestampFirstCombCodec.php +++ b/src/Codec/TimestampFirstCombCodec.php @@ -60,6 +60,7 @@ class TimestampFirstCombCodec extends StringCodec * @param string $encodedUuid * * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function decode($encodedUuid) { @@ -76,6 +77,7 @@ class TimestampFirstCombCodec extends StringCodec * @param string $bytes * * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function decodeBytes($bytes) { diff --git a/src/Converter/NumberConverterInterface.php b/src/Converter/NumberConverterInterface.php index 673c1df..9505e8c 100644 --- a/src/Converter/NumberConverterInterface.php +++ b/src/Converter/NumberConverterInterface.php @@ -28,6 +28,7 @@ interface NumberConverterInterface * * @param string $hex The hexadecimal string representation to convert * @return mixed + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present */ public function fromHex($hex); @@ -39,6 +40,7 @@ interface NumberConverterInterface * a true integer, a string integer, or a object representation that * this converter can understand * @return string Hexadecimal string + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present */ public function toHex($integer); } diff --git a/src/Converter/Time/DegradedTimeConverter.php b/src/Converter/Time/DegradedTimeConverter.php index 46edbe7..b94589c 100644 --- a/src/Converter/Time/DegradedTimeConverter.php +++ b/src/Converter/Time/DegradedTimeConverter.php @@ -30,7 +30,7 @@ class DegradedTimeConverter implements TimeConverterInterface * @param string $seconds * @param string $microSeconds * @return void - * @throws UnsatisfiedDependencyException + * @throws UnsatisfiedDependencyException if called on a 32-bit system and `Moontoast\Math\BigNumber` is not present */ public function calculateTime($seconds, $microSeconds) { diff --git a/src/Converter/TimeConverterInterface.php b/src/Converter/TimeConverterInterface.php index f068836..382008a 100644 --- a/src/Converter/TimeConverterInterface.php +++ b/src/Converter/TimeConverterInterface.php @@ -27,6 +27,8 @@ interface TimeConverterInterface * @param string $seconds * @param string $microSeconds * @return string[] An array guaranteed to contain `low`, `mid`, and `high` keys + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system and + * `Moontoast\Math\BigNumber` is not present * @link http://tools.ietf.org/html/rfc4122#section-4.2.2 */ public function calculateTime($seconds, $microSeconds); diff --git a/src/DegradedUuid.php b/src/DegradedUuid.php index b596c38..bcf0be8 100644 --- a/src/DegradedUuid.php +++ b/src/DegradedUuid.php @@ -24,6 +24,9 @@ use Ramsey\Uuid\Exception\UnsupportedOperationException; */ class DegradedUuid extends Uuid { + /** + * @inheritdoc + */ public function getDateTime() { if ($this->getVersion() != 1) { diff --git a/src/Generator/CombGenerator.php b/src/Generator/CombGenerator.php index 1a42776..7a94823 100644 --- a/src/Generator/CombGenerator.php +++ b/src/Generator/CombGenerator.php @@ -53,6 +53,9 @@ class CombGenerator implements RandomGeneratorInterface * * @param integer $length The number of bytes of random binary data to generate * @return string A binary string + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException if length is not a positive integer + * @throws \Exception */ public function generate($length) { diff --git a/src/Generator/DefaultTimeGenerator.php b/src/Generator/DefaultTimeGenerator.php index f05d818..c9969b3 100644 --- a/src/Generator/DefaultTimeGenerator.php +++ b/src/Generator/DefaultTimeGenerator.php @@ -72,6 +72,10 @@ class DefaultTimeGenerator implements TimeGeneratorInterface * could arise when the clock is set backwards in time or if the node ID * changes. * @return string A binary string + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system and + * `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception if it was not possible to gather sufficient entropy */ public function generate($node = null, $clockSeq = null) { @@ -111,6 +115,8 @@ class DefaultTimeGenerator implements TimeGeneratorInterface * * @param string|int $node A node value that may be used to override the node provider * @return string Hexadecimal representation of the node ID + * @throws \InvalidArgumentException + * @throws \Exception */ protected function getValidNode($node) { diff --git a/src/Generator/RandomBytesGenerator.php b/src/Generator/RandomBytesGenerator.php index 1e8392a..aaa285d 100644 --- a/src/Generator/RandomBytesGenerator.php +++ b/src/Generator/RandomBytesGenerator.php @@ -28,6 +28,7 @@ class RandomBytesGenerator implements RandomGeneratorInterface * * @param integer $length The number of bytes of random binary data to generate * @return string A binary string + * @throws \Exception if it was not possible to gather sufficient entropy */ public function generate($length) { diff --git a/src/Generator/RandomGeneratorInterface.php b/src/Generator/RandomGeneratorInterface.php index 87ccbc9..3a1bcae 100644 --- a/src/Generator/RandomGeneratorInterface.php +++ b/src/Generator/RandomGeneratorInterface.php @@ -25,6 +25,9 @@ interface RandomGeneratorInterface * * @param integer $length The number of bytes of random binary data to generate * @return string A binary string + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception if it was not possible to gather sufficient entropy */ public function generate($length); } diff --git a/src/Generator/TimeGeneratorInterface.php b/src/Generator/TimeGeneratorInterface.php index 1a56d51..cb182ea 100644 --- a/src/Generator/TimeGeneratorInterface.php +++ b/src/Generator/TimeGeneratorInterface.php @@ -30,6 +30,10 @@ interface TimeGeneratorInterface * could arise when the clock is set backwards in time or if the node ID * changes. * @return string A binary string + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system and + * `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception if it was not possible to gather sufficient entropy */ public function generate($node = null, $clockSeq = null); } diff --git a/src/Provider/Node/FallbackNodeProvider.php b/src/Provider/Node/FallbackNodeProvider.php index e230e17..289fdde 100644 --- a/src/Provider/Node/FallbackNodeProvider.php +++ b/src/Provider/Node/FallbackNodeProvider.php @@ -43,6 +43,7 @@ class FallbackNodeProvider implements NodeProviderInterface * and returning the first non-empty value found * * @return string System node ID as a hexadecimal string + * @throws \Exception */ public function getNode() { diff --git a/src/Provider/Node/RandomNodeProvider.php b/src/Provider/Node/RandomNodeProvider.php index 1018554..76c570d 100644 --- a/src/Provider/Node/RandomNodeProvider.php +++ b/src/Provider/Node/RandomNodeProvider.php @@ -28,6 +28,7 @@ class RandomNodeProvider implements NodeProviderInterface * Returns the system node ID * * @return string System node ID as a hexadecimal string + * @throws \Exception if it was not possible to gather sufficient entropy */ public function getNode() { diff --git a/src/Provider/NodeProviderInterface.php b/src/Provider/NodeProviderInterface.php index 864e840..14f747b 100644 --- a/src/Provider/NodeProviderInterface.php +++ b/src/Provider/NodeProviderInterface.php @@ -24,6 +24,7 @@ interface NodeProviderInterface * Returns the system node ID * * @return string System node ID as a hexadecimal string + * @throws \Exception if it was not possible to gather sufficient entropy */ public function getNode(); } diff --git a/src/Uuid.php b/src/Uuid.php index bccc7f7..45f9fa4 100644 --- a/src/Uuid.php +++ b/src/Uuid.php @@ -229,6 +229,7 @@ class Uuid implements UuidInterface * * @param string $serialized * @link http://php.net/manual/en/class.serializable.php + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function unserialize($serialized) { @@ -332,6 +333,9 @@ class Uuid implements UuidInterface return $this->converter; } + /** + * @inheritdoc + */ public function getDateTime() { if ($this->getVersion() != 1) { @@ -384,6 +388,9 @@ class Uuid implements UuidInterface return str_replace('-', '', $this->toString()); } + /** + * @inheritdoc + */ public function getInteger() { return $this->converter->fromHex($this->getHex()); @@ -393,6 +400,7 @@ class Uuid implements UuidInterface * Returns the least significant 64 bits of this UUID's 128 bit value. * * @return mixed Converted representation of the unsigned 64-bit integer value + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present */ public function getLeastSignificantBits() { @@ -413,6 +421,7 @@ class Uuid implements UuidInterface * Returns the most significant 64 bits of this UUID's 128 bit value. * * @return mixed Converted representation of the unsigned 64-bit integer value + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present */ public function getMostSignificantBits() { @@ -534,6 +543,9 @@ class Uuid implements UuidInterface return hexdec($this->getTimestampHex()); } + /** + * @inheritdoc + */ public function getTimestampHex() { if ($this->getVersion() != 1) { @@ -612,6 +624,8 @@ class Uuid implements UuidInterface * * @param string $bytes * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException + * @throws \InvalidArgumentException */ public static function fromBytes($bytes) { @@ -623,6 +637,7 @@ class Uuid implements UuidInterface * * @param string $name A string that specifies a UUID * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public static function fromString($name) { @@ -634,6 +649,8 @@ class Uuid implements UuidInterface * * @param string $integer String representation of 128-bit integer * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public static function fromInteger($integer) { @@ -670,6 +687,10 @@ class Uuid implements UuidInterface * could arise when the clock is set backwards in time or if the node ID * changes. * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system and + * `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception if it was not possible to gather sufficient entropy */ public static function uuid1($node = null, $clockSeq = null) { @@ -683,6 +704,7 @@ class Uuid implements UuidInterface * @param string $ns The UUID namespace in which to create the named UUID * @param string $name The name to create a UUID for * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public static function uuid3($ns, $name) { @@ -693,6 +715,9 @@ class Uuid implements UuidInterface * Generate a version 4 (random) UUID. * * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception */ public static function uuid4() { @@ -706,6 +731,7 @@ class Uuid implements UuidInterface * @param string $ns The UUID namespace in which to create the named UUID * @param string $name The name to create a UUID for * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public static function uuid5($ns, $name) { diff --git a/src/UuidFactory.php b/src/UuidFactory.php index 77d2383..99644d4 100644 --- a/src/UuidFactory.php +++ b/src/UuidFactory.php @@ -180,17 +180,26 @@ class UuidFactory implements UuidFactoryInterface $this->uuidBuilder = $builder; } + /** + * @inheritdoc + */ public function fromBytes($bytes) { return $this->codec->decodeBytes($bytes); } + /** + * @inheritdoc + */ public function fromString($uuid) { $uuid = strtolower($uuid); return $this->codec->decode($uuid); } + /** + * @inheritdoc + */ public function fromInteger($integer) { $hex = $this->numberConverter->toHex($integer); @@ -199,6 +208,9 @@ class UuidFactory implements UuidFactoryInterface return $this->fromString($hex); } + /** + * @inheritdoc + */ public function uuid1($node = null, $clockSeq = null) { $bytes = $this->timeGenerator->generate($node, $clockSeq); @@ -207,11 +219,17 @@ class UuidFactory implements UuidFactoryInterface return $this->uuidFromHashedName($hex, 1); } + /** + * @inheritdoc + */ public function uuid3($ns, $name) { return $this->uuidFromNsAndName($ns, $name, 3, 'md5'); } + /** + * @inheritdoc + */ public function uuid4() { $bytes = $this->randomGenerator->generate(16); @@ -224,6 +242,9 @@ class UuidFactory implements UuidFactoryInterface return $this->uuidFromHashedName($hex, 4); } + /** + * @inheritdoc + */ public function uuid5($ns, $name) { return $this->uuidFromNsAndName($ns, $name, 5, 'sha1'); @@ -253,6 +274,7 @@ class UuidFactory implements UuidFactoryInterface * @param string $hashFunction The hash function to use when hashing together * the namespace and name * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ protected function uuidFromNsAndName($ns, $name, $version, $hashFunction) { diff --git a/src/UuidFactoryInterface.php b/src/UuidFactoryInterface.php index 6895ff2..a228f5b 100644 --- a/src/UuidFactoryInterface.php +++ b/src/UuidFactoryInterface.php @@ -23,12 +23,16 @@ interface UuidFactoryInterface /** * Generate a version 1 UUID from a host ID, sequence number, and the current time. * - * @param int|string $node A 48-bit number representing the hardware address + * @param int|string|null $node A 48-bit number representing the hardware address * This number may be represented as an integer or a hexadecimal string. - * @param int $clockSeq A 14-bit number used to help avoid duplicates that + * @param int|null $clockSeq A 14-bit number used to help avoid duplicates that * could arise when the clock is set backwards in time or if the node ID * changes. * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if called on a 32-bit system and + * `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception if it was not possible to gather sufficient entropy */ public function uuid1($node = null, $clockSeq = null); @@ -39,6 +43,7 @@ interface UuidFactoryInterface * @param string $ns The UUID namespace in which to create the named UUID * @param string $name The name to create a UUID for * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function uuid3($ns, $name); @@ -46,6 +51,9 @@ interface UuidFactoryInterface * Generate a version 4 (random) UUID. * * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present + * @throws \InvalidArgumentException + * @throws \Exception */ public function uuid4(); @@ -56,6 +64,7 @@ interface UuidFactoryInterface * @param string $ns The UUID namespace in which to create the named UUID * @param string $name The name to create a UUID for * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function uuid5($ns, $name); @@ -64,6 +73,8 @@ interface UuidFactoryInterface * * @param string $bytes A 16-byte string representation of a UUID * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException + * @throws \InvalidArgumentException if string has not 16 characters */ public function fromBytes($bytes); @@ -72,6 +83,7 @@ interface UuidFactoryInterface * * @param string $uuid A string representation of a UUID * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function fromString($uuid); @@ -84,6 +96,8 @@ interface UuidFactoryInterface * @param mixed $integer The integer to use when creating a `Uuid` from an * integer; may be of any type understood by the configured number converter * @return UuidInterface + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present + * @throws \Ramsey\Uuid\Exception\InvalidUuidStringException */ public function fromInteger($integer); } diff --git a/src/UuidInterface.php b/src/UuidInterface.php index 792c32a..ea3a46f 100644 --- a/src/UuidInterface.php +++ b/src/UuidInterface.php @@ -123,6 +123,8 @@ interface UuidInterface extends \JsonSerializable, \Serializable * * @return \DateTime A PHP DateTime representation of the date * @throws UnsupportedOperationException If this UUID is not a version 1 UUID + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if called in a 32-bit system and + * `Moontoast\Math\BigNumber` is not present */ public function getDateTime(); @@ -131,6 +133,7 @@ interface UuidInterface extends \JsonSerializable, \Serializable * representation. * * @return mixed Converted representation of the unsigned 128-bit integer value + * @throws \Ramsey\Uuid\Exception\UnsatisfiedDependencyException if `Moontoast\Math\BigNumber` is not present */ public function getInteger();