-
Notifications
You must be signed in to change notification settings - Fork 0
/
manual.html
executable file
·275 lines (259 loc) · 17.6 KB
/
manual.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>DrUUID RFC 4122 library manual</title>
<meta name="author" content="J. King">
<link rel="stylesheet" type="text/css" href="http://jkingweb.ca/code/documentation.css">
<link rel="author" href="http://jkingweb.ca/">
<link rel="up" href="http://jkingweb.ca/code/">
</head>
<body>
<h1>DrUUID RFC 4122 library manual</h1>
<div id="preface">
<h2>Preface</h2>
<p>"DrUUID" (<i>ˈdɹː.ɪd</i>) is an implementation for PHP5 of---and associated API for---the data format described in <a href="http://tools.ietf.org/html/rfc4122">RFC 4122</a>, <i>A Universally Unique IDentifier (UUID) URN Namespace</i>. It is able to mint new UUIDs, import existing UUIDs, extract information from UUIDs, and compare two UUIDs for bit-exact equality.
<p>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.
<p>Questions and comments are very welcome, and should be directed to the author via <a href="http://jkingweb.ca/">his Web site</a>.
<p><a href="http://jkingweb.ca/code/php/lib.uuid/download">Download current version</a> (<a href="http://jkingweb.ca/code/php/lib.uuid/archives">archives</a>)
</div>
<div id="contents">
<h2>Table of contents</h2>
<h3>Prefaces</h3>
<ol>
<li><a href="#preface">Preface</a>
<li><a href="#contents">Table of contents</a>
<li><a href="#features">Features</a>
<li><a href="#requirements">Requirements</a>
<li><a href="#conformance">Conformance exceptions</a>
</ol>
<h3>Body</h3>
<ol>
<li><a href="#note">Documentation note</a>
<li><a href="#api">The API</a>
<ol>
<li><a href="#api-mint">UUID::mint()</a>
<ol>
<li><a href="#api-mint-v1">Version 1</a>
<li><a href="#api-mint-v3">Version 3</a>
<li><a href="#api-mint-v4">Version 4</a>
<li><a href="#api-mint-v5">Version 5</a>
</ol>
<li><a href="#api-import">UUID::import()</a>
<li><a href="#api-compare">UUID::compare()</a>
<li><a href="#api-seq">UUID::seq()</a>
</ol>
<li><a href="#the-object">The UUID object</a>
<ol>
<li><a href="#the-object-properties">Public properties</a>
</ol>
<li><a href="#randomness">Sources for random numbers</a>
<ol>
<li><a href="#randomness-initrandom">UUID::initRandom()</a>
</ol>
</ol>
<h3>Appendices</h3>
<ol>
<li><a href="#append-namespaces">Predefined namespaces</a>
<li><a href="#append-credits">Credits and licensing</a>
<li><a href="#append-history">Revision history</a>
</ol>
</div>
<div id="features">
<h2>Features</h2>
<ul>
<li>Conforms to <a href="http://tools.ietf.org/html/rfc4122">RFC 4122</a> (with <a href="#conformance">exceptions</a>)
<li>Simple API
<li>Able to generate new UUIDs, import existing UUIDs, extract data from UUIDs and compare two UUIDs for equality
<li>Optionally draws random numbers from a system-dependent randomness source
</ul>
</div>
<div id="requirements">
<h2>Requirements</h2>
<ul>
<li>PHP 5.0 or later
</ul>
<p>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.
</div>
<div id="conformance">
<h2>Conformance exceptions</h2>
<ul>
<li>No stable storage is implemented. Stable storage may be implemented on top of DrUUID
<li>Random numbers are not guaranteed to be generated from a cryptographically secure source
<li>Conversion of large-integer timestamp on 32-bit systems to and from floating-point may introduce minor rounding errors
</ul>
<div id="note">
<h2>Documentation note</h2>
<p>This manual often makes references to <dfn>binary and hexdecimal strings</dfn> for input and output. For the sake of simplicity please assume that such strings are always in network order (big-endian).
<p id="note-uuid">For methods accepting <dfn>a UUID</dfn> as a parameter, the UUID may be:
<ul>
<li>in canonical form, with or without curly braces
<li>a 16-byte binary string (fastest)
<li>a 32-character hexadecimal string
<li>an RFC 4122 URN
<li>a <a href="#the-object"><code>UUID</code> object</a>
</ul>
<p>This manual often makes reference to <dfn>invalid UUIDs</dfn>. For simplicity this is merely any string more or less than 16 bytes long. DrUUID performs no other validation on UUIDs.
</div>
<div id="api">
<h2>The API</h2>
<p>The core DrUUID API consists of four static methods: <code>UUID::mint()</code>, <code>UUID::import()</code>, <code>UUID::compare()</code> as well as <code>UUID::seq()</code>. Of these <code>UUID::mint()</code> and <code>UUID::import()</code> return an instance of the <code>UUID</code> class.
<h3 id="api-mint">UUID::mint()</h3>
<div>
<p class="samp"><samp><var>UUID</var> UUID::mint( [<var>int version</var> [, ... ] )</samp>
<p>The <code>UUID::mint()</code> 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.
<h4 id="api-mint-v1">Version 1</h4>
<p class="samp">
<samp><var>UUID</var> UUID::mint( <var>void</var> )</samp>
<br>
<samp><var>UUID</var> UUID::mint( 1 [, <var>string node</var>, [, <var>string sequence</var> [, <var>float time</var> ]]] )</samp>
<p>Version 1 UUIDs (the default type) are generated based on the current time and a MAC address (called a <i>node</i>).
<p>If specified, <var>node</var> should be either an 8-byte binary string or a 16-character hexadecimal string (with or without separators) representing a MAC address. Any other value will generate a random node. DrUUID does not attempt to detect the host's MAC address.
<p>The <var>sequence</var> argument specifies a clock sequence and should be a two-byte binary string. If an invalid value is provided, a random sequence will be used. This allows for the implementation of stable storage on top of DrUUID. Please consult <a href="http://www.apps.ietf.org/rfc/rfc4122.html#sec-4.1.5">Section 4.1.5</a> and <a href="http://www.apps.ietf.org/rfc/rfc4122.html#sec-4.2">Section 4.2</a> for guidance on the usage and purpose of clock sequences. For convenience, a random clock sequence may be manually generated using the <code>UUID::seq()</code> method.
<p>Finally, the <var>time</var> argument may be specified to employ a past or future time (as a Unix timestamp with microseconds like that returned by <code>microtime(<var>true</var>)</code> for example) instead of the curent time. This should only be used for debugging and never used to generate UUIDs for any purpose but testing.
<h4 id="api-mint-v3">Version 3</h4>
<p class="samp"><samp><var>UUID</var> UUID::mint( 3, <var>string name</var>, <var>mixed namespace</var> )</samp>
<p>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.
<p>The <var>name</var> argument is an arbitrary name and should be in a binary form appropriate for <var>namespace</var>. 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.
<p>The <var>namespace</var> argument is itself <a href="#note-uuid">a UUID</a>; invalid UUIDs will throw an exception. A list of provided namespaces is available in <a href="#append-namespaces">appendix A</a>.
<p>Note that the continued use of Version 3 UUIDs is discouraged: Version 5 UUIDs should be used instead whenever possible.
<h4 id="api-mint-v4">Version 4</h4>
<p class="samp"><samp><var>UUID</var> UUID::mint( 4 )</samp>
<p>Version 4 UUIDs are generated from random numbers. Save for embedded version information they are completely random.
<h4 id="api-mint-v5">Version 5</h4>
<p class="samp"><samp><var>UUID</var> UUID::mint( 5, <var>string name</var>, <var>mixed namespace</var> )</samp>
<p>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.
<p>The <var>name</var> argument is an arbitrary name and should be in a binary form appropriate for <var>namespace</var>. 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.
<p>The <var>namespace</var> argument is itself <a href="#note-uuid">a UUID</a>; invalid UUIDs will throw an exception. A list of provided namespaces is available in <a href="#append-namespaces">appendix A</a>.
<p>Version 5 UUIDs are preferred over Version 3 UUIDs.
</div>
<h3 id="api-import">UUID::import()</h3>
<div>
<p class="samp"><samp><var>UUID</var> UUID::import( <var>string uuid</var> )</samp>
<p>The <code>UUID::import()</code> method imports <a href="#note-uuid">a UUID</a> string as a <code>UUID</code> object. Invalid UUIDs will throw an exception. Note that while it will take a <code>UUID</code> object as input, this is <em>not</em> a no-op.
</div>
<h3 id="api-compare">UUID::compare()</h3>
<div>
<p class="samp"><samp><var>bool</var> UUID::compare( <var>mixed uuid1</var>, <var>mixed uuid2</var> )</samp>
<p>The <code>UUID::compare()</code> method compares <a href="#note-uuid">two UUIDs</a> for equivalency. If both UUIDs, as binary numbers, are equal, the method returns <samp>TRUE</samp>. The method will also return <samp>TRUE</samp> if neither arguments is a valid UUID.
<p>This method is useful for determining if two different UUID representations (eg. canonical string, lowercase hex string, uppercase hex string, binary, URN) are in fact the same UUID.
</div>
<h3 id="api-seq">UUID::seq()</h3>
<div>
<p class="samp"><samp><var>string</var> UUID::seq( <var>void</var> )</samp>
<p>The <code>UUID::seq()</code> method generates a random clock sequence for <a href="#api-mint-v1">Version 1 UUIDs</a>. The method returns two random bytes.
</div>
</div>
<div id="the-object">
<h2>The UUID object</h2>
<p><code>UUID</code> objects cannot be instantiated manually; they must be created via <code>UUID::mint()</code> or <code>UUID::import()</code>. When cast to a string a <code>UUID</code> object will be rendered in the canonical string form (eg. <samp>550e8400-e29b-41d4-a716-446655440000</samp>). They have no public methods, but do have a number of public properties:
<h3 id="the-object-properties">Public properties</h3>
<div>
<dl>
<dt>bytes
<dd>A 16-byte binary string representation of the UUID.
<dt>hex
<dd>A 32-character hexadecimal representation of the UUID. Neither octets nor fields are ever padded and high digits are always lowercased.
<dt>string
<dd>The canonical string representation of the UUID, with high hexadecimal digits always lowercased.
<dt>urn
<dd>The UUID formatted as an URN.
<dt>version
<dd>The UUID's version (eg. 1, 3, 4, 5).
<dt>variant
<dd>The UUID's variant. For RFC 4122 UUIDs this is always <samp>1</samp>.
<dt>node
<dd>The MAC address associated with the UUID. Only applicable to Version 1 identifiers.
<dt>time
<dd>The time at which the UUID was generated, as a floating-point Unix timestamp with microseconds. Only applicable to Version 1 identifiers.
</dl>
</div>
<div id="randomness">
<h2>Sources for random numbers</h2>
<p>PHP has a number of good sources for random numbers available to it, but most are either system-dependent, incur considerable overhead, or both. Consequently DrUUID uses the <code>mt_rand()</code> function to generate random numbers unless instructed to seek an alternative, usually cryptographically secure source. As of this writing random bytes may be drawn from <code>/dev/urandom</code> on Unix systems or <a href="http://msdn.microsoft.com/en-us/library/aa388182(VS.85).aspx">CAPICOM's GetRandom method</a> on Windows; other sources may be added in future. In order to use an alternative source the <code>UUID::initRandom()</code> static method must be invoked.
<h3 id="randomness-initrandom">UUID::initRandom()</h3>
<div>
<p class="samp">
<samp><var>string</var> UUID::initRandom( <var>void</var> )</samp>
<p>The <code>UUID::initRandom()</code> method need only be called once; subsequent calls are harmless other than incurring the same performance penalty each time.
<p>The return value is a string containing the name of the private method which will be used to gather random numbers. It is purely advisory, and return values may change in future versions.
</div>
<p>Note that since the characteristics of any given system can be unpredictably different from those of another, users are encouraged to run their own benchmarks to ascertain whether the performance of both <code>UUID::initRandom()</code> and calls thereafter to <code>UUID::randomBytes()</code> warrant an alternative source's use.
</div>
<div id="append-namespaces">
<h2>Predefined namespaces</h2>
<p><a href="http://tools.ietf.org/html/rfc4122#appendix-C">Appendix C of RFC 4122</a> lists a number of "potentially interesting" namespaces. For convenience DrUUID includes these namespaces as class constants:
<table>
<caption>Namespace constants</caption>
<thead>
<tr>
<th>Constant
<th>Namespace description
<th>UUID
<tbody>
<tr>
<td><code>UUID::nsDNS</code>
<td>DNS hostnames (eg. "www.example.com")
<td><samp>6ba7b810-9dad-11d1-80b4-00c04fd430c8</samp>
<tr>
<td><code>UUID::nsURL</code>
<td>Any valid URL (eg. "http://www.example.com/example.html")
<td><samp>6ba7b811-9dad-11d1-80b4-00c04fd430c8</samp>
<tr>
<td><code>UUID::nsOID</code>
<td>An ISO Object Identifier
<td><samp>6ba7b812-9dad-11d1-80b4-00c04fd430c8</samp>
<tr>
<td><code>UUID::nsX500</code>
<td>An X.500 Distinguished Name
<td><samp>6ba7b814-9dad-11d1-80b4-00c04fd430c8</samp>
</table>
</div>
<div id="append-credits">
<h2>Credits and licensing</h2>
<p>DrUUID and its manual (ie. this document) were written by <a href="http://jkingweb.ca/">J. King</a>. They are both covered by the following license:
<pre>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.</pre>
<p>This manual's stylesheet was written by <a href="http://dustinwilson.com/">Dustin Wilson</a>. It is licensed under the <a href="http://creativecommons.org/licenses/by/2.5/">Creative Commons Attribution</a> license (v2.5).
<p>This software is dedicated to <a href="http://www.insani.org/">Seung Park</a>. HLN <em>forever</em>!
</div>
<h2 id="append-history">Revision history</h2>
<dl>
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20110320">2011-03-20</a>
<dd>Refined the generation of Version 1 UUIDs. This sees the addition of the <var>sequence</var> and <var>time</var> parameters to <code>UUID::mint(<var>1</var>)</code>, as well as the addition of <code>UUID::seq()</code>.
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20100215">2010-02-15</a>
<dd>Fixed bug in <code>UUID::import</code> as reported by Sander van Lambalgen.
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20091126">2009-11-26</a>
<dd>Fixed previously non-functional <code>UUID::compare()</code> method. Also allowed input UUIDs to be RFC 4122 URNs.
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20091111">2009-11-11</a>
<dd>Various changes:
<ul>
<li>Implemented the <code>UUID::initRandom()</code> method. See <a href="#randomness">Section 4</a> for details. As a consequence generating random numbers is now much faster. Acknowledgement to Rubén Marrero for the impulse to implement this.
<li>Implemented system-level randomness source for Windows.
<li>Fixed a minor unnecessary processing branch when attempting to retrieve node value from non-version 1 UUIDs.
<li>Various documentation corrections and clarifications; numerous fixed typos.
</ul>
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20090928">2009-09-28</a>
<dd>Fixed a minor bug preventing <code>/dev/urandom</code> from being used. Reported by Rubén Marrero.
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20090413">2009-04-13</a>
<dd>Fixed two serious bugs in Version 5 generation and string casting.
<dt><a href="http://jkingweb.ca/code/php/lib.uuid/archives?rev=20090411">2009-04-11</a>
<dd>First release.
</dl>