Use internal exceptions

Fixes #254

CHANGELOG.md

@@ -18,6 +18,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 * Allow use of the [GMP extension](https://www.php.net/gmp) for number and time
   conversion through the addition of `Converter\Number\GmpConverter` and
   `Converter\Time\GmpTimeConverter`.
+* Add an internal `InvalidArgumentException` that descends from the built-in
+  PHP `\InvalidArgumentException`. All places that used to throw
+  `\InvalidArgumentException` now throw `Ramsey\Uuid\Exception\InvalidArgumentException`.
+  This should not cause any BC breaks, however.
+* Add an internal `DateTimeException` that descends from the built-in PHP
+  `\RuntimeException`. `Uuid::getDateTime()` and `DegradedUuid::getDateTime()`
+  may throw this exception if `\DateTimeImmutable` throws an error or exception.
+* Add `RandomSourceException` that descends from the built-in PHP
+  `\RuntimeException`. DefaultTimeGenerator, RandomBytesGenerator, and
+  RandomNodeProvider may throw this exception if `random_bytes()` or
+  `random_int()` throw an error or exception.
 
 ### Changed
 
@@ -37,6 +48,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   * `NumberConverterInterface::toHex(string $number): string`
   * `TimeConverterInterface::calculateTime(string $seconds, string $microSeconds): array`
   * `TimeConverterInterface::convertTime(string $timestamp): string`
+* `UnsatisfiedDependencyException` and `UnsupportedOperationException` are now
+  descended from `\LogicException`. Previously, they descended from `\RuntimeException`.
 
 ### Deprecated
 

src/Codec/GuidStringCodec.php

@@ -14,7 +14,7 @@
 
 namespace Ramsey\Uuid\Codec;
 
-use InvalidArgumentException;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\InvalidUuidStringException;
 use Ramsey\Uuid\UuidInterface;
 

src/Codec/OrderedTimeCodec.php

@@ -14,7 +14,7 @@
 
 namespace Ramsey\Uuid\Codec;
 
-use InvalidArgumentException;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\UuidInterface;
 
 /**

src/Codec/StringCodec.php

@@ -14,8 +14,8 @@
 
 namespace Ramsey\Uuid\Codec;
 
-use InvalidArgumentException;
 use Ramsey\Uuid\Builder\UuidBuilderInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\InvalidUuidStringException;
 use Ramsey\Uuid\Uuid;
 use Ramsey\Uuid\UuidInterface;

src/Codec/TimestampFirstCombCodec.php

@@ -14,7 +14,7 @@
 
 namespace Ramsey\Uuid\Codec;
 
-use InvalidArgumentException;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\InvalidUuidStringException;
 use Ramsey\Uuid\UuidInterface;
 

src/Converter/Number/BigNumberConverter.php

@@ -14,11 +14,11 @@
 
 namespace Ramsey\Uuid\Converter\Number;
 
-use InvalidArgumentException;
 use Moontoast\Math\BigNumber;
 use Ramsey\Uuid\Converter\DependencyCheckTrait;
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 use Ramsey\Uuid\Converter\NumberStringTrait;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 
 /**

src/Converter/Number/GmpConverter.php

@@ -14,10 +14,10 @@
 
 namespace Ramsey\Uuid\Converter\Number;
 
-use InvalidArgumentException;
 use Ramsey\Uuid\Converter\DependencyCheckTrait;
 use Ramsey\Uuid\Converter\NumberConverterInterface;
 use Ramsey\Uuid\Converter\NumberStringTrait;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 
 /**

src/Converter/NumberStringTrait.php

@@ -14,7 +14,7 @@
 
 namespace Ramsey\Uuid\Converter;
 
-use InvalidArgumentException;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 
 /**
  * Provides shared functionality to check the values of string numbers for

src/Converter/Time/BigNumberTimeConverter.php

@@ -14,11 +14,11 @@
 
 namespace Ramsey\Uuid\Converter\Time;
 
-use InvalidArgumentException;
 use Moontoast\Math\BigNumber;
 use Ramsey\Uuid\Converter\DependencyCheckTrait;
 use Ramsey\Uuid\Converter\NumberStringTrait;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 
 /**

src/Converter/Time/GmpTimeConverter.php

@@ -14,10 +14,10 @@
 
 namespace Ramsey\Uuid\Converter\Time;
 
-use InvalidArgumentException;
 use Ramsey\Uuid\Converter\DependencyCheckTrait;
 use Ramsey\Uuid\Converter\NumberStringTrait;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 
 /**

src/Converter/Time/PhpTimeConverter.php

@@ -14,10 +14,10 @@
 
 namespace Ramsey\Uuid\Converter\Time;
 
-use InvalidArgumentException;
 use Ramsey\Uuid\Converter\DependencyCheckTrait;
 use Ramsey\Uuid\Converter\NumberStringTrait;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 
 /**

src/DegradedUuid.php

@@ -16,6 +16,7 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use Ramsey\Uuid\Exception\DateTimeException;
 use Ramsey\Uuid\Exception\UnsatisfiedDependencyException;
 use Ramsey\Uuid\Exception\UnsupportedOperationException;
 
@@ -31,6 +32,8 @@ class DegradedUuid extends Uuid
     /**
      * @return DateTimeImmutable An immutable instance of DateTimeInterface
      *
+     * @throws DateTimeException if DateTime throws an exception/error
+     * @throws UnsatisfiedDependencyException if large integer support is not available
      * @throws UnsupportedOperationException if UUID is not time-based
      */
     public function getDateTime(): DateTimeInterface
@@ -42,11 +45,19 @@ public function getDateTime(): DateTimeInterface
         $time = $this->numberConverter->fromHex($this->getTimestampHex());
         $unixTime = $this->timeConverter->convertTime($time);
 
-        return new DateTimeImmutable("@{$unixTime}");
+        try {
+            return new DateTimeImmutable("@{$unixTime}");
+        } catch (\Throwable $exception) {
+            throw new DateTimeException(
+                $exception->getMessage(),
+                $exception->getCode(),
+                $exception
+            );
+        }
     }
 
     /**
-     * @throws UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsatisfiedDependencyException if large integer support is not available
      *
      * @inheritDoc
      */
