P4Cms_Uuid Class Reference

Encapsulates and generates a UUID (Universally Unique IDentifier). More...

List of all members.

Public Member Functions
	__toString ()
	Automatically return the UUID string when cast to a string.
	get ()
	Get the UUID.
	isValid ($uuid)
	Determine if the given string is a valid UUID.
	set ($uuid)
	Set an arbitrary UUID or clear the existing one.
Static Public Member Functions
static	fromMd5 ($md5)
	Returns a UUID instnace where the passed md5 string has been formatted as a UUID and can be retrieved by calling 'get'.
Protected Member Functions
	_md5ToUuid ($md5)
	Formats the passed 32 character hex md5 as a UUID by insert hyphen '-' characters appropriately.
Protected Attributes
	$_uuid = null

---

Detailed Description

Encapsulates and generates a UUID (Universally Unique IDentifier).

Casting a new UUID object to a string will automatically generate and return a UUID. For example:

print new P4Cms_Uuid; // outputs: 550e8400-e29b-41d4-a716-446655440000

Copyright:

2011-2012 Perforce Software. All rights reserved

License:

Please see LICENSE.txt in top-level folder of this distribution.

Version:

2012.2/486814

---

Member Function Documentation

P4Cms_Uuid::__toString

(

)

Automatically return the UUID string when cast to a string.

Returns:

string a generated or explicitly set UUID (in lower-case)

    {
        return $this->get();
    }

P4Cms_Uuid::_md5ToUuid

(

$

md5

)

[protected]

Formats the passed 32 character hex md5 as a UUID by insert hyphen '-' characters appropriately.

Parameters:

string

$md5

the 32 character hex formatted md5 to uuid'ize

Returns:

string the uuid formatted result

    {
        return substr($md5,  0,  8) . '-'
             . substr($md5,  8,  4) . '-'
             . substr($md5, 12,  4) . '-'
             . substr($md5, 16,  4) . '-'
             . substr($md5, 20, 12);
    }

static P4Cms_Uuid::fromMd5

(

$

md5

)

[static]

Returns a UUID instnace where the passed md5 string has been formatted as a UUID and can be retrieved by calling 'get'.

Parameters:

string

$md5

an md5 hash

Returns:

P4Cms_UUID a uuid instance utilizing the passed md5

Exceptions:

InvalidArgumentException

if input is not a 32 character hex string

    {
        if (!is_string($md5) || !preg_match('/[a-z0-9]{32}/i', $md5)) {
            throw new InvalidArgumentException(
                "Cannot create UUID from passed value. Value must be a 32 character hex string."
            );
        }

        $uuid = new static;
        $uuid->set($uuid->_md5ToUuid($md5));

        return $uuid;
    }

P4Cms_Uuid::get

(

)

Get the UUID.

If no UUID is presently set, a new one will be generated.

Returns:

string a generated or explicitly set UUID (in lower-case)

    {
        // if we don't have a uuid yet, generate one.
        if (!$this->_uuid) {
            $chars = md5(uniqid(mt_rand(), true));
            $uuid  = $this->_md5ToUuid($chars);

            $this->_uuid = $uuid;
        }

        return $this->_uuid;
    }

P4Cms_Uuid::isValid

(

$

uuid

)

Determine if the given string is a valid UUID.

Characters a-z, 0-9 in the arrangement: 8-4-4-4-12

Parameters:

string

$uuid

the UUID to validate.

Returns:

bool true if the given UUID is valid; false otherwise.

    {
        // verify type.
        if (!is_string($uuid)) {
            return false;
        }

        // verify correct format.
        $pattern = "/^[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}$/i";
        return (bool) preg_match($pattern, $uuid);
    }

P4Cms_Uuid::set

(

$

uuid

)

Set an arbitrary UUID or clear the existing one.

Parameters:

string | null

$uuid

the UUID to hold or null to clear.

Returns:

P4Cms_Uuid provides fluent interface.

Exceptions:

InvalidArgumentException

if the input is not a valid string or null

    {
        if (!is_null($uuid) && !$this->isValid($uuid)) {
            throw new InvalidArgumentException(
                "Cannot set UUID. Must be a valid UUID string or null."
            );
        }

        // set (normalize to lower-case)
        $this->_uuid = strtolower($uuid);

        return $this;
    }

---

Member Data Documentation

P4Cms_Uuid::$_uuid = null [protected]

---

The documentation for this class was generated from the following file:

• Uuid.php