Ramsey\Uuid Cookbook

juliusstoerrle edited this page Feb 16, 2017 · 14 revisions

Overriding the default time UUID generator

When generating time-based (version 1) UUIDs, ramsey/uuid will default to the Generator\DefaultTimeGenerator time generator. In a best-case scenario for the environment, this defaults to use the Provider\Node\SystemNodeProvider, Converter\Time\PhpTimeConverter, and Provider\Time\SystemTimeProvider to generate a time-based UUID. However, any of these may be replaced to generate a time-based UUID according to your needs.

For example:

$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setTimeGenerator(new \Ramsey\Uuid\Generator\DefaultTimeGenerator(
    new \MyVendor\Uuid\NodeProvider(),
    new \MyVendor\Uuid\TimeConverter(),
    new \MyVendor\Uuid\TimeProvider()
));
\Ramsey\Uuid\Uuid::setFactory($uuidFactory);

$uuid = \Ramsey\Uuid\Uuid::uuid1();

Use the PECL UUID PHP extension to generate time-based UUIDs

It's possible to use the PECL UUID PHP extension with this library to generate bytes for version 1 UUIDs.

If you have the UUID extension installed, you may use the following to configure this library to use it:

$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setTimeGenerator(new \Ramsey\Uuid\Generator\PeclUuidTimeGenerator());
\Ramsey\Uuid\Uuid::setFactory($uuidFactory);

$uuid = \Ramsey\Uuid\Uuid::uuid1();

Now, instead of using the system time values generated by this library, $uuid was generated using the PECL UUID extension.

Overriding the default random UUID generator

When generating random (version 4) UUIDs, ramsey/uuid will default to a fallback approach through the following random generators:

  1. If running on PHP 7+, it will use random_bytes() (see Generator\RandomBytesGenerator)
  2. If running on PHP 5.6 and earlier, it uses the paragonie/random_compat, which steps through a variety of random generators, if available on the system—libsodium, /dev/urandom, mcrypt, or CAPICOM (on Windows).

This fallback behavior may be overridden by explicitly setting the random generator to use. We are able to do this by instantiating a new UuidFactory and configuring it to use the appropriate generator. For example, to explicitly set ramsey/uuid to use libsodium for generating random bytes, we would use the following code:

$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setRandomGenerator(new \Ramsey\Uuid\Generator\SodiumRandomGenerator());
\Ramsey\Uuid\Uuid::setFactory($uuidFactory);

$uuid = \Ramsey\Uuid\Uuid::uuid4();

Now, $uuid contains a Ramsey\Uuid\Uuid object representing a version 4 UUID generated using bytes from Sodium\randombytes_buf().

Use ircmaxell/random-lib to generate random UUIDs

The ramsey/uuid has built-in support to use ircmaxell/random-lib for generating random bytes for version 4 UUIDs through the use of the Generator\RandomLibAdapter class.

$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setRandomGenerator(new \Ramsey\Uuid\Generator\RandomLibAdapter());
\Ramsey\Uuid\Uuid::setFactory($uuidFactory);

$uuid = \Ramsey\Uuid\Uuid::uuid4();

Now, $uuid contains a Ramsey\Uuid\Uuid object representing a version 4 UUID generated using bytes from ircmaxell/random-lib.

By default, RandomLibAdapter uses a medium-strength generator. If you'd like to use a different strength, you may do so like this:

$randomLibFactory = new \RandomLib\Factory();
$randomLibGenerator = $randomLibFactory->getHighStrengthGenerator();
$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setRandomGenerator(
    new \Ramsey\Uuid\Generator\RandomLibAdapter($randomLibGenerator)
);

$uuid = \Ramsey\Uuid\Uuid::uuid4();

This time, we generated the $uuid using bytes from a high strength generator, provided by ircmaxell/ramdom-lib.

Use the PECL UUID PHP extension to generate random UUIDs

It's possible to use the PECL UUID PHP extension with this library to generate random bytes for version 4 UUIDs.

If you have the UUID extension installed, you may use the following to configure this library to use it:

$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setRandomGenerator(new \Ramsey\Uuid\Generator\PeclUuidRandomGenerator());
\Ramsey\Uuid\Uuid::setFactory($uuidFactory);

$uuid = \Ramsey\Uuid\Uuid::uuid4();

In this instance, we generate $uuid using bytes from the PECL UUID extension.

Using OpenSSL

While this library provides an OpenSSL generator for generating random bytes with openssl_random_pseudo_bytes(), it is no longer provided as a default option due to OpenSSL's random fork-safety issue. If not using PHP in a forked environment (i.e. Apache, PHP-FPM, etc.), then it is safe to use the OpenSSL generator.

See also issue #80 for the full discussion regarding UUID collisions encountered when using OpenSSL as a generator in environments with forked PHP processes.

Use your own random generator!

While not recommended, there may be cases where you need to use your own random generator to generate bytes to create UUIDs. The ramsey/uuid library is flexible to allow you do this.

The first step is to create a class that implements Generator\RandomGeneratorInterface:

namespace MyVendor\Uuid;

class MyRandomGenerator implements \Ramsey\Uuid\Generator\RandomGeneratorInterface
{
    public function generate($length)
    {
        // Your code to generate $length bytes of data
        return $bytes;
    }
}

Now that you have a generator, you may inject it into ramsey/uuid, like this:

$uuidFactory = new \Ramsey\Uuid\UuidFactory();
$uuidFactory->setRandomGenerator(new \MyVendor\Uuid\MyRandomGenerator());
\Ramsey\Uuid\Uuid::setFactory($uuidFactory);

$uuid = \Ramsey\Uuid\Uuid::uuid4();

Here, $uuid was created using bytes generated by your own random generator.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.