Skip to main content
Drupal API
User account menu
  • Log in

Breadcrumb

  1. Drupal Core 11.1.x
  2. OrderedTimeCodec.php

class OrderedTimeCodec

OrderedTimeCodec encodes and decodes a UUID, optimizing the byte order for more efficient storage

For binary representations of version 1 UUID, this codec may be used to reorganize the time fields, making the UUID closer to sequential when storing the bytes. According to Percona, this optimization can improve database INSERTs and SELECTs using the UUID column as a key.

The string representation of the UUID will remain unchanged. Only the binary representation is reordered.

**PLEASE NOTE:** Binary representations of UUIDs encoded with this codec must be decoded with this codec. Decoding using another codec can result in malformed UUIDs.

@link https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/ Storing UUID Values in MySQL

@psalm-immutable

Hierarchy

  • class \Ramsey\Uuid\Codec\StringCodec implements \Ramsey\Uuid\Codec\CodecInterface
    • class \Ramsey\Uuid\Codec\OrderedTimeCodec extends \Ramsey\Uuid\Codec\StringCodec

Expanded class hierarchy of OrderedTimeCodec

1 string reference to 'OrderedTimeCodec'
OrderedTimeCodec::decodeBytes in vendor/ramsey/uuid/src/Codec/OrderedTimeCodec.php
Returns a UuidInterface derived from an ordered-time binary string representation

File

vendor/ramsey/uuid/src/Codec/OrderedTimeCodec.php, line 46

Namespace

Ramsey\Uuid\Codec
View source
class OrderedTimeCodec extends StringCodec {
    
    /**
     * Returns a binary string representation of a UUID, with the timestamp
     * fields rearranged for optimized storage
     *
     * @inheritDoc
     * @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 {
        if (!$uuid->getFields() instanceof Rfc4122FieldsInterface || $uuid->getFields()
            ->getVersion() !== Uuid::UUID_TYPE_TIME) {
            throw new InvalidArgumentException('Expected RFC 4122 version 1 (time-based) UUID');
        }
        $bytes = $uuid->getFields()
            ->getBytes();
        
        /** @phpstan-ignore-next-line PHPStan complains that this is not a non-empty-string. */
        return $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5] . $bytes[0] . $bytes[1] . $bytes[2] . $bytes[3] . substr($bytes, 8);
    }
    
    /**
     * Returns a UuidInterface derived from an ordered-time binary string
     * representation
     *
     * @throws InvalidArgumentException if $bytes is an invalid length
     *
     * @inheritDoc
     */
    public function decodeBytes(string $bytes) : UuidInterface {
        if (strlen($bytes) !== 16) {
            throw new InvalidArgumentException('$bytes string should contain 16 characters.');
        }
        // Rearrange the bytes to their original order.
        $rearrangedBytes = $bytes[4] . $bytes[5] . $bytes[6] . $bytes[7] . $bytes[2] . $bytes[3] . $bytes[0] . $bytes[1] . substr($bytes, 8);
        $uuid = parent::decodeBytes($rearrangedBytes);
        if (!$uuid->getFields() instanceof Rfc4122FieldsInterface || $uuid->getFields()
            ->getVersion() !== Uuid::UUID_TYPE_TIME) {
            throw new UnsupportedOperationException('Attempting to decode a non-time-based UUID using ' . 'OrderedTimeCodec');
        }
        return $uuid;
    }

}

Members

Title Sort descending Modifiers Object type Summary Overriden Title Overrides
OrderedTimeCodec::decodeBytes public function Returns a UuidInterface derived from an ordered-time binary string
representation
Overrides StringCodec::decodeBytes
OrderedTimeCodec::encodeBinary public function Returns a binary string representation of a UUID, with the timestamp
fields rearranged for optimized storage
Overrides StringCodec::encodeBinary
StringCodec::decode public function @inheritDoc Overrides CodecInterface::decode 2
StringCodec::encode public function Returns a hexadecimal string representation of a UuidInterface Overrides CodecInterface::encode 2
StringCodec::getBuilder protected function Returns the UUID builder
StringCodec::getBytes protected function Returns a byte string of the UUID
StringCodec::__construct public function Constructs a StringCodec
RSS feed
Powered by Drupal