@@ -60,7 +71,7 @@ public function getFields(): array
     }
 
     /**
-     * @throws UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsatisfiedDependencyException if large integer support is not available
      */
     public function getNode(): int
     {
@@ -73,7 +84,7 @@ public function getNode(): int
     }
 
     /**
-     * @throws UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsatisfiedDependencyException if large integer support is not available
      */
     public function getTimeLow(): int
     {
@@ -86,7 +97,7 @@ public function getTimeLow(): int
     }
 
     /**
-     * @throws UnsatisfiedDependencyException if called on a 32-bit system
+     * @throws UnsatisfiedDependencyException if large integer support is not available
      * @throws UnsupportedOperationException if UUID is not time-based
      */
     public function getTimestamp(): int

src/Exception/DateTimeException.php

@@ -0,0 +1,24 @@
+<?php
+
+/**
+ * This file is part of the ramsey/uuid library
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright Copyright (c) Ben Ramsey <ben@benramsey.com>
+ * @license http://opensource.org/licenses/MIT MIT
+ */
+
+declare(strict_types=1);
+
+namespace Ramsey\Uuid\Exception;
+
+use RuntimeException as PhpRuntimeException;
+
+/**
+ * Thrown to indicate that the PHP DateTime extension encountered an exception/error
+ */
+class DateTimeException extends PhpRuntimeException
+{
+}

src/Exception/InvalidArgumentException.php

@@ -0,0 +1,24 @@
+<?php
+
+/**
+ * This file is part of the ramsey/uuid library
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright Copyright (c) Ben Ramsey <ben@benramsey.com>
+ * @license http://opensource.org/licenses/MIT MIT
+ */
+
+declare(strict_types=1);
+
+namespace Ramsey\Uuid\Exception;
+
+use InvalidArgumentException as PhpInvalidArgumentException;
+
+/**
+ * Thrown to indicate that the argument received is not valid
+ */
+class InvalidArgumentException extends PhpInvalidArgumentException
+{
+}

