Debian Codegraph @

vendor/ramsey/uuid/src/Codec/OrderedTimeCodec.php

raw
1 <?php
2
3 /**
4 * This file is part of the ramsey/uuid library
5 *
6 * For the full copyright and license information, please view the LICENSE
7 * file that was distributed with this source code.
8 *
9 * @copyright Copyright (c) Ben Ramsey <[email protected]>
10 * @license http://opensource.org/licenses/MIT MIT
11 */
12
13 declare(strict_types=1);
14
15 namespace Ramsey\Uuid\Codec;
16
17 use Ramsey\Uuid\Exception\InvalidArgumentException;
18 use Ramsey\Uuid\Exception\UnsupportedOperationException;
19 use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;
20 use Ramsey\Uuid\Uuid;
21 use Ramsey\Uuid\UuidInterface;
22
23 use function strlen;
24 use function substr;
25
26 /**
27 * OrderedTimeCodec encodes and decodes a UUID, optimizing the byte order for more efficient storage
28 *
29 * For binary representations of version 1 UUID, this codec may be used to reorganize the time fields, making the UUID
30 * closer to sequential when storing the bytes. According to Percona, this optimization can improve database INSERT and
31 * SELECT statements using the UUID column as a key.
32 *
33 * The string representation of the UUID will remain unchanged. Only the binary representation is reordered.
34 *
35 * PLEASE NOTE: Binary representations of UUIDs encoded with this codec must be decoded with this codec. Decoding using
36 * another codec can result in malformed UUIDs.
37 *
38 * @deprecated Please migrate to {@link https://uuid.ramsey.dev/en/stable/rfc4122/version6.html Version 6, reordered time-based UUIDs}.
39 *
40 * @link https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/ Storing UUID Values in MySQL
41 *
42 * @immutable
43 */
44 class OrderedTimeCodec extends StringCodec
45 {
46 /**
47 * Returns a binary string representation of a UUID, with the timestamp fields rearranged for optimized storage
48 *
49 * @return non-empty-string
50 */
51 public function encodeBinary(UuidInterface $uuid): string
52 {
53 if (
54 /** @phpstan-ignore possiblyImpure.methodCall */
55 !($uuid->getFields() instanceof Rfc4122FieldsInterface)
56 /** @phpstan-ignore possiblyImpure.methodCall */
57 || $uuid->getFields()->getVersion() !== Uuid::UUID_TYPE_TIME
58 ) {
59 throw new InvalidArgumentException('Expected version 1 (time-based) UUID');
60 }
61
62 /** @phpstan-ignore possiblyImpure.methodCall */
63 $bytes = $uuid->getFields()->getBytes();
64
65 return $bytes[6] . $bytes[7] . $bytes[4] . $bytes[5]
66 . $bytes[0] . $bytes[1] . $bytes[2] . $bytes[3]
67 . substr($bytes, 8);
68 }
69
70 /**
71 * Returns a UuidInterface derived from an ordered-time binary string representation
72 *
73 * @throws InvalidArgumentException if $bytes is an invalid length
74 *
75 * @inheritDoc
76 */
77 public function decodeBytes(string $bytes): UuidInterface
78 {
79 if (strlen($bytes) !== 16) {
80 throw new InvalidArgumentException('$bytes string should contain 16 characters.');
81 }
82
83 // Rearrange the bytes to their original order.
84 $rearrangedBytes = $bytes[4] . $bytes[5] . $bytes[6] . $bytes[7]
85 . $bytes[2] . $bytes[3] . $bytes[0] . $bytes[1]
86 . substr($bytes, 8);
87
88 $uuid = parent::decodeBytes($rearrangedBytes);
89
90 /** @phpstan-ignore possiblyImpure.methodCall */
91 $fields = $uuid->getFields();
92
93 if (!$fields instanceof Rfc4122FieldsInterface || $fields->getVersion() !== Uuid::UUID_TYPE_TIME) {
94 throw new UnsupportedOperationException(
95 'Attempting to decode a non-time-based UUID using OrderedTimeCodec',
96 );
97 }
98
99 return $uuid;
100 }
101 }