mougrim/fast-uuid

A PHP library for generating and working with UUIDs faster than ramsey/uuid in many cases.

mougrim/fast-uuid is a PHP library for generating and working with universally unique identifiers (UUIDs).

mougrim/fast-uuid is based on the source code of ramsey/uuid and used it as a dependency, but it is faster in many cases.

Installation

The preferred method of installation is via Composer. Run the following command to install the package and add it as a requirement to your project's composer.json:

Documentation

Creating the factory:

If you want to use lazy initialization, create the factory in the following way:

After creating the factory, you can use it as ramsey/uuid, for example, to generate a UUID v7:

For more information, see the ramsey/uuid documentation.

Problem

ramsey/uuid is slow (sometimes very slow) when not using lazy initialization.

To use lazy initialization, you have to use static methods like Uuid::fromString(), Uuid::uuid7(), etc., with the default factory. If you use Uuid::getFactory() or change the default factory, you can't use lazy initialization.

So, if you want to use dependency injection (DI) or a non-default factory, you can't use the lazy initialization of ramsey/uuid.

mougrim/fast-uuid has a much faster non-lazy initialization than ramsey/uuid.

mougrim/fast-uuid has the same speed for lazy initialization as ramsey/uuid, but in cases where you need to unwrap a UUID (for example, to get the timestamp from it), mougrim/fast-uuid is much faster.

Benchmark

To run the benchmark, use the following command:

The result:

Transcript:

• bench* without the following Fast* and Lazy* is ramsey/uuid without lazy initialization
• benchLazy* is ramsey/uuid with lazy initialization
• benchFast* without the following String* or Bytes* is mougrim/fast-uuid where we can't use both string-based realization and bytes-based realization (can use only one of them) without lazy initialization
• benchFastString* is mougrim/fast-uuid string-based realization without lazy initialization
• benchFastBytes* is mougrim/fast-uuid bytes-based realization without lazy initialization
• benchLazy* is mougrim/fast-uuid string-based realization with lazy initialization (lazy initialization can't be bytes-based)

As you see, generation isn't optimized, but if needed you can make a MR 🙂

If you use only fromString and toString conversions, and you don't need DI and custom UUID factory, ramsey/uuid will be optimal for you.

In any other cases, it is better to use mougrim/fast-uuid with or without lazy initialization.

Restrictions

• only RFC-4122 and nonstandard UUID variants are supported
• GUID is not supported
• do not use checks like $uuid instanceof UuidV7, use $uuid->getVersion() or $uuid->getFields()->getVersion() to check the version
• string UUID should be in lowercase without 'urn:uuid:' and curly braces ('{' and '}') and should meet FastStringFields::VALID_PATTERN
• if you want to use lazy initialization or serialize/deserialize UUID, you have to use the FastUuidFactoryFactory::createAndSetFactory() method and only one instance of FastUuidFactory
• changing $codec (\Ramsey\Uuid\Codec\CodecInterface) is at your own risk, because in some places converting is used directly without $codec

Copyright and License

The mougrim/fast-uuid library is copyright © Mougrim and licensed for use under the MIT License (MIT). Please see license.md for more information.