AaronSaray

I’ve been thinking more and more about having unique ID’s – especially with working with larger datasets – and I thought it was high time that I investigated the UUID.

The first time I ever heard about these was actually Microsoft’s implementation of the GUID in the CLSID sections of the windows registry. However, if you check out the RFC for UUID, you’ll see that’s just one of the uses and types.

My chosen UUID is V4 in PHP. I checked out the php.net/uniqid page and reviewed the comments. I still had a few questions, but settled on one example. Lets dissect this now…

UUID is Hex

So, lets make sure we fully understand our integer formats http://us2.php.net/manual/en/language.types.integer.php specifically our hexadecimal format: 0[xX][0-9a-fA-F]+ From this, we should start to think of our min and max ranges for our UUID in hex: between 0 and 0xFF…(many f’s).

The next thing I want to make sure is that PHP doesn’t convert my hex to something base 10 – so lets format it properly with the sprintf() function. Note the description of the last parameter:

x – the argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).

Excellent! So, now we can deal with Hex solely – and PHP is amazing because any function that works with integers, can work with Hex – as they are just a different base of integer (math wizards are going – duh aaron… I just like being verbose… )

The basic format of the UUID

The basic format of the UUID – and I’m talking real basic – is:

########-####-####-############ where # is a hexadecimal number.

Of course, those nodes actually mean something (per the rfc):

UUID = time-low “-” time-mid “-” time-high-and-version “-” clock-seq-and-reserved clock-seq-low “-” node

What makes this v4?

RFC states:

The version 4 UUID is meant for generating UUIDs from truly-random or pseudo-random numbers.

The algorithm is as follows:

o Set the two most significant bits (bits 6 and 7) of the clock_seq_hi_and_reserved to zero and one, respectively.

o Set the four most significant bits (bits 12 through 15) of the time_hi_and_version field to the 4-bit version number from Section 4.1.3.

o Set all the other bits to randomly (or pseudo-randomly) chosen values.

And 4.1.3 states the binary value of this:

0 1 0 0 version 4: The randomly or pseudo-randomly generated version specified in this document.

So, what that all means is that we need to set those bits properly in each sub section after we’ve generated our random number – doesn’t sound so bad. Just use the bitwise operator.

PHP and generating the random number

Ok – first off, lets generate some random numbers with mt_rand(). The middle two sections are not a problem what so ever… we’ll use use

1

mt_rand(0, 0xffff);

However, what about the next bigger one, the 8 digit one? Well, I’m using a windows machine in 32 bit – so I did a bit of math here:

1
2

var_dump(0xffffffff);
print mt_getmaxrand();

Outputs were: 4294967295 and 2147483647 respectively, so I know we’ll have to break that up. Basically, we’ll use 2 random numbers dash one random dash one random dash three random numbers. sprintf will take care of the padding.

Ok, putting it all together

The best example of all of this – and what I used to kind of reverse-engineer for this article, was from the PHP manual, check it out:

1
2
3
4
5

sprintf( '%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
        mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff ),
        mt_rand( 0, 0x0fff ) | 0x4000,
        mt_rand( 0, 0x3fff ) | 0x8000,
        mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff ), mt_rand( 0, 0xffff ) );

Simple enough, proper sprintf format, all the random number generators in place, and then the bitwise operators to set the bits properly.

So – with all that said, do YOU use a different way to generate a UUID in PHP – or do you think this is the best one?

Simple enough question. Lets check out some test code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php
class TEST
{
    public function __construct($arguments)
    {
        print "constructed with: {$arguments}";
    }
 
    public function __call($name, $arguments)
    {
        print "called {$name} with: {$arguments}";
    }
}
 
new TEST('hi');

Ran the first time, the output was:

constructed with: hi

Ran without a constructor?
BLANK. __call is not called.

Now we can all sleep at night! whew!

Date formats – How time makes pretty

The PHP Date manual page has a ton of interesting features to format the date that you can display to the user. However, when you look closer at it, there are actually some really useful modifiers that will help us with our date calculations as well. For the longest time, I had just used the time() function and let the pieces fall. This was OK when the offset was similar to my own timezone – but servers change locations – and websites have global audiences. The date and gmdate functions can help with this. Both functions take an optional timestamp parameter. If you do not specify this, they’ll calculate based off of the current date. This actually becomes quite useful for our calculations… Lets jump in.

date – the date on your current server

