vendor/ramsey/uuid/src/Lazy/LazyUuidFromString.php line 55

Open in your IDE?
  1. <?php
  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 <ben@benramsey.com>
  10.  * @license http://opensource.org/licenses/MIT MIT
  11.  */
  13. declare(strict_types=1);
  15. namespace Ramsey\Uuid\Lazy;
  17. use DateTimeInterface;
  18. use Ramsey\Uuid\Converter\NumberConverterInterface;
  19. use Ramsey\Uuid\Exception\UnsupportedOperationException;
  20. use Ramsey\Uuid\Fields\FieldsInterface;
  21. use Ramsey\Uuid\Nonstandard\UuidV6;
  22. use Ramsey\Uuid\Rfc4122\UuidV1;
  23. use Ramsey\Uuid\Type\Hexadecimal;
  24. use Ramsey\Uuid\Type\Integer as IntegerObject;
  25. use Ramsey\Uuid\UuidFactory;
  26. use Ramsey\Uuid\UuidInterface;
  27. use ValueError;
  29. use function assert;
  30. use function bin2hex;
  31. use function hex2bin;
  32. use function sprintf;
  33. use function str_replace;
  34. use function substr;
  36. /**
  37.  * Lazy version of a UUID: its format has not been determined yet, so it is mostly only usable for string/bytes
  38.  * conversion. This object optimizes instantiation, serialization and string conversion time, at the cost of
  39.  * increased overhead for more advanced UUID operations.
  40.  *
  41.  * @internal this type is used internally for performance reasons, and is not supposed to be directly referenced
  42.  *           in consumer libraries.
  43.  *
  44.  * @psalm-immutable
  45.  *
  46.  * Note: the {@see FieldsInterface} does not declare methods that deprecated API
  47.  *        relies upon: the API has been ported from the {@see \Ramsey\Uuid\Uuid} definition,
  48.  *        and is deprecated anyway.
  49.  * Note: the deprecated API from {@see \Ramsey\Uuid\Uuid} is in use here (on purpose): it will be removed
  50.  *       once the deprecated API is gone from this class too.
  51.  *
  52.  * @psalm-suppress UndefinedInterfaceMethod
  53.  * @psalm-suppress DeprecatedMethod
  54.  */
  55. final class LazyUuidFromString implements UuidInterface
  56. {
  57.     public const VALID_REGEX = '/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/ms';
  58.     /**
  59.      * @var string
  60.      * @psalm-var non-empty-string
  61.      */
  62.     private $uuid;
  63.     /** @var UuidInterface|null */
  64.     private $unwrapped;
  66.     /** @psalm-param non-empty-string $uuid */
  67.     public function __construct(string $uuid)
  68.     {
  69.         $this->uuid = $uuid;
  70.     }
  72.     /** @psalm-pure */
  73.     public static function fromBytes(string $bytes): self
  74.     {
  75.         $base16Uuid = bin2hex($bytes);
  77.         return new self(
  78.             substr($base16Uuid, 0, 8)
  79.             . '-'
  80.             . substr($base16Uuid, 8, 4)
  81.             . '-'
  82.             . substr($base16Uuid, 12, 4)
  83.             . '-'
  84.             . substr($base16Uuid, 16, 4)
  85.             . '-'
  86.             . substr($base16Uuid, 20, 12)
  87.         );
  88.     }
  90.     public function serialize(): string
  91.     {
  92.         return $this->uuid;
  93.     }
  95.     /**
  96.      * @return array{string: string}
  97.      *
  98.      * @psalm-return array{string: non-empty-string}
  99.      */
  100.     public function __serialize(): array
  101.     {
  102.         return ['string' => $this->uuid];
  103.     }
  105.     /**
  106.      * {@inheritDoc}
  107.      *
  108.      * @param string $serialized
  109.      *
  110.      * @psalm-param non-empty-string $serialized
  111.      */
  112.     public function unserialize($serialized): void
  113.     {
  114.         $this->uuid = $serialized;
  115.     }
  117.     /**
  118.      * @param array{string: string} $data
  119.      *
  120.      * @psalm-param array{string: non-empty-string} $data
  121.      */
  122.     public function __unserialize(array $data): void
  123.     {
  124.         // @codeCoverageIgnoreStart
  125.         if (!isset($data['string'])) {
  126.             throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
  127.         }
  128.         // @codeCoverageIgnoreEnd
  130.         $this->unserialize($data['string']);
  131.     }
  133.     /** @psalm-suppress DeprecatedMethod */
  134.     public function getNumberConverter(): NumberConverterInterface
  135.     {
  136.         return ($this->unwrapped ?? $this->unwrap())
  137.             ->getNumberConverter();
  138.     }
  140.     /**
  141.      * {@inheritDoc}
  142.      *
  143.      * @psalm-suppress DeprecatedMethod
  144.      */
  145.     public function getFieldsHex(): array
  146.     {
  147.         return ($this->unwrapped ?? $this->unwrap())
  148.             ->getFieldsHex();
  149.     }
  151.     /** @psalm-suppress DeprecatedMethod */
  152.     public function getClockSeqHiAndReservedHex(): string
  153.     {
  154.         return ($this->unwrapped ?? $this->unwrap())
  155.             ->getClockSeqHiAndReservedHex();
  156.     }
  158.     /** @psalm-suppress DeprecatedMethod */
  159.     public function getClockSeqLowHex(): string
  160.     {
  161.         return ($this->unwrapped ?? $this->unwrap())
  162.             ->getClockSeqLowHex();
  163.     }
  165.     /** @psalm-suppress DeprecatedMethod */
  166.     public function getClockSequenceHex(): string
  167.     {
  168.         return ($this->unwrapped ?? $this->unwrap())
  169.             ->getClockSequenceHex();
  170.     }
  172.     /** @psalm-suppress DeprecatedMethod */
  173.     public function getDateTime(): DateTimeInterface
  174.     {
  175.         return ($this->unwrapped ?? $this->unwrap())
  176.             ->getDateTime();
  177.     }
  179.     /** @psalm-suppress DeprecatedMethod */
  180.     public function getLeastSignificantBitsHex(): string
  181.     {
  182.         return ($this->unwrapped ?? $this->unwrap())
  183.             ->getLeastSignificantBitsHex();
  184.     }
  186.     /** @psalm-suppress DeprecatedMethod */
  187.     public function getMostSignificantBitsHex(): string
  188.     {
  189.         return ($this->unwrapped ?? $this->unwrap())
  190.             ->getMostSignificantBitsHex();
  191.     }
  193.     /** @psalm-suppress DeprecatedMethod */
  194.     public function getNodeHex(): string
  195.     {
  196.         return ($this->unwrapped ?? $this->unwrap())
  197.             ->getNodeHex();
  198.     }
  200.     /** @psalm-suppress DeprecatedMethod */
  201.     public function getTimeHiAndVersionHex(): string
  202.     {
  203.         return ($this->unwrapped ?? $this->unwrap())
  204.             ->getTimeHiAndVersionHex();
  205.     }
  207.     /** @psalm-suppress DeprecatedMethod */
  208.     public function getTimeLowHex(): string
  209.     {
  210.         return ($this->unwrapped ?? $this->unwrap())
  211.             ->getTimeLowHex();
  212.     }
  214.     /** @psalm-suppress DeprecatedMethod */
  215.     public function getTimeMidHex(): string
  216.     {
  217.         return ($this->unwrapped ?? $this->unwrap())
  218.             ->getTimeMidHex();
  219.     }
  221.     /** @psalm-suppress DeprecatedMethod */
  222.     public function getTimestampHex(): string
  223.     {
  224.         return ($this->unwrapped ?? $this->unwrap())
  225.             ->getTimestampHex();
  226.     }
  228.     /** @psalm-suppress DeprecatedMethod */
  229.     public function getUrn(): string
  230.     {
  231.         return ($this->unwrapped ?? $this->unwrap())
  232.             ->getUrn();
  233.     }
  235.     /** @psalm-suppress DeprecatedMethod */
  236.     public function getVariant(): ?int
  237.     {
  238.         return ($this->unwrapped ?? $this->unwrap())
  239.             ->getVariant();
  240.     }
  242.     /** @psalm-suppress DeprecatedMethod */
  243.     public function getVersion(): ?int
  244.     {
  245.         return ($this->unwrapped ?? $this->unwrap())
  246.             ->getVersion();
  247.     }
  249.     public function compareTo(UuidInterface $other): int
  250.     {
  251.         return ($this->unwrapped ?? $this->unwrap())
  252.             ->compareTo($other);
  253.     }
  255.     public function equals(?object $other): bool
  256.     {
  257.         if (! $other instanceof UuidInterface) {
  258.             return false;
  259.         }
  261.         return $this->uuid === $other->toString();
  262.     }
  264.     /**
  265.      * {@inheritDoc}
  266.      *
  267.      * @psalm-suppress MoreSpecificReturnType
  268.      * @psalm-suppress LessSpecificReturnStatement we know that {@see self::$uuid} is a non-empty string, so
  269.      *                                             we know that {@see hex2bin} will retrieve a non-empty string too.
  270.      */
  271.     public function getBytes(): string
  272.     {
  273.         /** @phpstan-ignore-next-line PHPStan complains that this is not a non-empty-string. */
  274.         return (string) hex2bin(str_replace('-', '', $this->uuid));
  275.     }
  277.     public function getFields(): FieldsInterface
  278.     {
  279.         return ($this->unwrapped ?? $this->unwrap())
  280.             ->getFields();
  281.     }
  283.     public function getHex(): Hexadecimal
  284.     {
  285.         return ($this->unwrapped ?? $this->unwrap())
  286.             ->getHex();
  287.     }
  289.     public function getInteger(): IntegerObject
  290.     {
  291.         return ($this->unwrapped ?? $this->unwrap())
  292.             ->getInteger();
  293.     }
  295.     public function toString(): string
  296.     {
  297.         return $this->uuid;
  298.     }
  300.     public function __toString(): string
  301.     {
  302.         return $this->uuid;
  303.     }
  305.     public function jsonSerialize(): string
  306.     {
  307.         return $this->uuid;
  308.     }
  310.     /**
  311.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  312.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  313.      *     instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}
  314.      *     and use the arbitrary-precision math library of your choice to
  315.      *     convert it to a string integer.
  316.      *
  317.      * @psalm-suppress UndefinedInterfaceMethod
  318.      * @psalm-suppress DeprecatedMethod
  319.      * @psalm-suppress MixedArgument
  320.      * @psalm-suppress MixedMethodCall
  321.      */
  322.     public function getClockSeqHiAndReserved(): string
  323.     {
  324.         $instance = ($this->unwrapped ?? $this->unwrap());
  326.         return $instance->getNumberConverter()
  327.             ->fromHex(
  328.                 $instance->getFields()
  329.                     ->getClockSeqHiAndReserved()
  330.                     ->toString()
  331.             );
  332.     }
  334.     /**
  335.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  336.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  337.      *     instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()}
  338.      *     and use the arbitrary-precision math library of your choice to
  339.      *     convert it to a string integer.
  340.      *
  341.      * @psalm-suppress UndefinedInterfaceMethod
  342.      * @psalm-suppress DeprecatedMethod
  343.      * @psalm-suppress MixedArgument
  344.      * @psalm-suppress MixedMethodCall
  345.      */
  346.     public function getClockSeqLow(): string
  347.     {
  348.         $instance = ($this->unwrapped ?? $this->unwrap());
  350.         return $instance->getNumberConverter()
  351.             ->fromHex(
  352.                 $instance->getFields()
  353.                     ->getClockSeqLow()
  354.                     ->toString()
  355.             );
  356.     }
  358.     /**
  359.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  360.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  361.      *     instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()}
  362.      *     and use the arbitrary-precision math library of your choice to
  363.      *     convert it to a string integer.
  364.      *
  365.      * @psalm-suppress UndefinedInterfaceMethod
  366.      * @psalm-suppress DeprecatedMethod
  367.      * @psalm-suppress MixedArgument
  368.      * @psalm-suppress MixedMethodCall
  369.      */
  370.     public function getClockSequence(): string
  371.     {
  372.         $instance = ($this->unwrapped ?? $this->unwrap());
  374.         return $instance->getNumberConverter()
  375.             ->fromHex(
  376.                 $instance->getFields()
  377.                     ->getClockSeq()
  378.                     ->toString()
  379.             );
  380.     }
  382.     /**
  383.      * @deprecated This method will be removed in 5.0.0. There is no direct
  384.      *     alternative, but the same information may be obtained by splitting
  385.      *     in half the value returned by {@see UuidInterface::getHex()}.
  386.      *
  387.      * @psalm-suppress UndefinedInterfaceMethod
  388.      * @psalm-suppress DeprecatedMethod
  389.      * @psalm-suppress MixedArgument
  390.      * @psalm-suppress MixedMethodCall
  391.      */
  392.     public function getLeastSignificantBits(): string
  393.     {
  394.         $instance = ($this->unwrapped ?? $this->unwrap());
  396.         return $instance->getNumberConverter()
  397.             ->fromHex(substr($instance->getHex()->toString(), 16));
  398.     }
  400.     /**
  401.      * @deprecated This method will be removed in 5.0.0. There is no direct
  402.      *     alternative, but the same information may be obtained by splitting
  403.      *     in half the value returned by {@see UuidInterface::getHex()}.
  404.      *
  405.      * @psalm-suppress UndefinedInterfaceMethod
  406.      * @psalm-suppress DeprecatedMethod
  407.      * @psalm-suppress MixedArgument
  408.      * @psalm-suppress MixedMethodCall
  409.      */
  410.     public function getMostSignificantBits(): string
  411.     {
  412.         $instance = ($this->unwrapped ?? $this->unwrap());
  414.         return $instance->getNumberConverter()
  415.             ->fromHex(substr($instance->getHex()->toString(), 0, 16));
  416.     }
  418.     /**
  419.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  420.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  421.      *     instance, you may call {@see Rfc4122FieldsInterface::getNode()}
  422.      *     and use the arbitrary-precision math library of your choice to
  423.      *     convert it to a string integer.
  424.      *
  425.      * @psalm-suppress UndefinedInterfaceMethod
  426.      * @psalm-suppress DeprecatedMethod
  427.      * @psalm-suppress MixedArgument
  428.      * @psalm-suppress MixedMethodCall
  429.      */
  430.     public function getNode(): string
  431.     {
  432.         $instance = ($this->unwrapped ?? $this->unwrap());
  434.         return $instance->getNumberConverter()
  435.             ->fromHex(
  436.                 $instance->getFields()
  437.                     ->getNode()
  438.                     ->toString()
  439.             );
  440.     }
  442.     /**
  443.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  444.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  445.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()}
  446.      *     and use the arbitrary-precision math library of your choice to
  447.      *     convert it to a string integer.
  448.      *
  449.      * @psalm-suppress UndefinedInterfaceMethod
  450.      * @psalm-suppress DeprecatedMethod
  451.      * @psalm-suppress MixedArgument
  452.      * @psalm-suppress MixedMethodCall
  453.      */
  454.     public function getTimeHiAndVersion(): string
  455.     {
  456.         $instance = ($this->unwrapped ?? $this->unwrap());
  458.         return $instance->getNumberConverter()
  459.             ->fromHex(
  460.                 $instance->getFields()
  461.                     ->getTimeHiAndVersion()
  462.                     ->toString()
  463.             );
  464.     }
  466.     /**
  467.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  468.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  469.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()}
  470.      *     and use the arbitrary-precision math library of your choice to
  471.      *     convert it to a string integer.
  472.      *
  473.      * @psalm-suppress UndefinedInterfaceMethod
  474.      * @psalm-suppress DeprecatedMethod
  475.      * @psalm-suppress MixedArgument
  476.      * @psalm-suppress MixedMethodCall
  477.      */
  478.     public function getTimeLow(): string
  479.     {
  480.         $instance = ($this->unwrapped ?? $this->unwrap());
  482.         return $instance->getNumberConverter()
  483.             ->fromHex(
  484.                 $instance->getFields()
  485.                     ->getTimeLow()
  486.                     ->toString()
  487.             );
  488.     }
  490.     /**
  491.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  492.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  493.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()}
  494.      *     and use the arbitrary-precision math library of your choice to
  495.      *     convert it to a string integer.
  496.      *
  497.      * @psalm-suppress UndefinedInterfaceMethod
  498.      * @psalm-suppress DeprecatedMethod
  499.      * @psalm-suppress MixedArgument
  500.      * @psalm-suppress MixedMethodCall
  501.      */
  502.     public function getTimeMid(): string
  503.     {
  504.         $instance = ($this->unwrapped ?? $this->unwrap());
  506.         return $instance->getNumberConverter()
  507.             ->fromHex(
  508.                 $instance->getFields()
  509.                     ->getTimeMid()
  510.                     ->toString()
  511.             );
  512.     }
  514.     /**
  515.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  516.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  517.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()}
  518.      *     and use the arbitrary-precision math library of your choice to
  519.      *     convert it to a string integer.
  520.      *
  521.      * @psalm-suppress UndefinedInterfaceMethod
  522.      * @psalm-suppress DeprecatedMethod
  523.      * @psalm-suppress MixedArgument
  524.      * @psalm-suppress MixedMethodCall
  525.      */
  526.     public function getTimestamp(): string
  527.     {
  528.         $instance = ($this->unwrapped ?? $this->unwrap());
  529.         $fields = $instance->getFields();
  531.         if ($fields->getVersion() !== 1) {
  532.             throw new UnsupportedOperationException('Not a time-based UUID');
  533.         }
  535.         return $instance->getNumberConverter()
  536.             ->fromHex($fields->getTimestamp()->toString());
  537.     }
  539.     public function toUuidV1(): UuidV1
  540.     {
  541.         $instance = ($this->unwrapped ?? $this->unwrap());
  543.         if ($instance instanceof UuidV1) {
  544.             return $instance;
  545.         }
  547.         assert($instance instanceof UuidV6);
  549.         return $instance->toUuidV1();
  550.     }
  552.     public function toUuidV6(): UuidV6
  553.     {
  554.         $instance = ($this->unwrapped ?? $this->unwrap());
  556.         assert($instance instanceof UuidV6);
  558.         return $instance;
  559.     }
  561.     /**
  562.      * @psalm-suppress ImpureMethodCall the retrieval of the factory is a clear violation of purity here: this is a
  563.      *                                  known pitfall of the design of this library, where a value object contains
  564.      *                                  a mutable reference to a factory. We use a fixed factory here, so the violation
  565.      *                                  will not have real-world effects, as this object is only instantiated with the
  566.      *                                  default factory settings/features.
  567.      * @psalm-suppress InaccessibleProperty property {@see $unwrapped} is used as a cache: we don't expose it to the
  568.      *                                      outside world, so we should be fine here.
  569.      */
  570.     private function unwrap(): UuidInterface
  571.     {
  572.         return $this->unwrapped = (new UuidFactory())
  573.             ->fromString($this->uuid);
  574.     }
  575. }