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

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;
  28. use function assert;
  29. use function bin2hex;
  30. use function hex2bin;
  31. use function str_replace;
  32. use function substr;
  34. /**
  35.  * Lazy version of a UUID: its format has not been determined yet, so it is mostly only usable for string/bytes
  36.  * conversion. This object optimizes instantiation, serialization and string conversion time, at the cost of
  37.  * increased overhead for more advanced UUID operations.
  38.  *
  39.  * @internal this type is used internally for performance reasons, and is not supposed to be directly referenced
  40.  *           in consumer libraries.
  41.  *
  42.  * @psalm-immutable
  43.  *
  44.  * Note: the {@see FieldsInterface} does not declare methods that deprecated API
  45.  *        relies upon: the API has been ported from the {@see \Ramsey\Uuid\Uuid} definition,
  46.  *        and is deprecated anyway.
  47.  * Note: the deprecated API from {@see \Ramsey\Uuid\Uuid} is in use here (on purpose): it will be removed
  48.  *       once the deprecated API is gone from this class too.
  49.  *
  50.  * @psalm-suppress UndefinedInterfaceMethod
  51.  * @psalm-suppress DeprecatedMethod
  52.  */
  53. final class LazyUuidFromString implements UuidInterface
  54. {
  55.     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';
  56.     /**
  57.      * @var string
  58.      * @psalm-var non-empty-string
  59.      */
  60.     private $uuid;
  61.     /** @var UuidInterface|null */
  62.     private $unwrapped;
  64.     /** @psalm-param non-empty-string $uuid */
  65.     public function __construct(string $uuid)
  66.     {
  67.         $this->uuid = $uuid;
  68.     }
  70.     /** @psalm-pure */
  71.     public static function fromBytes(string $bytes): self
  72.     {
  73.         $base16Uuid = bin2hex($bytes);
  75.         return new self(
  76.             substr($base16Uuid, 0, 8)
  77.             . '-'
  78.             . substr($base16Uuid, 8, 4)
  79.             . '-'
  80.             . substr($base16Uuid, 12, 4)
  81.             . '-'
  82.             . substr($base16Uuid, 16, 4)
  83.             . '-'
  84.             . substr($base16Uuid, 20, 12)
  85.         );
  86.     }
  88.     public function serialize(): string
  89.     {
  90.         return $this->uuid;
  91.     }
  93.     /**
  94.      * {@inheritDoc}
  95.      *
  96.      * @param string $serialized
  97.      *
  98.      * @psalm-param non-empty-string $serialized
  99.      */
  100.     public function unserialize($serialized): void
  101.     {
  102.         $this->uuid = $serialized;
  103.     }
  105.     /** @psalm-suppress DeprecatedMethod */
  106.     public function getNumberConverter(): NumberConverterInterface
  107.     {
  108.         return ($this->unwrapped ?? $this->unwrap())
  109.             ->getNumberConverter();
  110.     }
  112.     /**
  113.      * {@inheritDoc}
  114.      *
  115.      * @psalm-suppress DeprecatedMethod
  116.      */
  117.     public function getFieldsHex(): array
  118.     {
  119.         return ($this->unwrapped ?? $this->unwrap())
  120.             ->getFieldsHex();
  121.     }
  123.     /** @psalm-suppress DeprecatedMethod */
  124.     public function getClockSeqHiAndReservedHex(): string
  125.     {
  126.         return ($this->unwrapped ?? $this->unwrap())
  127.             ->getClockSeqHiAndReservedHex();
  128.     }
  130.     /** @psalm-suppress DeprecatedMethod */
  131.     public function getClockSeqLowHex(): string
  132.     {
  133.         return ($this->unwrapped ?? $this->unwrap())
  134.             ->getClockSeqLowHex();
  135.     }
  137.     /** @psalm-suppress DeprecatedMethod */
  138.     public function getClockSequenceHex(): string
  139.     {
  140.         return ($this->unwrapped ?? $this->unwrap())
  141.             ->getClockSequenceHex();
  142.     }
  144.     /** @psalm-suppress DeprecatedMethod */
  145.     public function getDateTime(): DateTimeInterface
  146.     {
  147.         return ($this->unwrapped ?? $this->unwrap())
  148.             ->getDateTime();
  149.     }
  151.     /** @psalm-suppress DeprecatedMethod */
  152.     public function getLeastSignificantBitsHex(): string
  153.     {
  154.         return ($this->unwrapped ?? $this->unwrap())
  155.             ->getLeastSignificantBitsHex();
  156.     }
  158.     /** @psalm-suppress DeprecatedMethod */
  159.     public function getMostSignificantBitsHex(): string
  160.     {
  161.         return ($this->unwrapped ?? $this->unwrap())
  162.             ->getMostSignificantBitsHex();
  163.     }
  165.     /** @psalm-suppress DeprecatedMethod */
  166.     public function getNodeHex(): string
  167.     {
  168.         return ($this->unwrapped ?? $this->unwrap())
  169.             ->getNodeHex();
  170.     }
  172.     /** @psalm-suppress DeprecatedMethod */
  173.     public function getTimeHiAndVersionHex(): string
  174.     {
  175.         return ($this->unwrapped ?? $this->unwrap())
  176.             ->getTimeHiAndVersionHex();
  177.     }
  179.     /** @psalm-suppress DeprecatedMethod */
  180.     public function getTimeLowHex(): string
  181.     {
  182.         return ($this->unwrapped ?? $this->unwrap())
  183.             ->getTimeLowHex();
  184.     }
  186.     /** @psalm-suppress DeprecatedMethod */
  187.     public function getTimeMidHex(): string
  188.     {
  189.         return ($this->unwrapped ?? $this->unwrap())
  190.             ->getTimeMidHex();
  191.     }
  193.     /** @psalm-suppress DeprecatedMethod */
  194.     public function getTimestampHex(): string
  195.     {
  196.         return ($this->unwrapped ?? $this->unwrap())
  197.             ->getTimestampHex();
  198.     }
  200.     /** @psalm-suppress DeprecatedMethod */
  201.     public function getUrn(): string
  202.     {
  203.         return ($this->unwrapped ?? $this->unwrap())
  204.             ->getUrn();
  205.     }
  207.     /** @psalm-suppress DeprecatedMethod */
  208.     public function getVariant(): ?int
  209.     {
  210.         return ($this->unwrapped ?? $this->unwrap())
  211.             ->getVariant();
  212.     }
  214.     /** @psalm-suppress DeprecatedMethod */
  215.     public function getVersion(): ?int
  216.     {
  217.         return ($this->unwrapped ?? $this->unwrap())
  218.             ->getVersion();
  219.     }
  221.     public function compareTo(UuidInterface $other): int
  222.     {
  223.         return ($this->unwrapped ?? $this->unwrap())
  224.             ->compareTo($other);
  225.     }
  227.     public function equals(?object $other): bool
  228.     {
  229.         if (! $other instanceof UuidInterface) {
  230.             return false;
  231.         }
  233.         return $this->uuid === $other->toString();
  234.     }
  236.     /**
  237.      * {@inheritDoc}
  238.      *
  239.      * @psalm-suppress MoreSpecificReturnType
  240.      * @psalm-suppress LessSpecificReturnStatement we know that {@see self::$uuid} is a non-empty string, so
  241.      *                                             we know that {@see hex2bin} will retrieve a non-empty string too.
  242.      */
  243.     public function getBytes(): string
  244.     {
  245.         return (string) hex2bin(str_replace('-', '', $this->uuid));
  246.     }
  248.     public function getFields(): FieldsInterface
  249.     {
  250.         return ($this->unwrapped ?? $this->unwrap())
  251.             ->getFields();
  252.     }
  254.     public function getHex(): Hexadecimal
  255.     {
  256.         return ($this->unwrapped ?? $this->unwrap())
  257.             ->getHex();
  258.     }
  260.     public function getInteger(): IntegerObject
  261.     {
  262.         return ($this->unwrapped ?? $this->unwrap())
  263.             ->getInteger();
  264.     }
  266.     public function toString(): string
  267.     {
  268.         return $this->uuid;
  269.     }
  271.     public function __toString(): string
  272.     {
  273.         return $this->uuid;
  274.     }
  276.     public function jsonSerialize(): string
  277.     {
  278.         return $this->uuid;
  279.     }
  281.     /**
  282.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  283.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  284.      *     instance, you may call {@see Rfc4122FieldsInterface::getClockSeqHiAndReserved()}
  285.      *     and use the arbitrary-precision math library of your choice to
  286.      *     convert it to a string integer.
  287.      *
  288.      * @psalm-suppress UndefinedInterfaceMethod
  289.      * @psalm-suppress DeprecatedMethod
  290.      * @psalm-suppress MixedArgument
  291.      * @psalm-suppress MixedMethodCall
  292.      */
  293.     public function getClockSeqHiAndReserved(): string
  294.     {
  295.         $instance = ($this->unwrapped ?? $this->unwrap());
  297.         return $instance->getNumberConverter()
  298.             ->fromHex(
  299.                 $instance->getFields()
  300.                     ->getClockSeqHiAndReserved()
  301.                     ->toString()
  302.             );
  303.     }
  305.     /**
  306.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  307.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  308.      *     instance, you may call {@see Rfc4122FieldsInterface::getClockSeqLow()}
  309.      *     and use the arbitrary-precision math library of your choice to
  310.      *     convert it to a string integer.
  311.      *
  312.      * @psalm-suppress UndefinedInterfaceMethod
  313.      * @psalm-suppress DeprecatedMethod
  314.      * @psalm-suppress MixedArgument
  315.      * @psalm-suppress MixedMethodCall
  316.      */
  317.     public function getClockSeqLow(): string
  318.     {
  319.         $instance = ($this->unwrapped ?? $this->unwrap());
  321.         return $instance->getNumberConverter()
  322.             ->fromHex(
  323.                 $instance->getFields()
  324.                     ->getClockSeqLow()
  325.                     ->toString()
  326.             );
  327.     }
  329.     /**
  330.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  331.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  332.      *     instance, you may call {@see Rfc4122FieldsInterface::getClockSeq()}
  333.      *     and use the arbitrary-precision math library of your choice to
  334.      *     convert it to a string integer.
  335.      *
  336.      * @psalm-suppress UndefinedInterfaceMethod
  337.      * @psalm-suppress DeprecatedMethod
  338.      * @psalm-suppress MixedArgument
  339.      * @psalm-suppress MixedMethodCall
  340.      */
  341.     public function getClockSequence(): string
  342.     {
  343.         $instance = ($this->unwrapped ?? $this->unwrap());
  345.         return $instance->getNumberConverter()
  346.             ->fromHex(
  347.                 $instance->getFields()
  348.                     ->getClockSeq()
  349.                     ->toString()
  350.             );
  351.     }
  353.     /**
  354.      * @deprecated This method will be removed in 5.0.0. There is no direct
  355.      *     alternative, but the same information may be obtained by splitting
  356.      *     in half the value returned by {@see UuidInterface::getHex()}.
  357.      *
  358.      * @psalm-suppress UndefinedInterfaceMethod
  359.      * @psalm-suppress DeprecatedMethod
  360.      * @psalm-suppress MixedArgument
  361.      * @psalm-suppress MixedMethodCall
  362.      */
  363.     public function getLeastSignificantBits(): string
  364.     {
  365.         $instance = ($this->unwrapped ?? $this->unwrap());
  367.         return $instance->getNumberConverter()
  368.             ->fromHex(substr($instance->getHex()->toString(), 16));
  369.     }
  371.     /**
  372.      * @deprecated This method will be removed in 5.0.0. There is no direct
  373.      *     alternative, but the same information may be obtained by splitting
  374.      *     in half the value returned by {@see UuidInterface::getHex()}.
  375.      *
  376.      * @psalm-suppress UndefinedInterfaceMethod
  377.      * @psalm-suppress DeprecatedMethod
  378.      * @psalm-suppress MixedArgument
  379.      * @psalm-suppress MixedMethodCall
  380.      */
  381.     public function getMostSignificantBits(): string
  382.     {
  383.         $instance = ($this->unwrapped ?? $this->unwrap());
  385.         return $instance->getNumberConverter()
  386.             ->fromHex(substr($instance->getHex()->toString(), 0, 16));
  387.     }
  389.     /**
  390.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  391.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  392.      *     instance, you may call {@see Rfc4122FieldsInterface::getNode()}
  393.      *     and use the arbitrary-precision math library of your choice to
  394.      *     convert it to a string integer.
  395.      *
  396.      * @psalm-suppress UndefinedInterfaceMethod
  397.      * @psalm-suppress DeprecatedMethod
  398.      * @psalm-suppress MixedArgument
  399.      * @psalm-suppress MixedMethodCall
  400.      */
  401.     public function getNode(): string
  402.     {
  403.         $instance = ($this->unwrapped ?? $this->unwrap());
  405.         return $instance->getNumberConverter()
  406.             ->fromHex(
  407.                 $instance->getFields()
  408.                     ->getNode()
  409.                     ->toString()
  410.             );
  411.     }
  413.     /**
  414.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  415.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  416.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimeHiAndVersion()}
  417.      *     and use the arbitrary-precision math library of your choice to
  418.      *     convert it to a string integer.
  419.      *
  420.      * @psalm-suppress UndefinedInterfaceMethod
  421.      * @psalm-suppress DeprecatedMethod
  422.      * @psalm-suppress MixedArgument
  423.      * @psalm-suppress MixedMethodCall
  424.      */
  425.     public function getTimeHiAndVersion(): string
  426.     {
  427.         $instance = ($this->unwrapped ?? $this->unwrap());
  429.         return $instance->getNumberConverter()
  430.             ->fromHex(
  431.                 $instance->getFields()
  432.                     ->getTimeHiAndVersion()
  433.                     ->toString()
  434.             );
  435.     }
  437.     /**
  438.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  439.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  440.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimeLow()}
  441.      *     and use the arbitrary-precision math library of your choice to
  442.      *     convert it to a string integer.
  443.      *
  444.      * @psalm-suppress UndefinedInterfaceMethod
  445.      * @psalm-suppress DeprecatedMethod
  446.      * @psalm-suppress MixedArgument
  447.      * @psalm-suppress MixedMethodCall
  448.      */
  449.     public function getTimeLow(): string
  450.     {
  451.         $instance = ($this->unwrapped ?? $this->unwrap());
  453.         return $instance->getNumberConverter()
  454.             ->fromHex(
  455.                 $instance->getFields()
  456.                     ->getTimeLow()
  457.                     ->toString()
  458.             );
  459.     }
  461.     /**
  462.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  463.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  464.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimeMid()}
  465.      *     and use the arbitrary-precision math library of your choice to
  466.      *     convert it to a string integer.
  467.      *
  468.      * @psalm-suppress UndefinedInterfaceMethod
  469.      * @psalm-suppress DeprecatedMethod
  470.      * @psalm-suppress MixedArgument
  471.      * @psalm-suppress MixedMethodCall
  472.      */
  473.     public function getTimeMid(): string
  474.     {
  475.         $instance = ($this->unwrapped ?? $this->unwrap());
  477.         return $instance->getNumberConverter()
  478.             ->fromHex(
  479.                 $instance->getFields()
  480.                     ->getTimeMid()
  481.                     ->toString()
  482.             );
  483.     }
  485.     /**
  486.      * @deprecated Use {@see UuidInterface::getFields()} to get a
  487.      *     {@see FieldsInterface} instance. If it is a {@see Rfc4122FieldsInterface}
  488.      *     instance, you may call {@see Rfc4122FieldsInterface::getTimestamp()}
  489.      *     and use the arbitrary-precision math library of your choice to
  490.      *     convert it to a string integer.
  491.      *
  492.      * @psalm-suppress UndefinedInterfaceMethod
  493.      * @psalm-suppress DeprecatedMethod
  494.      * @psalm-suppress MixedArgument
  495.      * @psalm-suppress MixedMethodCall
  496.      */
  497.     public function getTimestamp(): string
  498.     {
  499.         $instance = ($this->unwrapped ?? $this->unwrap());
  500.         $fields   = $instance->getFields();
  502.         if ($fields->getVersion() !== 1) {
  503.             throw new UnsupportedOperationException('Not a time-based UUID');
  504.         }
  506.         return $instance->getNumberConverter()
  507.             ->fromHex($fields->getTimestamp()->toString());
  508.     }
  510.     public function toUuidV1(): UuidV1
  511.     {
  512.         $instance = ($this->unwrapped ?? $this->unwrap());
  514.         if ($instance instanceof UuidV1) {
  515.             return $instance;
  516.         }
  518.         assert($instance instanceof UuidV6);
  520.         return $instance->toUuidV1();
  521.     }
  523.     public function toUuidV6(): UuidV6
  524.     {
  525.         $instance = ($this->unwrapped ?? $this->unwrap());
  527.         assert($instance instanceof UuidV6);
  529.         return $instance;
  530.     }
  532.     /**
  533.      * @psalm-suppress ImpureMethodCall the retrieval of the factory is a clear violation of purity here: this is a
  534.      *                                  known pitfall of the design of this library, where a value object contains
  535.      *                                  a mutable reference to a factory. We use a fixed factory here, so the violation
  536.      *                                  will not have real-world effects, as this object is only instantiated with the
  537.      *                                  default factory settings/features.
  538.      * @psalm-suppress InaccessibleProperty property {@see $unwrapped} is used as a cache: we don't expose it to the
  539.      *                                      outside world, so we should be fine here.
  540.      */
  541.     private function unwrap(): UuidInterface
  542.     {
  543.         return $this->unwrapped = (new UuidFactory())
  544.             ->fromString($this->uuid);
  545.     }
  546. }