Merge bf4d79d into 6890241

ramsey · Jan 2, 2020 · b086971 · b086971
2 parents 6890241 + bf4d79d
commit b086971
Show file tree

Hide file tree

Showing 51 changed files with 1,499 additions and 237 deletions.
diff --git a/phpstan-tests.neon b/phpstan-tests.neon
@@ -20,3 +20,7 @@ parameters:
             message: "#^Function uuid_parse\\(\\) has parameter \\$uuid with no typehint specified\\.$#"
             count: 1
             path: tests/phpstan-bootstrap.php
+        -
+            message: "#^Unreachable statement - code above always terminates\\.$#"
+            count: 3
+            path: tests/UuidTest.php
diff --git a/src/BinaryUtils.php b/src/BinaryUtils.php
@@ -30,6 +30,8 @@ class BinaryUtils
      *     before the RFC 4122 variant is applied
      *
      * @return int The high field of the clock sequence multiplexed with the variant
+     *
+     * @psalm-pure
      */
     public static function applyVariant(int $clockSeqHi): int
     {
@@ -50,6 +52,8 @@ public static function applyVariant(int $clockSeqHi): int
      * @param int $version The RFC 4122 version to apply to the `time_hi` field
      *
      * @return int The high field of the timestamp multiplexed with the version number
+     *
+     * @psalm-pure
      */
     public static function applyVersion(string $timeHi, int $version): int
     {

diff --git a/src/Builder/DefaultUuidBuilder.php b/src/Builder/DefaultUuidBuilder.php
@@ -22,6 +22,8 @@
 
 /**
  * DefaultUuidBuilder builds instances of Uuid
+ *
+ * @psalm-immutable
  */
 class DefaultUuidBuilder implements UuidBuilderInterface
 {

diff --git a/src/Builder/DegradedUuidBuilder.php b/src/Builder/DegradedUuidBuilder.php
@@ -22,6 +22,8 @@
 
 /**
  * DegradedUuidBuilder builds instances of DegradedUuid
+ *
+ * @psalm-immutable
  */
 class DegradedUuidBuilder implements UuidBuilderInterface
 {
@@ -36,8 +38,6 @@ class DegradedUuidBuilder implements UuidBuilderInterface
     private $timeConverter;
 
     /**
-     * Constructs the DegradedUuidBuilder
-     *
      * @param NumberConverterInterface $numberConverter The number converter to
      *     use when constructing the DegradedUuid
      * @param TimeConverterInterface $timeConverter The time converter to use

diff --git a/src/Builder/GuidBuilder.php b/src/Builder/GuidBuilder.php
@@ -0,0 +1,72 @@
+<?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\Builder;
+
+use Ramsey\Uuid\Codec\CodecInterface;
+use Ramsey\Uuid\Converter\NumberConverterInterface;
+use Ramsey\Uuid\Converter\TimeConverterInterface;
+use Ramsey\Uuid\Guid;
+use Ramsey\Uuid\UuidInterface;
+
+/**
+ * GuidBuilder builds instances of Guid
+ *
+ * @psalm-immutable
+ */
+class GuidBuilder implements UuidBuilderInterface
+{
+    /**
+     * @var NumberConverterInterface
+     */
+    private $numberConverter;
+
+    /**
+     * @var TimeConverterInterface
+     */
+    private $timeConverter;
+
+    /**
+     * @param NumberConverterInterface $numberConverter The number converter to
+     *     use when constructing the Guid
+     * @param TimeConverterInterface $timeConverter The time converter to use
+     *     for converting timestamps extracted from a UUID to Unix timestamps
+     */
+    public function __construct(
+        NumberConverterInterface $numberConverter,
+        TimeConverterInterface $timeConverter
+    ) {
+        $this->numberConverter = $numberConverter;
+        $this->timeConverter = $timeConverter;
+    }
+
+    /**
+     * Builds and returns a Guid
+     *
+     * @param CodecInterface $codec The codec to use for building this Guid instance
+     * @param string[] $fields An array of fields from which to construct a Guid instance;
+     *     see {@see \Ramsey\Uuid\UuidInterface::getFieldsHex()} for array structure.
+     *
+     * @return Guid The GuidBuilder returns an instance of Ramsey\Uuid\Guid
+     */
+    public function build(CodecInterface $codec, array $fields): UuidInterface
+    {
+        return new Guid(
+            $fields,
+            $this->numberConverter,
+            $codec,
+            $this->timeConverter
+        );
+    }
+}
diff --git a/src/Builder/UuidBuilderInterface.php b/src/Builder/UuidBuilderInterface.php
@@ -19,6 +19,8 @@
 
 /**
  * A UUID builder builds instances of UuidInterface
+ *
+ * @psalm-immutable
  */
 interface UuidBuilderInterface
 {

diff --git a/src/Codec/CodecInterface.php b/src/Codec/CodecInterface.php
@@ -28,6 +28,8 @@ interface CodecInterface
      *     string representation
      *
      * @return string Hexadecimal string representation of a UUID
+     *
+     * @psalm-pure
      */
     public function encode(UuidInterface $uuid): string;
 
@@ -38,6 +40,8 @@ public function encode(UuidInterface $uuid): string;
      *     representation
      *
      * @return string Binary string representation of a UUID
+     *
+     * @psalm-pure
      */
     public function encodeBinary(UuidInterface $uuid): string;
 
@@ -49,6 +53,8 @@ public function encodeBinary(UuidInterface $uuid): string;
      *
      * @return UuidInterface An instance of a UUID decoded from a hexadecimal
      *     string representation
+     *
+     * @psalm-pure
      */
     public function decode(string $encodedUuid): UuidInterface;
 
@@ -60,6 +66,8 @@ public function decode(string $encodedUuid): UuidInterface;
      *
      * @return UuidInterface An instance of a UUID decoded from a binary string
      *     representation
+     *
+     * @psalm-pure
      */
     public function decodeBytes(string $bytes): UuidInterface;
 }
diff --git a/src/Codec/GuidStringCodec.php b/src/Codec/GuidStringCodec.php
@@ -25,36 +25,16 @@
  */
 class GuidStringCodec extends StringCodec
 {
-    public function encode(UuidInterface $uuid): string
-    {
-        $components = array_values($uuid->getFieldsHex());
-
-        // Swap byte-order on the first three fields.
-        $this->swapFields($components);
-
-        return vsprintf(
-            '%08s-%04s-%04s-%02s%02s-%012s',
-            $components
-        );
-    }
-
-    public function encodeBinary(UuidInterface $uuid): string
-    {
-        $components = array_values($uuid->getFieldsHex());
-
-        return (string) hex2bin(implode('', $components));
-    }
-
     /**
      * @throws InvalidUuidStringException
      *
      * @inheritDoc
+     *
+     * @psalm-pure
      */
     public function decode(string $encodedUuid): UuidInterface
     {
-        $components = $this->extractComponents($encodedUuid);
-
-        $this->swapFields($components);
+        $components = $this->swapBytes($this->extractComponents($encodedUuid));
 
         return $this->getBuilder()->build($this, $this->getFields($components));
     }
@@ -63,6 +43,8 @@ public function decode(string $encodedUuid): UuidInterface
      * @throws InvalidArgumentException if $bytes is an invalid length
      *
      * @inheritDoc
+     *
+     * @psalm-pure
      */
     public function decodeBytes(string $bytes): UuidInterface
     {
@@ -71,22 +53,22 @@ public function decodeBytes(string $bytes): UuidInterface
     }
 
     /**
-     * Swap fields to support GUID byte order
+     * @param string[] $fields The fields that comprise this UUID
+     *
+     * @return string[]
      *
-     * @param string[] $components An array of UUID components (the UUID exploded on its dashes)
+     * @psalm-pure
      */
-    private function swapFields(array &$components): void
+    private function swapBytes(array $fields): array
     {
-        $hex = unpack('H*', pack('L', hexdec($components[0])));
-        assert(is_string($hex[1]));
-        $components[0] = $hex[1];
+        $fields = array_values($fields);
 
-        $hex = unpack('H*', pack('S', hexdec($components[1])));
-        assert(is_string($hex[1]));
-        $components[1] = $hex[1];
+        // Swap bytes to support GUID byte order.
+        $bytes = (string) hex2bin(implode('', $fields));
+        $fields[0] = bin2hex($bytes[3] . $bytes[2] . $bytes[1] . $bytes[0]);
+        $fields[1] = bin2hex($bytes[5] . $bytes[4]);
+        $fields[2] = bin2hex($bytes[7] . $bytes[6]);
 
-        $hex = unpack('H*', pack('S', hexdec($components[2])));
-        assert(is_string($hex[1]));
-        $components[2] = $hex[1];
+        return $fields;
     }
 }
diff --git a/src/Codec/OrderedTimeCodec.php b/src/Codec/OrderedTimeCodec.php
@@ -44,6 +44,7 @@ class OrderedTimeCodec extends StringCodec
      * fields rearranged for optimized storage
      *
      * @inheritDoc
+     * @psalm-pure
      */
     public function encodeBinary(UuidInterface $uuid): string
     {
@@ -78,6 +79,8 @@ public function encodeBinary(UuidInterface $uuid): string
      * @throws InvalidArgumentException if $bytes is an invalid length
      *
      * @inheritDoc
+     *
+     * @psalm-pure
      */
     public function decodeBytes(string $bytes): UuidInterface
     {

diff --git a/src/Codec/StringCodec.php b/src/Codec/StringCodec.php
@@ -42,6 +42,9 @@ public function __construct(UuidBuilderInterface $builder)
         $this->builder = $builder;
     }
 
+    /**
+     * @psalm-pure
+     */
     public function encode(UuidInterface $uuid): string
     {
         $fields = array_values($uuid->getFieldsHex());
@@ -52,15 +55,20 @@ public function encode(UuidInterface $uuid): string
         );
     }
 
+    /**
+     * @psalm-pure
+     */
     public function encodeBinary(UuidInterface $uuid): string
     {
-        return (string) hex2bin($uuid->getHex());
+        return $uuid->getBytes();
     }
 
     /**
      * @throws InvalidUuidStringException
      *
      * @inheritDoc
+     *
+     * @psalm-pure
      */
     public function decode(string $encodedUuid): UuidInterface
     {
@@ -74,6 +82,8 @@ public function decode(string $encodedUuid): UuidInterface
      * @throws InvalidArgumentException if $bytes is an invalid length
      *
      * @inheritDoc
+     *
+     * @psalm-pure
      */
     public function decodeBytes(string $bytes): UuidInterface
     {
@@ -85,7 +95,7 @@ public function decodeBytes(string $bytes): UuidInterface
 
         $hexUuid = unpack('H*', $bytes);
 
-        return $this->decode($hexUuid[1]);
+        return $this->decode((string) $hexUuid[1]);
     }
 
     /**
@@ -104,6 +114,8 @@ protected function getBuilder(): UuidBuilderInterface
      * @return string[]
      *
      * @throws InvalidUuidStringException
+     *
+     * @psalm-pure
      */
     protected function extractComponents(string $encodedUuid): array
     {
@@ -146,6 +158,8 @@ protected function extractComponents(string $encodedUuid): array
      *     the fields of an RFC 4122 UUID
      *
      * @return string[]
+     *
+     * @psalm-pure
      */
     protected function getFields(array $components): array
     {