Support version 6 UUIDs

See the following:

* https://github.com/uuid6/uuid6-ietf-draft
* http://gh.peabody.io/uuidv6/

src/Nonstandard/UuidV6.php

@@ -0,0 +1,130 @@
+<?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\Nonstandard;
+
+use DateTimeImmutable;
+use DateTimeInterface;
+use Ramsey\Uuid\Codec\CodecInterface;
+use Ramsey\Uuid\Converter\NumberConverterInterface;
+use Ramsey\Uuid\Converter\TimeConverterInterface;
+use Ramsey\Uuid\Exception\DateTimeException;
+use Ramsey\Uuid\Exception\InvalidArgumentException;
+use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
+use Ramsey\Uuid\Rfc4122\UuidInterface;
+use Ramsey\Uuid\Rfc4122\UuidV1;
+use Ramsey\Uuid\Uuid;
+use Throwable;
+
+use function str_pad;
+
+use const STR_PAD_LEFT;
+
+/**
+ * Ordered-time, or version 6, UUIDs include timestamp, clock sequence, and node
+ * values that are combined into a 128-bit unsigned integer
+ *
+ * @link https://github.com/uuid6/uuid6-ietf-draft UUID version 6 IETF draft
+ * @link http://gh.peabody.io/uuidv6/ "Version 6" UUIDs
+ *
+ * @psalm-immutable
+ */
+final class UuidV6 extends Uuid implements UuidInterface
+{
+    /**
+     * Creates a version 6 (time-based) UUID
+     *
+     * @param Rfc4122FieldsInterface $fields The fields from which to construct a UUID
+     * @param NumberConverterInterface $numberConverter The number converter to use
+     *     for converting hex values to/from integers
+     * @param CodecInterface $codec The codec to use when encoding or decoding
+     *     UUID strings
+     * @param TimeConverterInterface $timeConverter The time converter to use
+     *     for converting timestamps extracted from a UUID to unix timestamps
+     */
+    public function __construct(
+        Rfc4122FieldsInterface $fields,
+        NumberConverterInterface $numberConverter,
+        CodecInterface $codec,
+        TimeConverterInterface $timeConverter
+    ) {
+        if ($fields->getVersion() !== Uuid::UUID_TYPE_PEABODY) {
+            throw new InvalidArgumentException(
+                'Fields used to create a UuidV6 must represent a '
+                . 'version 6 (ordered-time) UUID'
+            );
+        }
+
+        parent::__construct($fields, $numberConverter, $codec, $timeConverter);
+    }
+
+    /**
+     * Returns a DateTimeInterface object representing the timestamp associated
+     * with the UUID
+     *
+     * @return DateTimeImmutable A PHP DateTimeImmutable instance representing
+     *     the timestamp of a version 6 UUID
+     */
+    public function getDateTime(): DateTimeInterface
+    {
+        $time = $this->timeConverter->convertTime($this->fields->getTimestamp());
+
+        try {
+            return new DateTimeImmutable(
+                '@'
+                . $time->getSeconds()->toString()
+                . '.'
+                . str_pad($time->getMicroSeconds()->toString(), 6, '0', STR_PAD_LEFT)
+            );
+        } catch (Throwable $e) {
+            throw new DateTimeException($e->getMessage(), (int) $e->getCode(), $e);
+        }
+    }
+
+    /**
+     * Converts this UUID into an instance of a version 1 UUID
+     */
+    public function toUuidV1(): UuidV1
+    {
+        $hex = $this->getHex()->toString();
+        $hex = substr($hex, 7, 5)
+            . substr($hex, 13, 3)
+            . substr($hex, 3, 4)
+            . '1' . substr($hex, 0, 3)
+            . substr($hex, 16);
+
+        /** @var UuidV1 $uuid */
+        $uuid = Uuid::fromBytes((string) hex2bin($hex));
+
+        return $uuid;
+    }
+
+    /**
+     * Converts a version 1 UUID into an instance of a version 6 UUID
+     */
+    public static function fromUuidV1(UuidV1 $uuidV1): UuidV6
+    {
+        $hex = $uuidV1->getHex()->toString();
+        $hex = substr($hex, 13, 3)
+            . substr($hex, 8, 4)
+            . substr($hex, 0, 5)
+            . '6' . substr($hex, 5, 3)
+            . substr($hex, 16);
+
+        /** @var UuidV6 $uuid */
+        $uuid = Uuid::fromBytes((string) hex2bin($hex));
+
+        return $uuid;
+    }
+}

src/Rfc4122/Fields.php