src/Exception/InvalidUuidStringException.php

@@ -14,10 +14,11 @@
 
 namespace Ramsey\Uuid\Exception;
 
-use InvalidArgumentException;
-
 /**
- * Thrown to indicate that the parsed UUID string is invalid.
+ * Thrown to indicate that the string received is not a valid UUID
+ *
+ * The InvalidArgumentException that this extends is the ramsey/uuid version
+ * of this exception. It exists in the same namespace as this class.
  */
 class InvalidUuidStringException extends InvalidArgumentException
 {

src/Exception/RandomSourceException.php

@@ -0,0 +1,27 @@
+<?php
+
+/**
+ * This file is part of the ramsey/uuid library
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @copyright Copyright (c) Ben Ramsey <ben@benramsey.com>
+ * @license http://opensource.org/licenses/MIT MIT
+ */
+
+declare(strict_types=1);
+
+namespace Ramsey\Uuid\Exception;
+
+use RuntimeException as PhpRuntimeException;
+
+/**
+ * Thrown to indicate that the source of random data encountered an error
+ *
+ * This exception is used mostly to indicate that random_bytes() or random_int()
+ * threw an exception. However, it may be used for other sources of random data.
+ */
+class RandomSourceException extends PhpRuntimeException
+{
+}

src/Exception/UnsatisfiedDependencyException.php

@@ -14,12 +14,12 @@
 
 namespace Ramsey\Uuid\Exception;
 
-use RuntimeException;
+use LogicException as PhpLogicException;
 
 /**
  * Thrown to indicate that the requested operation has dependencies that have not
- * been satisfied.
+ * been satisfied
  */
-class UnsatisfiedDependencyException extends RuntimeException
+class UnsatisfiedDependencyException extends PhpLogicException
 {
 }

src/Exception/UnsupportedOperationException.php

@@ -14,11 +14,11 @@
 
 namespace Ramsey\Uuid\Exception;
 
-use RuntimeException;
+use LogicException as PhpLogicException;
 
 /**
- * Thrown to indicate that the requested operation is not supported.
+ * Thrown to indicate that the requested operation is not supported
  */
-class UnsupportedOperationException extends RuntimeException
+class UnsupportedOperationException extends PhpLogicException
 {
 }

src/Generator/CombGenerator.php

@@ -14,8 +14,8 @@
 
 namespace Ramsey\Uuid\Generator;
 
-use InvalidArgumentException;
 use Ramsey\Uuid\Converter\NumberConverterInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
 
 /**
  * CombGenerator generates COMBs (combined UUID/timestamp)

src/Generator/DefaultTimeGenerator.php

@@ -14,9 +14,10 @@
 
 namespace Ramsey\Uuid\Generator;
 
-use InvalidArgumentException;
 use Ramsey\Uuid\BinaryUtils;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
+use Ramsey\Uuid\Exception\RandomSourceException;
 use Ramsey\Uuid\Provider\NodeProviderInterface;
 use Ramsey\Uuid\Provider\TimeProviderInterface;
 
@@ -53,6 +54,7 @@ public function __construct(
 
     /**
      * @throws InvalidArgumentException if the parameters contain invalid values
+     * @throws RandomSourceException if random_int() throws an exception/error
      *
      * @inheritDoc
      */
@@ -61,8 +63,16 @@ public function generate($node = null, ?int $clockSeq = null): string
         $node = $this->getValidNode($node);
 
         if ($clockSeq === null) {
-            // This does not use "stable storage"; see RFC 4122, Section 4.2.1.1.
-            $clockSeq = random_int(0, 0x3fff);
+            try {
+                // This does not use "stable storage"; see RFC 4122, Section 4.2.1.1.
+                $clockSeq = random_int(0, 0x3fff);
+            } catch (\Throwable $exception) {
+                throw new RandomSourceException(
+                    $exception->getMessage(),
+                    $exception->getCode(),
+                    $exception
+                );
+            }
         }
 
         // Create a 60-bit time value as a count of 100-nanosecond intervals