Subversion-Projekte lars-tiefland.laravel_shop

<?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;

use BadMethodCallException;

use DateTimeInterface;

use Ramsey\Uuid\Codec\CodecInterface;

use Ramsey\Uuid\Converter\NumberConverterInterface;

use Ramsey\Uuid\Converter\TimeConverterInterface;

use Ramsey\Uuid\Exception\UnsupportedOperationException;

use Ramsey\Uuid\Fields\FieldsInterface;

use Ramsey\Uuid\Lazy\LazyUuidFromString;

use Ramsey\Uuid\Rfc4122\FieldsInterface as Rfc4122FieldsInterface;

use Ramsey\Uuid\Type\Hexadecimal;

use Ramsey\Uuid\Type\Integer as IntegerObject;

use ValueError;

use function assert;

use function bin2hex;

use function method_exists;

use function preg_match;

use function sprintf;

use function str_replace;

use function strcmp;

use function strlen;

use function strtolower;

use function substr;

/**

 * Uuid provides constants and static methods for working with and generating UUIDs

 *

 * @psalm-immutable

 */

class Uuid implements UuidInterface

{

    use DeprecatedUuidMethodsTrait;

    /**

     * When this namespace is specified, the name string is a fully-qualified

     * domain name

     *

     * @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs

     */

    public const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';

    /**

     * When this namespace is specified, the name string is a URL

     *

     * @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs

     */

    public const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';

    /**

     * When this namespace is specified, the name string is an ISO OID

     *

     * @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs

     */

    public const NAMESPACE_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';

    /**

     * When this namespace is specified, the name string is an X.500 DN in DER

     * or a text output format

     *

     * @link http://tools.ietf.org/html/rfc4122#appendix-C RFC 4122, Appendix C: Some Name Space IDs

     */

    public const NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8';

    /**

     * The nil UUID is a special form of UUID that is specified to have all 128

     * bits set to zero

     *

     * @link http://tools.ietf.org/html/rfc4122#section-4.1.7 RFC 4122, § 4.1.7: Nil UUID

     */

    public const NIL = '00000000-0000-0000-0000-000000000000';

    /**

     * The max UUID is a special form of UUID that is specified to have all 128

     * bits set to one

     *

     * @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.10 Max UUID

     */

    public const MAX = 'ffffffff-ffff-ffff-ffff-ffffffffffff';

    /**

     * Variant: reserved, NCS backward compatibility

     *

     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant

     */

    public const RESERVED_NCS = 0;

    /**

     * Variant: the UUID layout specified in RFC 4122

     *

     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant

     */

    public const RFC_4122 = 2;

    /**

     * Variant: reserved, Microsoft Corporation backward compatibility

     *

     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant

     */

    public const RESERVED_MICROSOFT = 6;

    /**

     * Variant: reserved for future definition

     *

     * @link http://tools.ietf.org/html/rfc4122#section-4.1.1 RFC 4122, § 4.1.1: Variant

     */

    public const RESERVED_FUTURE = 7;

    /**

     * @deprecated Use {@see ValidatorInterface::getPattern()} instead.

     */

    public const VALID_PATTERN = '^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$';

    /**

     * Version 1 (Gregorian time) UUID

     *

     * @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version

     */

    public const UUID_TYPE_TIME = 1;

    /**

     * Version 2 (DCE Security) UUID

     *

     * @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version

     */

    public const UUID_TYPE_DCE_SECURITY = 2;

    /**

     * @deprecated Use {@see Uuid::UUID_TYPE_DCE_SECURITY} instead.

     */

    public const UUID_TYPE_IDENTIFIER = 2;

    /**

     * Version 3 (name-based and hashed with MD5) UUID

     *

     * @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version

     */

    public const UUID_TYPE_HASH_MD5 = 3;

    /**

     * Version 4 (random) UUID

     *

     * @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version

     */

    public const UUID_TYPE_RANDOM = 4;

    /**

     * Version 5 (name-based and hashed with SHA1) UUID

     *

     * @link https://tools.ietf.org/html/rfc4122#section-4.1.3 RFC 4122, § 4.1.3: Version

     */

