mirror of
https://github.com/ramsey/uuid.git
synced 2026-06-15 16:07:55 +03:00
Ben Ramsey
157 lines
4.6 KiB
ReStructuredText
157 lines
4.6 KiB
ReStructuredText
.. _rfc4122.version1:
|
||
|
||
=====================
|
||
Version 1: Time-based
|
||
=====================
|
||
|
||
A version 1 UUID uses the current time, along with the MAC address (or *node*)
|
||
for a network interface on the local machine. This serves two purposes:
|
||
|
||
1. You can know *when* the identifier was created.
|
||
2. You can know *where* the identifier was created.
|
||
|
||
In a distributed system, these two pieces of information can be valuable. Not
|
||
only is there no need for a central authority to generate identifiers, but you
|
||
can determine what nodes in your infrastructure created the UUIDs and at what
|
||
time.
|
||
|
||
.. tip::
|
||
It is also possible to use a **randomly-generated node**, rather than a
|
||
hardware address. This is useful for when you don't want to leak machine
|
||
information, while still using a UUID based on time. Keep reading to find
|
||
out how.
|
||
|
||
|
||
Default Mode
|
||
############
|
||
|
||
By default, ramsey/uuid will attempt to look up a MAC address for the machine it
|
||
is running on, using this value as the node. If it cannot find a MAC address, it
|
||
will generate a random node.
|
||
|
||
.. code-block:: php
|
||
|
||
use Ramsey\Uuid\Uuid;
|
||
|
||
$uuid = Uuid::uuid1();
|
||
|
||
printf(
|
||
"UUID: %s\nVersion: %d\nDate: %s\nNode: %s\n",
|
||
$uuid->toString(),
|
||
$uuid->getFields()->getVersion(),
|
||
$uuid->getDateTime()->format('r'),
|
||
$uuid->getFields()->getNode()->toString()
|
||
);
|
||
|
||
This will generate a version 1 UUID and print out its string representation, the
|
||
time the UUID was created, and the node used to create the UUID.
|
||
|
||
It will look something like this:
|
||
|
||
.. code-block:: text
|
||
|
||
UUID: e22e1622-5c14-11ea-b2f3-acde48001122
|
||
Version: 1
|
||
Date: Sun, 01 Mar 2020 23:32:15 +0000
|
||
Node: acde48001122
|
||
|
||
After creating a ``UuidInterface`` object from a string (or bytes), you can
|
||
check to see if it's a version 1 UUID by checking its instance type.
|
||
|
||
.. code-block:: php
|
||
|
||
use Ramsey\Uuid\Rfc4122\UuidV1;
|
||
use Ramsey\Uuid\Uuid;
|
||
|
||
$uuid = Uuid::fromString('200e43fa-5c14-11ea-bc55-0242ac130003');
|
||
|
||
if ($uuid instanceof UuidV1) {
|
||
printf(
|
||
"UUID: %s\nVersion: %d\nDate: %s\nNode: %s\n",
|
||
$uuid->toString(),
|
||
$uuid->getFields()->getVersion(),
|
||
$uuid->getDateTime()->format('r'),
|
||
$uuid->getFields()->getNode()->toString()
|
||
);
|
||
}
|
||
|
||
.. tip::
|
||
Check out the :php:interface:`Ramsey\\Uuid\\Rfc4122\\UuidInterface` API
|
||
documentation to learn more about what you can do with a ``UuidV1``
|
||
instance.
|
||
|
||
|
||
Random or Custom Node
|
||
#####################
|
||
|
||
You may override the default behavior by passing your own node value when
|
||
generating a version 1 UUID.
|
||
|
||
In the following example, we use ``RandomNodeProvider`` to generate a random
|
||
node, which we pass when creating the UUID.
|
||
|
||
.. code-block:: php
|
||
|
||
use Ramsey\Uuid\Provider\Node\RandomNodeProvider;
|
||
use Ramsey\Uuid\Uuid;
|
||
|
||
$nodeProvider = new RandomNodeProvider();
|
||
|
||
$uuid = Uuid::uuid1($nodeProvider->getNode());
|
||
|
||
You may also set the node value of your choice. In this example, we use
|
||
``StaticNodeProvider`` to do so.
|
||
|
||
.. code-block:: php
|
||
|
||
use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
|
||
use Ramsey\Uuid\Type\Hexadecimal;
|
||
use Ramsey\Uuid\Uuid;
|
||
|
||
$myCustomNode = new Hexadecimal('1234567890ab');
|
||
$nodeProvider = new StaticNodeProvider($myCustomNode);
|
||
|
||
$uuid = Uuid::uuid1($nodeProvider->getNode());
|
||
|
||
.. attention::
|
||
According to RFC 4122, nodes that do not identify the host should set the
|
||
unicast/multicast bit to one (``1``). This bit will never be set in IEEE 802
|
||
addresses obtained from network cards, so it helps to distinguish it from a
|
||
hardware MAC address.
|
||
|
||
``RandomNodeProvider`` and ``StaticNodeProvider`` of ramsey/uuid set this
|
||
bit for you, so they’re the easiest to use, but if you use a custom node
|
||
provider, be sure to set this bit.
|
||
|
||
See `RFC 4122, section 4.5 <https://tools.ietf.org/html/rfc4122#section-4.5>`_,
|
||
for more details.
|
||
|
||
|
||
Using the Factory
|
||
#################
|
||
|
||
It is possible to override the behavior of ``Uuid::uuid1()`` globally, by
|
||
overriding values on the ``FeatureSet`` and ``UuidFactory``.
|
||
|
||
For example, if you wish to always use a specific node whenever ``Uuid::uuid1()``
|
||
is called, you may do the following:
|
||
|
||
.. code-block:: php
|
||
|
||
use Ramsey\Uuid\FeatureSet;
|
||
use Ramsey\Uuid\Provider\Node\StaticNodeProvider;
|
||
use Ramsey\Uuid\Type\Hexadecimal;
|
||
use Ramsey\Uuid\Uuid;
|
||
use Ramsey\Uuid\UuidFactory;
|
||
|
||
$nodeProvider = new StaticNodeProvider(new Hexadecimal('1234567890ab'));
|
||
|
||
$featureSet = new FeatureSet();
|
||
$featureSet->setNodeProvider($nodeProvider);
|
||
|
||
$factory = new UuidFactory($featureSet);
|
||
|
||
Uuid::setFactory($factory);
|
||
|
||
$uuid = Uuid::uuid1();
|