@@ -125,12 +125,21 @@ final class Fields implements FieldsInterface
 
     public function getTimestamp(): Hexadecimal
     {
-        return new Hexadecimal(sprintf(
+        $timestamp = sprintf(
             '%03x%04s%08s',
             hexdec($this->getTimeHiAndVersion()->toString()) & 0x0fff,
             $this->getTimeMid()->toString(),
             $this->getTimeLow()->toString()
-        ));
+        );
+
+        // Put the timestamp into the correct order, if this is a v6 UUID.
+        if ($this->getVersion() === Uuid::UUID_TYPE_PEABODY) {
+            $timestamp = substr($timestamp, 7)
+                . substr($timestamp, 3, 4)
+                . substr($timestamp, 0, 3);
+        }
+
+        return new Hexadecimal($timestamp);
     }
 
     public function getVersion(): ?int

src/Rfc4122/UuidBuilder.php

@@ -20,6 +20,7 @@ use Ramsey\Uuid\Converter\NumberConverterInterface;
 use Ramsey\Uuid\Converter\TimeConverterInterface;
 use Ramsey\Uuid\Exception\UnableToBuildUuidException;
 use Ramsey\Uuid\Exception\UnsupportedOperationException;
+use Ramsey\Uuid\Nonstandard\UuidV6;
 use Ramsey\Uuid\Rfc4122\UuidInterface as Rfc4122UuidInterface;
 use Ramsey\Uuid\UuidInterface;
 use Throwable;
@@ -85,6 +86,8 @@ class UuidBuilder implements UuidBuilderInterface
                     return new UuidV4($fields, $this->numberConverter, $codec, $this->timeConverter);
                 case 5:
                     return new UuidV5($fields, $this->numberConverter, $codec, $this->timeConverter);
+                case 6:
+                    return new UuidV6($fields, $this->numberConverter, $codec, $this->timeConverter);
             }
 
             throw new UnsupportedOperationException(

src/Rfc4122/VersionTrait.php

@@ -46,6 +46,7 @@ trait VersionTrait
             case 3:
             case 4:
             case 5:
+            case 6:
                 return true;
         }
 

src/Uuid.php

@@ -156,6 +156,17 @@ class Uuid implements UuidInterface
      */
     public const UUID_TYPE_HASH_SHA1 = 5;
 
+    /**
+     * Version 6 (ordered-time) UUID
+     *
+     * This is named `UUID_TYPE_PEABODY`, since the specification is still in
+     * draft form, and the primary author/editor's name is Brad Peabody.
+     *
+     * @link https://github.com/uuid6/uuid6-ietf-draft UUID version 6 IETF draft
+     * @link http://gh.peabody.io/uuidv6/ "Version 6" UUIDs
+     */
+    public const UUID_TYPE_PEABODY = 6;
+
     /**
      * DCE Security principal domain
      *
@@ -523,4 +534,22 @@ class Uuid implements UuidInterface
     {
         return self::getFactory()->uuid5($ns, $name);
     }
+
+    /**
+     * Returns a version 6 (ordered-time) UUID from a host ID, sequence number,
+     * and the current time
+     *
+     * @param int|string $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
+     *     could arise when the clock is set backwards in time or if the node ID
+     *     changes
+     *
+     * @return UuidInterface A UuidInterface instance that represents a
+     *     version 6 UUID
+     */
+    public static function uuid6($node = null, ?int $clockSeq = null): UuidInterface
+    {
+        return self::getFactory()->uuid6($node, $clockSeq);
+    }
 }

src/UuidFactory.php

@@ -351,6 +351,27 @@ class UuidFactory implements UuidFactoryInterface
         return $this->uuidFromNsAndName($ns, $name, 5, 'sha1');
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function uuid6($node = null, ?int $clockSeq = null): UuidInterface
+    {
+        $bytes = $this->timeGenerator->generate($node, $clockSeq);
+
+        // Rearrange the bytes, according to the UUID version 6 specification.
+        $v6 = $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5]
+            . $bytes[0] . $bytes[1] . $bytes[2] . $bytes[3];
+        $v6 = bin2hex($v6);
+
+        // Drop the first four bits, while adding an empty four bits for the
+        // version field. This allows us to reconstruct the correct time from
+        // the bytes of this UUID.
+        $v6Bytes = hex2bin(substr($v6, 1, 12) . '0' . substr($v6, -3));
+        $v6Bytes .= substr($bytes, 8);
+
+        return $this->uuidFromBytesAndVersion($v6Bytes, 6);
+    }
+
     /**
      * Returns a Uuid created from the provided byte string
      *

src/UuidFactoryInterface.php

@@ -105,6 +105,21 @@ interface UuidFactoryInterface
      */
     public function uuid5($ns, string $name): UuidInterface;
 
+    /**
+     * Returns a version 6 (ordered-time) UUID from a host ID, sequence number,
+     * and the current time
+     *
+     * @param int|string $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
+     *     could arise when the clock is set backwards in time or if the node ID
+     *     changes
+     *
+     * @return UuidInterface A UuidInterface instance that represents a
+     *     version 6 UUID
+     */
+    public function uuid6($node = null, ?int $clockSeq = null): UuidInterface;
+
     /**
      * Creates a UUID from a byte string
      *