From 5c3d327889636bc61ead15b72ca91ae0e43af562 Mon Sep 17 00:00:00 2001
From: Dave Hall <dave.hall@skwashd.com>
Date: Sun, 28 Aug 2011 00:59:42 +1000
Subject: [PATCH 3/3] more RFC compliant UUID generator and docs

---
 includes/uuid.inc          |  121 ++++++++++++++++++++++++++++++++++++++++++++
 modules/system/system.test |   40 ++++++++++++++
 2 files changed, 161 insertions(+), 0 deletions(-)
 create mode 100644 includes/uuid.inc

diff --git a/includes/uuid.inc b/includes/uuid.inc
new file mode 100644
index 0000000..13230ba
--- /dev/null
+++ b/includes/uuid.inc
@@ -0,0 +1,121 @@
+<?php
+
+/**
+ * @file
+ * Handling of universally unique identifiers.
+ */
+
+/**
+ * Interface that defines an UUID plugin.
+ */
+interface UuidInterface {
+
+  /**
+   * Generates an universally unique identifier.
+   *
+   * @return
+   *   An UUID, made up of 32 hex digits and 4 hyphens.
+   */
+  public function generate();
+
+}
+
+/**
+ * Factory class that determines which UUID implementation to use, and uses
+ * that to generate and validate UUIDs.
+ */
+class Uuid {
+
+  /**
+   * Holds the UUID implementation.
+   */
+  protected $plugin;
+
+  /**
+   * This constructor figures out which UUID implementation to use.
+   */
+  public function __construct() {
+    $class = variable_get('uuid_class', 'UuidPhp');
+    $this->plugin = new $class();
+  }
+
+  /**
+   * Generates an universally unique identifier.
+   *
+   * @see UuidInterface::generate()
+   */
+  public function generate() {
+    return $this->plugin->generate();
+  }
+
+  /**
+   * Check that a string appears to be in the format of a UUID.
+   *
+   * Plugins should not implement validation, since UUIDs should be in a
+   * consistent format across all plugins.
+   *
+   * @param $uuid
+   *   The string to test.
+   * @return
+   *   TRUE if the string is well formed.
+   */
+  public function isValid($uuid) {
+    return preg_match("/^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$/", $uuid);
+  }
+}
+
+/**
+ * UUID implementation using the PECL extension.
+ */
+class UuidPecl implements UuidInterface {
+  public function generate() {
+    return uuid_create(UUID_TYPE_DEFAULT);
+  }
+}
+
+/**
+ * UUID implementation using the Windows internal GUID extension.
+ *
+ * @see http://php.net/com_create_guid
+ */
+class UuidCom implements UuidInterface {
+  public function generate() {
+    // Remove {} wrapper and make lower case to keep result consistent.
+    return drupal_strtolower(trim(com_create_guid(), '{}'));
+  }
+}
+
+/**
+ * Generates an UUID v4 using PHP code.
+ *
+ * Loosely based on Ruby's UUIDTools generate_random logic.
+ *
+ * @see http://uuidtools.rubyforge.org/api/classes/UUIDTools/UUID.html
+ */
+class UuidPhp implements UuidInterface {
+  public function generate() {
+    $hex = substr(hash('sha256', drupal_random_bytes(16)), 0, 32);
+
+    // The field names refer to RFC 4122 section 4.1.2.
+    $time_low = substr($hex, 0, 8);
+    $time_mid = substr($hex, 8, 4);
+
+    $time_hi_and_version = base_convert(substr($hex, 12, 4), 16, 10);
+    $time_hi_and_version &= 0x0FFF;
+    $time_hi_and_version |= (4 << 12);
+
+    $clock_seq_hi_and_reserved = base_convert(substr($hex, 16, 4), 16, 10);
+    $clock_seq_hi_and_reserved &= 0x3F;
+    $clock_seq_hi_and_reserved |= 0x80;
+
+    $clock_seq_low = substr($hex, 20, 2);
+    $nodes = substr($hex, 20);
+
+    $uuid = sprintf('%s-%s-%04x-%02x%02x-%s',
+      $time_low, $time_mid, 
+      $time_hi_and_version, $clock_seq_hi_and_reserved,
+      $clock_seq_low, $nodes);
+
+    return $uuid;
+  }
+}
diff --git a/modules/system/system.test b/modules/system/system.test
index 9944619..dfd8a46 100644
--- a/modules/system/system.test
+++ b/modules/system/system.test
@@ -2466,3 +2466,43 @@ class SystemIndexPhpTest extends DrupalWebTestCase {
   }
 }
 
+/**
+ * Tests uuid.inc and related functions.
+ */
+class UuidTestCase extends DrupalWebTestCase {
+  public static function getInfo() {
+    return array(
+      'name' => 'UUID handling',
+      'description' => "Test the handling of universally unique identifiers.",
+      'group' => 'System',
+    );
+  }
+
+  /**
+   * Test UUID handling.
+   */
+  function testUuidHandling() {
+    // Initiate the generator. This will lazy-load uuid.inc.
+    $uuid = new Uuid();
+
+    // This is a valid UUID, we know that.
+    $valid_uuid = '0ab26e6b-f074-4e44-9da6-1205fa0e9761';
+    $invalid_uuid1 = '0ab26e6b-f074-4e44-9da6-1205fa0e976';
+    $invalid_uuid2 = '0ab26e6b-f074-4e44-9da-1205fa0e9761';
+    // Test the uuid_is_valid() function.
+    $test = (
+      $uuid->isValid($valid_uuid)
+      && !$uuid->isValid($invalid_uuid1)
+      && !$uuid->isValid($invalid_uuid2)
+    );
+    $this->assertTrue($test, 'UUID validation works.');
+
+    // Test generating an uuid.
+    $uuid1 = $uuid->generate();
+    $this->assertTrue($uuid->isValid($uuid1), 'UUID generation works.');
+
+    // Just to demonstrate the purpose of the UUID functionality.
+    $uuid2 = $uuid->generate();
+    $this->assertNotEqual($uuid1, $uuid2, 'Same UUID was not generated twice.');
+  }
+}
-- 
1.7.4.1