From d975f0f143958b5a379c214df7cd1db6fab31a2e Mon Sep 17 00:00:00 2001 From: Ben Ramsey Date: Sun, 27 Sep 2015 13:02:30 -0500 Subject: [PATCH] Add docblocks for classes and interfaces in Ramsey\Uuid\Provider namespace --- src/Provider/Node/FallbackNodeProvider.php | 19 ++++++++++++++ src/Provider/Node/RandomNodeProvider.php | 13 ++++++++-- src/Provider/Node/SystemNodeProvider.php | 11 ++++++-- src/Provider/NodeProviderInterface.php | 9 +++++++ src/Provider/Time/FixedTimeProvider.php | 30 ++++++++++++++++++++++ src/Provider/Time/SystemTimeProvider.php | 8 ++++++ src/Provider/TimeProviderInterface.php | 8 +++++- 7 files changed, 93 insertions(+), 5 deletions(-) diff --git a/src/Provider/Node/FallbackNodeProvider.php b/src/Provider/Node/FallbackNodeProvider.php index 6340c1f..e230e17 100644 --- a/src/Provider/Node/FallbackNodeProvider.php +++ b/src/Provider/Node/FallbackNodeProvider.php @@ -16,15 +16,34 @@ namespace Ramsey\Uuid\Provider\Node; use Ramsey\Uuid\Provider\NodeProviderInterface; +/** + * FallbackNodeProvider attempts to gain the system host ID from an array of + * providers, falling back to the next in line in the event a host ID can not be + * obtained + */ class FallbackNodeProvider implements NodeProviderInterface { + /** + * @var NodeProviderInterface[] + */ private $nodeProviders; + /** + * Constructs a `FallbackNodeProvider` using an array of node providers + * + * @param NodeProviderInterface[] $providers Array of node providers + */ public function __construct(array $providers) { $this->nodeProviders = $providers; } + /** + * Returns the system node ID by iterating over an array of node providers + * and returning the first non-empty value found + * + * @return string System node ID as a hexadecimal string + */ public function getNode() { foreach ($this->nodeProviders as $provider) { diff --git a/src/Provider/Node/RandomNodeProvider.php b/src/Provider/Node/RandomNodeProvider.php index 8d8c0d5..1437bb6 100644 --- a/src/Provider/Node/RandomNodeProvider.php +++ b/src/Provider/Node/RandomNodeProvider.php @@ -16,12 +16,21 @@ namespace Ramsey\Uuid\Provider\Node; use Ramsey\Uuid\Provider\NodeProviderInterface; +/** + * RandomNodeProvider provides functionality to generate a random node ID, in + * the event that the node ID could not be obtained from the host system + * + * @link http://tools.ietf.org/html/rfc4122#section-4.5 + */ class RandomNodeProvider implements NodeProviderInterface { + /** + * Returns the system node ID + * + * @return string System node ID as a hexadecimal string + */ public function getNode() { - // if $node is still null (couldn't get from system), randomly generate - // a node value, according to RFC 4122, Section 4.5 return sprintf('%06x%06x', mt_rand(0, 1 << 24), mt_rand(0, 1 << 24)); } } diff --git a/src/Provider/Node/SystemNodeProvider.php b/src/Provider/Node/SystemNodeProvider.php index 3f10294..d3a27b3 100644 --- a/src/Provider/Node/SystemNodeProvider.php +++ b/src/Provider/Node/SystemNodeProvider.php @@ -16,8 +16,17 @@ namespace Ramsey\Uuid\Provider\Node; use Ramsey\Uuid\Provider\NodeProviderInterface; +/** + * SystemNodeProvider provides functionality to get the system node ID (MAC + * address) using external system calls + */ class SystemNodeProvider implements NodeProviderInterface { + /** + * Returns the system node ID + * + * @return string System node ID as a hexadecimal string + */ public function getNode() { static $node = null; @@ -43,8 +52,6 @@ class SystemNodeProvider implements NodeProviderInterface /** * Returns the network interface configuration for the system * - * @todo Needs evaluation and possibly modification to ensure this works - * well across multiple platforms. * @codeCoverageIgnore * @return string */ diff --git a/src/Provider/NodeProviderInterface.php b/src/Provider/NodeProviderInterface.php index 5dc842f..864e840 100644 --- a/src/Provider/NodeProviderInterface.php +++ b/src/Provider/NodeProviderInterface.php @@ -14,7 +14,16 @@ namespace Ramsey\Uuid\Provider; +/** + * NodeProviderInterface provides functionality to get the node ID (or host ID + * in the form of the system's MAC address) from a specific type of node provider + */ interface NodeProviderInterface { + /** + * Returns the system node ID + * + * @return string System node ID as a hexadecimal string + */ public function getNode(); } diff --git a/src/Provider/Time/FixedTimeProvider.php b/src/Provider/Time/FixedTimeProvider.php index f15552b..1734de4 100644 --- a/src/Provider/Time/FixedTimeProvider.php +++ b/src/Provider/Time/FixedTimeProvider.php @@ -16,10 +16,25 @@ namespace Ramsey\Uuid\Provider\Time; use Ramsey\Uuid\Provider\TimeProviderInterface; +/** + * FixedTimeProvider uses an previously-generated timestamp to provide the time + * + * This provider allows the use of a previously-generated timestamp, such as one + * stored in a database, when creating version 1 UUIDs. + */ class FixedTimeProvider implements TimeProviderInterface { + /** + * @var int[] Array containing `sec` and `usec` components of a timestamp + */ private $fixedTime; + /** + * Constructs a `FixedTimeProvider` using the provided `$timestamp` + * + * @param int[] Array containing `sec` and `usec` components of a timestamp + * @throws InvalidArgumentException if the `$timestamp` does not contain `sec` or `usec` components + */ public function __construct(array $timestamp) { if (!array_key_exists('sec', $timestamp) || !array_key_exists('usec', $timestamp)) { @@ -29,16 +44,31 @@ class FixedTimeProvider implements TimeProviderInterface $this->fixedTime = $timestamp; } + /** + * Sets the `usec` component of the timestamp + * + * @param int $value The `usec` value to set + */ public function setUsec($value) { $this->fixedTime['usec'] = $value; } + /** + * Sets the `sec` component of the timestamp + * + * @param int $value The `sec` value to set + */ public function setSec($value) { $this->fixedTime['sec'] = $value; } + /** + * Returns a timestamp array + * + * @return int[] Array containing `sec` and `usec` components of a timestamp + */ public function currentTime() { return $this->fixedTime; diff --git a/src/Provider/Time/SystemTimeProvider.php b/src/Provider/Time/SystemTimeProvider.php index b1b9f5f..6442985 100644 --- a/src/Provider/Time/SystemTimeProvider.php +++ b/src/Provider/Time/SystemTimeProvider.php @@ -16,8 +16,16 @@ namespace Ramsey\Uuid\Provider\Time; use Ramsey\Uuid\Provider\TimeProviderInterface; +/** + * SystemTimeProvider uses built-in PHP functions to provide the time + */ class SystemTimeProvider implements TimeProviderInterface { + /** + * Returns a timestamp array + * + * @return int[] Array containing `sec` and `usec` components of a timestamp + */ public function currentTime() { return gettimeofday(); diff --git a/src/Provider/TimeProviderInterface.php b/src/Provider/TimeProviderInterface.php index 84b38d8..ef8099d 100644 --- a/src/Provider/TimeProviderInterface.php +++ b/src/Provider/TimeProviderInterface.php @@ -14,10 +14,16 @@ namespace Ramsey\Uuid\Provider; +/** + * TimeProviderInterface provides functionality to get the time from a specific + * type of time provider + */ interface TimeProviderInterface { /** - * @return string[] Array guaranteed to contain "sec" and "usec" components of current timestamp. + * Returns a timestamp array + * + * @return int[] Array guaranteed to contain `sec` and `usec` components of a timestamp */ public function currentTime(); }