"DrUUID" (ˈdɹː.ɪd) is an implementation for PHP5 of---and associated API for---the data format described in RFC 4122, A Universally Unique IDentifier (UUID) URN Namespace. It is able to mint new UUIDs, import existing UUIDs, extract information from UUIDs, and compare two UUIDs for bit-exact equality.
The API is designed to be as simple as possible, with an implementation as accurate as practical given the limits of PHP. All other concerns, including PHP compatibility, efficiency and extensibility are secondary.
Questions and comments are very welcome, and should be directed to the author via his Web site.
/dev/urandom when possible
No other requirements are known to me. Behaviour may be erratic with PHP versions earlier than 5.1 due to bugs in string casting for objects.
This manual often makes references to binary and hexdecimal strings for input and output. For the sake of simplicity please assume that such strings are always in network order (big-endian).
The entire DrUUID API consists of consists of three static methods: UUID::mint(), UUID::import() and UUID::compare(). Of these UUID::mint() and UUID::import() return an instance of the UUID class.
UUID UUID::mint( [int version [, string node [, mixed namespace]]] )
The UUID::mint() method generates ("mints", like coinage) a new UUID. It is capable of producing Version 1 (time-based), Version 3 (MD5 hash-based), Version 4 (random) and Version 5 (SHA-1 hash-based) UUIDs. Its argument list is generic: required and optional argument depend upon the specified version to produce.
UUID UUID::mint( void )
UUID UUID::mint( 1 )
UUID UUID::mint( 1 [, string node] )
Version 1 UUIDs (the default type) are generated based on the current time and a MAC address (called a node).
If specified, node should be either an 8-byte binary string or a 16-nibble hexadecimal string (with or without separators). Any other value will generate a random node.
Due to the difficulties inherent in the process from PHP, DrUUID does not attempt to detect the host's MAC address.
UUID UUID::mint( 3, string name, mixed namespace )
Version 3 UUIDs are generated based upon a an MD5 hash of an arbitrary name and its associated name-space. For example the name "www.example.com" is within the DNS namespace, much as "Canada" is within a name-space of the world's countries. A name/namespace pair will predictably generate the same UUID.
The name argument is an arbitrary name and should be in a binary form appropriate for namespace. It is the responsibility of the user to assure the proper conversion to binary form. For many namespaces (like the DNS) the appropriate representation is plain text and therefore no conversion is required.
The namespace argument, itself a UUID, must be either a 16-byte binary string representation of a namespace, or a UUID object. Any other value will thrown an exception. A list of provided namespaces is available in appendix A.
Note that the continued use of Version 3 UUIDs is discouraged: Version 5 UUIDs should be used instead whenever possible.
UUID UUID::mint( 4 )
Version 4 UUIDs are generated from random numbers. Save for embedded version information they are completely random.
UUID UUID::mint( 5, string name, mixed namespace )
Version 5 UUIDs are generated based upon a an SHA-1 hash of an arbitrary name and its associated name-space. For example the name "www.example.com" is within the DNS namespace, much as "Canada" is within a name-space of the world's countries. A name/namespace pair will predictably generate the same UUID.
The name argument is an arbitrary name and should be in a binary form appropriate for namespace. It is the responsibility of the user to assure the proper conversion to binary form. For many namespaces (like the DNS) the appropriate representation is plain text and therefore no conversion is required.
The namespace argument, itself a UUID, must be either a 16-byte binary string representation of a namespace, or a UUID object. Any other value will thrown an exception. A list of provided namespaces is available in appendix A.
Version 5 UUIDs are preferred over Version 3 UUIDs.
UUID UUID::import( string uuid )
The UUID::import() method imports a UUID string as a UUID object. uuid may be either a 16-byte binary string, or a 32-nibble hexadecimal string (with or without separators or curly braces). It may also be a UUID object, though this is of questionable usefulness. Anything else with throw an exception.
UUID UUID::compare( mixed uuid1, mixed uuid2 )
The UUID::compare() method compares two UUIDs for equivalency. If both UUIDs, as binary numbers, are equal, the method returns TRUE. The method will also return TRUE if neither arguments is a valid UUID.
Either argument may be either a UUID object, a 16-byte binary string, or a 32-nibble hexdecimal string (with or without separators or curly braces).
UUID objects cannot be instantiated manually; they must be created via UUID::mint() or UUID::import(). When cast to a string a UUID object will be rendered in the canonical string form (eg. 550e8400-e29b-41d4-a716-446655440000). They have no public methods, but do have a number of public properties:
Appendix C of RFC 4122 lists a number of "potentially interesting" namespaces. For convenience DrUUID includes these namespaces as class constants:
| Constant | Namespace description | UUID |
|---|---|---|
UUID::nsDNS
| DNS hostnames (eg. "www.example.com") | 6ba7b810-9dad-11d1-80b4-00c04fd430c8 |
UUID::nsURL
| Any valid URL (eg. "http://www.example.com/example.html") | 6ba7b811-9dad-11d1-80b4-00c04fd430c8 |
UUID::nsOID
| An ISO Object Identifier | 6ba7b812-9dad-11d1-80b4-00c04fd430c8 |
UUID::nsX500
| An X.500 Distinguished Name | 6ba7b814-9dad-11d1-80b4-00c04fd430c8 |
DrUUID and its manual (ie. this document) were written by J. King. They are both covered by the following license:
Copyright (c) 2009 J. King Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
This manual's stylesheet was written by Dustin Wilson. It is licensed under the Creative Commons Attribution license (v2.5).
This software is dedicated to Seung Park. HLN forever!