    public const UUID_TYPE_HASH_SHA1 = 5;

    /**

     * @deprecated Use {@see Uuid::UUID_TYPE_REORDERED_TIME} instead.

     */

    public const UUID_TYPE_PEABODY = 6;

    /**

     * Version 6 (reordered time) UUID

     *

     * @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.6 UUID Version 6

     */

    public const UUID_TYPE_REORDERED_TIME = 6;

    /**

     * Version 7 (Unix Epoch time) UUID

     *

     * @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.7 UUID Version 7

     */

    public const UUID_TYPE_UNIX_TIME = 7;

    /**

     * @link https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis-00#section-5.8 UUID Version 8

     */

    public const UUID_TYPE_CUSTOM = 8;

    /**

     * DCE Security principal domain

     *

     * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1

     */

    public const DCE_DOMAIN_PERSON = 0;

    /**

     * DCE Security group domain

     *

     * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1

     */

    public const DCE_DOMAIN_GROUP = 1;

    /**

     * DCE Security organization domain

     *

     * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1

     */

    public const DCE_DOMAIN_ORG = 2;

    /**

     * DCE Security domain string names

     *

     * @link https://pubs.opengroup.org/onlinepubs/9696989899/chap11.htm#tagcjh_14_05_01_01 DCE 1.1, §11.5.1.1

     */

    public const DCE_DOMAIN_NAMES = [

        self::DCE_DOMAIN_PERSON => 'person',

        self::DCE_DOMAIN_GROUP => 'group',

        self::DCE_DOMAIN_ORG => 'org',

    ];

    private static ?UuidFactoryInterface $factory = null;

    /**

     * @var bool flag to detect if the UUID factory was replaced internally,

     *     which disables all optimizations for the default/happy path internal

     *     scenarios

     */

    private static bool $factoryReplaced = false;

    protected CodecInterface $codec;

    protected NumberConverterInterface $numberConverter;

    protected Rfc4122FieldsInterface $fields;

    protected TimeConverterInterface $timeConverter;

    /**

     * Creates a universally unique identifier (UUID) from an array of fields

     *

     * Unless you're making advanced use of this library to generate identifiers

     * that deviate from RFC 4122, you probably do not want to instantiate a

     * UUID directly. Use the static methods, instead:

     *

     * ```

     * use Ramsey\Uuid\Uuid;

     *

     * $timeBasedUuid = Uuid::uuid1();

     * $namespaceMd5Uuid = Uuid::uuid3(Uuid::NAMESPACE_URL, 'http://php.net/');

     * $randomUuid = Uuid::uuid4();

     * $namespaceSha1Uuid = Uuid::uuid5(Uuid::NAMESPACE_URL, 'http://php.net/');

     * ```

     *

     * @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

    ) {

        $this->fields = $fields;

        $this->codec = $codec;

        $this->numberConverter = $numberConverter;

        $this->timeConverter = $timeConverter;

    }

    /**

     * @psalm-return non-empty-string

     */

    public function __toString(): string

    {

        return $this->toString();

    }

    /**

     * Converts the UUID to a string for JSON serialization

     */

    public function jsonSerialize(): string

    {

        return $this->toString();

    }

    /**

     * Converts the UUID to a string for PHP serialization

     */

    public function serialize(): string

    {

        return $this->getFields()->getBytes();

    }

    /**

     * @return array{bytes: string}

     */

    public function __serialize(): array

    {

        return ['bytes' => $this->serialize()];

    }

    /**

     * Re-constructs the object from its serialized form

     *

     * @param string $data The serialized PHP string to unserialize into

     *     a UuidInterface instance

     */

    public function unserialize(string $data): void

    {

        if (strlen($data) === 16) {

            /** @var Uuid $uuid */

            $uuid = self::getFactory()->fromBytes($data);

        } else {

            /** @var Uuid $uuid */

            $uuid = self::getFactory()->fromString($data);

        }

        $this->codec = $uuid->codec;

        $this->numberConverter = $uuid->numberConverter;

        $this->fields = $uuid->fields;

        $this->timeConverter = $uuid->timeConverter;

    }