The date() function’s default timezone is based on your server’s timezone (or php.ini’s, etc…). Regardless of where that timezone is set, it uses it to display/retrieve a localized version of the time. For example, if it were noon in GMT, and your server was in central time, if you used date() to retrieve the time, it would display a time equavalent to noon – 6 hours – so 6am. (Holy run-on sentence, batman!)

When I say displays the time equivalent, this is because of the first parameter of date’s behavior. When you review the man page, you’ll see many different ways to display the time – including some common RFC based ones.

Generally, I shy away from using date() unless I really have to. I feel it gives a bias to the output because of its timezone centric behavior.

How do we not do that??

gmdate – the date in Greenwich Mean Time

Unless you live under a rock, you know that GMT is the basis of our timezones. You are either ahead or behind them via half hours and full hours, incrementally from the distance to that location. This obviously is to balance out for the earth’s rotation – duh – enough with the 3rd grade lecture…

gmdate takes the format of the date function as well, but its default offset is ‘0′. This is especially useful if you do not send in a timestamp because it will grab the current time off the server and display it based off of the GMT (not central time for my server, perhaps eastern time for yours, etc, etc). Normally, when storing date formats, you will always be storing them in GMT to have a common base format. This function is useful because it can show you exactly, accurately what the value is that you’re storing.

So, now we know we have two functions that do rather similar things, its time to find out how to actually get them something to work with.

time – current time measured in seconds

Ok – so we have date and gmdate which take optional second parameters of a timestamp – so how do we pump them full of information besides the current time? using time() of course! Time() returns the number of seconds since 1/1/70 0:0:0 GMT. Now, since this is the # of seconds from a GMT date, to a GMT date, its a perfect candidate for both functions! Want to see a nice display of a timestamp in GMT – the local method you may have stored it in? – send it into gmdate(). Want to see what that time that really was in your timezone? use date().

Ok – display and content – we’ve got them. Now, lets tie it all together in something that is useful to the end user and website.

Date Storage, User Information, and Display

Ok, so the biggest thing to remember, lets always store our time with the time() output – this gives us a proper and accurate GMT time, no need to worry about Daylight savings, moving servers, etc. (using datestamp/timestamp formats in mysql is a topic for a full other article – at this point, we’re just using an integer to store our dates). Ok, now with our proper GMT, lets always use gmdate() to format our date as well. This way, we never accidentally introduce a timezone offset to our date. We need two other things yet, is it daylight savings time – and what is the user’s timezone.

Daylight savings time can be returned using gmdate(‘I’) – which will give 1 if daylight savings, and 0 if not. This will equate to keeping the standard offset or adding an hour to it. For example, Central time is -6 offset, but with daylight savings time active, its +1 hour – so -5 offset. 1 small caveat, you may not need to use this calculation if that user’s timezone does not have DST.

Finally, the user’s offset. You should store this with the user record. For example, when storing my record, I would expect to see -6 for central time.

A real life code example

Ok, lets see our code now in practice.

First off, Aaron comes to the website at 7:30p jan 5th, 2009 Central (1:30AM on january 6th, 2009 GMT). He posts an entry.

1

mysql_query("insert into entries (title, body, authorID, datePosted) values ('$clean_title', '$clean_body', $authorID, time());

Now, the data we see looks like this:

ID | title | body                 | authorID | datePosted
----------------------------------------------------------
1  | yay!  | I like making posts! | 12       | 1231205400

Its also important to see my user row:

ID | name  | gmtOffset
----------------------
12 | aaron | -6

Lets see some code for displaying that entry localized for when I wrote it:

1
2
3
4
5
6
7
8
9

$authorID = 12;
$entryID = 1;
$author = new Author($authorID);
$entry = new Entry($entryID);
$dst = gmdate('I') ? 3600 : 0;
$datePosted = $author->gmtOffset * 3600 + $dst + $entry->datePosted;
 
print "{$entry->title}<hr />{$entry->body}<br /><em>Posted at ";
print gmdate("M/d/Y h:i:sa", $datePosted);

Lets do a quick run down of this code:
We have the authorID and the entryID set there just for reference. We make new objects based off of them – pretty simple mock-code almost.

Next, we calculate if daylight savings time is in effect. If it is, the function returns 1 – or true. If not, 0 or false. So our ternary operator either adds an hour to the offset for DST true, or does nothing for it being off. Finally, we calculate our date posted based off of the author’s gmt offset, whether dst is active, and what the gmt time of the entry was.