    /**

     * @param array{bytes?: string} $data

     */

    public function __unserialize(array $data): void

    {

        // @codeCoverageIgnoreStart

        if (!isset($data['bytes'])) {

            throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));

        }

        // @codeCoverageIgnoreEnd

        $this->unserialize($data['bytes']);

    }

    public function compareTo(UuidInterface $other): int

    {

        $compare = strcmp($this->toString(), $other->toString());

        if ($compare < 0) {

            return -1;

        }

        if ($compare > 0) {

            return 1;

        }

        return 0;

    }

    public function equals(?object $other): bool

    {

        if (!$other instanceof UuidInterface) {

            return false;

        }

        return $this->compareTo($other) === 0;

    }

    /**

     * @psalm-return non-empty-string

     */

    public function getBytes(): string

    {

        return $this->codec->encodeBinary($this);

    }

    public function getFields(): FieldsInterface

    {

        return $this->fields;

    }

    public function getHex(): Hexadecimal

    {

        return new Hexadecimal(str_replace('-', '', $this->toString()));

    }

    public function getInteger(): IntegerObject

    {

        return new IntegerObject($this->numberConverter->fromHex($this->getHex()->toString()));

    }

    public function getUrn(): string

    {

        return 'urn:uuid:' . $this->toString();

    }

    /**

     * @psalm-return non-empty-string

     */

    public function toString(): string

    {

        return $this->codec->encode($this);

    }

    /**

     * Returns the factory used to create UUIDs

     */

    public static function getFactory(): UuidFactoryInterface

    {

        if (self::$factory === null) {

            self::$factory = new UuidFactory();

        }

        return self::$factory;

    }

    /**

     * Sets the factory used to create UUIDs

     *

     * @param UuidFactoryInterface $factory A factory that will be used by this

     *     class to create UUIDs

     */

    public static function setFactory(UuidFactoryInterface $factory): void

    {

        // Note: non-strict equality is intentional here. If the factory is configured differently, every assumption

        //       around purity is broken, and we have to internally decide everything differently.

        // phpcs:ignore SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedNotEqualOperator

        self::$factoryReplaced = ($factory != new UuidFactory());

        self::$factory = $factory;

    }

    /**

     * Creates a UUID from a byte string

     *

     * @param string $bytes A binary string

     *

     * @return UuidInterface A UuidInterface instance created from a binary

     *     string representation

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     *

     * @psalm-suppress ImpureStaticProperty we know that the factory being replaced can lead to massive

     *                                      havoc across all consumers: that should never happen, and

     *                                      is generally to be discouraged. Until the factory is kept

     *                                      un-replaced, this method is effectively pure.

     */

    public static function fromBytes(string $bytes): UuidInterface

    {

        if (! self::$factoryReplaced && strlen($bytes) === 16) {

            $base16Uuid = bin2hex($bytes);

            // Note: we are calling `fromString` internally because we don't know if the given `$bytes` is a valid UUID

            return self::fromString(

                substr($base16Uuid, 0, 8)

                . '-'

                . substr($base16Uuid, 8, 4)

                . '-'

                . substr($base16Uuid, 12, 4)

                . '-'

                . substr($base16Uuid, 16, 4)

                . '-'

                . substr($base16Uuid, 20, 12)

            );

        }

        return self::getFactory()->fromBytes($bytes);

    }

    /**

     * Creates a UUID from the string standard representation

     *

     * @param string $uuid A hexadecimal string

     *

     * @return UuidInterface A UuidInterface instance created from a hexadecimal

     *     string representation

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     *

     * @psalm-suppress ImpureStaticProperty we know that the factory being replaced can lead to massive

     *                                      havoc across all consumers: that should never happen, and

     *                                      is generally to be discouraged. Until the factory is kept

     *                                      un-replaced, this method is effectively pure.

     */

    public static function fromString(string $uuid): UuidInterface

    {

        $uuid = strtolower($uuid);

        if (! self::$factoryReplaced && preg_match(LazyUuidFromString::VALID_REGEX, $uuid) === 1) {

            assert($uuid !== '');

            return new LazyUuidFromString($uuid);

        }

        return self::getFactory()->fromString($uuid);

    }

    /**

     * Creates a UUID from a DateTimeInterface instance

     *

     * @param DateTimeInterface $dateTime The date and time

     * @param Hexadecimal|null $node A 48-bit number representing the hardware

     *     address

     * @param int|null $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 1 UUID created from a DateTimeInterface instance

     */

    public static function fromDateTime(

        DateTimeInterface $dateTime,

        ?Hexadecimal $node = null,

        ?int $clockSeq = null

    ): UuidInterface {

        return self::getFactory()->fromDateTime($dateTime, $node, $clockSeq);

    }

    /**

     * Creates a UUID from the Hexadecimal object

     *

     * @param Hexadecimal $hex Hexadecimal object representing a hexadecimal number

     *

     * @return UuidInterface A UuidInterface instance created from the Hexadecimal

     * object representing a hexadecimal number

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     * @psalm-suppress MixedInferredReturnType,MixedReturnStatement

     */

    public static function fromHexadecimal(Hexadecimal $hex): UuidInterface

    {

        $factory = self::getFactory();

        if (method_exists($factory, 'fromHexadecimal')) {

            /**

             * @phpstan-ignore-next-line

             * @psalm-suppress UndefinedInterfaceMethod

             */

            return self::getFactory()->fromHexadecimal($hex);

        }

        throw new BadMethodCallException('The method fromHexadecimal() does not exist on the provided factory');

    }

    /**

     * Creates a UUID from a 128-bit integer string

     *

     * @param string $integer String representation of 128-bit integer

     *

     * @return UuidInterface A UuidInterface instance created from the string

     *     representation of a 128-bit integer

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     */

    public static function fromInteger(string $integer): UuidInterface

    {

        /** @psalm-suppress ImpureMethodCall */

        return self::getFactory()->fromInteger($integer);

    }

    /**

     * Returns true if the provided string is a valid UUID

     *

     * @param string $uuid A string to validate as a UUID

     *

     * @return bool True if the string is a valid UUID, false otherwise

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     *

     * @psalm-assert-if-true =non-empty-string $uuid

     */

    public static function isValid(string $uuid): bool

    {

        /** @psalm-suppress ImpureMethodCall */

        return self::getFactory()->getValidator()->validate($uuid);

    }

    /**

     * Returns a version 1 (Gregorian time) UUID from a host ID, sequence number,

     * and the current time

     *

     * @param Hexadecimal|int|string|null $node A 48-bit number representing the

     *     hardware address; this number may be represented as an integer or a

     *     hexadecimal string

     * @param int|null $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 1 UUID

     */

    public static function uuid1($node = null, ?int $clockSeq = null): UuidInterface

    {

        return self::getFactory()->uuid1($node, $clockSeq);

    }

    /**

     * Returns a version 2 (DCE Security) UUID from a local domain, local

     * identifier, host ID, clock sequence, and the current time

     *

     * @param int $localDomain The local domain to use when generating bytes,

     *     according to DCE Security

     * @param IntegerObject|null $localIdentifier The local identifier for the

     *     given domain; this may be a UID or GID on POSIX systems, if the local

     *     domain is person or group, or it may be a site-defined identifier

     *     if the local domain is org

     * @param Hexadecimal|null $node A 48-bit number representing the hardware

     *     address

     * @param int|null $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 (in a version 2 UUID, the lower 8 bits of this number

     *     are replaced with the domain).

     *

     * @return UuidInterface A UuidInterface instance that represents a

     *     version 2 UUID

     */

    public static function uuid2(

        int $localDomain,

        ?IntegerObject $localIdentifier = null,

        ?Hexadecimal $node = null,

        ?int $clockSeq = null

    ): UuidInterface {

        return self::getFactory()->uuid2($localDomain, $localIdentifier, $node, $clockSeq);

    }

    /**

     * Returns a version 3 (name-based) UUID based on the MD5 hash of a

     * namespace ID and a name

     *

     * @param string|UuidInterface $ns The namespace (must be a valid UUID)

     * @param string $name The name to use for creating a UUID

     *

     * @return UuidInterface A UuidInterface instance that represents a

     *     version 3 UUID

     *

     * @psalm-suppress ImpureMethodCall we know that the factory being replaced can lead to massive

     *                                  havoc across all consumers: that should never happen, and

     *                                  is generally to be discouraged. Until the factory is kept

     *                                  un-replaced, this method is effectively pure.

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     */

    public static function uuid3($ns, string $name): UuidInterface

    {

        return self::getFactory()->uuid3($ns, $name);

    }

    /**

     * Returns a version 4 (random) UUID

     *

     * @return UuidInterface A UuidInterface instance that represents a

     *     version 4 UUID

     */

    public static function uuid4(): UuidInterface

    {

        return self::getFactory()->uuid4();

    }

    /**

     * Returns a version 5 (name-based) UUID based on the SHA-1 hash of a

     * namespace ID and a name

     *

     * @param string|UuidInterface $ns The namespace (must be a valid UUID)

     * @param string $name The name to use for creating a UUID

     *

     * @return UuidInterface A UuidInterface instance that represents a

     *     version 5 UUID

     *

     * @psalm-pure note: changing the internal factory is an edge case not covered by purity invariants,

     *             but under constant factory setups, this method operates in functionally pure manners

     *

     * @psalm-suppress ImpureMethodCall we know that the factory being replaced can lead to massive

     *                                  havoc across all consumers: that should never happen, and

     *                                  is generally to be discouraged. Until the factory is kept

     *                                  un-replaced, this method is effectively pure.

     */

    public static function uuid5($ns, string $name): UuidInterface

    {

        return self::getFactory()->uuid5($ns, $name);

    }

    /**

     * Returns a version 6 (reordered time) UUID from a host ID, sequence number,

     * and the current time

     *

     * @param Hexadecimal|null $node A 48-bit number representing the hardware

     *     address

     * @param int|null $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(

        ?Hexadecimal $node = null,

        ?int $clockSeq = null

    ): UuidInterface {

        return self::getFactory()->uuid6($node, $clockSeq);

    }

    /**

     * Returns a version 7 (Unix Epoch time) UUID

     *

     * @param DateTimeInterface|null $dateTime An optional date/time from which

     *     to create the version 7 UUID. If not provided, the UUID is generated

     *     using the current date/time.

     *

     * @return UuidInterface A UuidInterface instance that represents a

     *     version 7 UUID

     */

    public static function uuid7(?DateTimeInterface $dateTime = null): UuidInterface

    {

        $factory = self::getFactory();

        if (method_exists($factory, 'uuid7')) {

            /** @var UuidInterface */

            return $factory->uuid7($dateTime);

        }

        throw new UnsupportedOperationException(

            'The provided factory does not support the uuid7() method',

        );

    }

    /**

     * Returns a version 8 (custom) UUID

     *

     * The bytes provided may contain any value according to your application's

     * needs. Be aware, however, that other applications may not understand the

     * semantics of the value.

     *

     * @param string $bytes A 16-byte octet string. This is an open blob

     *     of data that you may fill with 128 bits of information. Be aware,

     *     however, bits 48 through 51 will be replaced with the UUID version

     *     field, and bits 64 and 65 will be replaced with the UUID variant. You

     *     MUST NOT rely on these bits for your application needs.

     *

     * @return UuidInterface A UuidInterface instance that represents a

     *     version 8 UUID

     */

    public static function uuid8(string $bytes): UuidInterface

    {

        $factory = self::getFactory();

        if (method_exists($factory, 'uuid8')) {

            /** @var UuidInterface */

            return $factory->uuid8($bytes);

        }

        throw new UnsupportedOperationException(

            'The provided factory does not support the uuid8() method',

        );

    }

}