Merging develop to master in preparation for 2.8.0

Author: weierophinney

CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file, in reverse chronological order by release.
 
+## 2.8.0 - TBD
+
+### Added
+
+- [#58](https://github.com/zendframework/zend-validator/pull/58) adds a new
+  `Uuid` validator, capable of validating if Versions 1-5 UUIDs are well-formed.
+- [#64](https://github.com/zendframework/zend-validator/pull/64) ports
+  `Zend\ModuleManager\Feature\ValidatorProviderInterface` to
+  `Zend\Validator\ValidatorProviderInterface`, and updates the `Module::init()`
+  to typehint against the new interface instead of the one from
+  zend-modulemanager. Applications targeting zend-mvc v3 can start updating
+  their code to implement the new interface, or simply duck-type against it.
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.
+
 ## 2.7.3 - 2016-05-16
 
 ### Added

doc/book/set.md

@@ -29,6 +29,7 @@ The following validators come with the zend-validator distribution.
 - [StringLength](validators/string-length.md)
 - [Timezone](validators/timezone.md)
 - [Uri](validators/uri.md)
+- [Uuid](validators/uuid.md)
 
 ## Additional validators
 

doc/book/validators/uuid.md

@@ -0,0 +1,38 @@
+# UUID Validator
+
+`Zend\Validator\Uuid` allows validating [Universally Unique IDentifiers](https://en.wikipedia.org/wiki/Universally_unique_identifier)
+(UUIDs). UUIDs are 128-bit values that are guaranteed to be "practically unique"
+in order to help prevent identifier conflicts. Five separate UUID versions
+exist:
+
+- Version 1, which uses a combination of date-time and hardware MAC addresses to
+  generate the hash.
+- Version 2, which uses a combination of date-time and system user/group identifiers.
+- Version 3, which uses an MD5sum of a URI or distinguished name to generate the
+  hash.
+- Version 4, which uses a CSPRNG to generate the hash.
+- Version 5, which uses the same idea as Version 3, but using SHA-1 for hashing.
+
+The `Uuid` validator is capable of validating whether a string is a valid UUID
+of any version. It does not validate that the UUID exists in your system,
+however, only that it is well-formed.
+
+> ### Introduced in 2.8.0
+>
+> `Zend\Validator\Uuid` was introduced with version 2.8.0.
+
+## Supported options
+
+The `Uuid` validator has no additional options.
+
+## Basic usage
+
+```php
+$validator = new Zend\Validator\Uuid();
+
+if ($validator->isValid($uuid)) {
+    // UUID was valid
+} else {
+    // Invalid/mal-formed UUID; use $validator->getMessages() for more detail
+}
+```

mkdocs.yml

@@ -35,6 +35,7 @@ pages:
             - StringLength: validators/string-length.md
             - Timezone: validators/timezone.md
             - Uri: validators/uri.md
+            - Uuid: validators/uuid.md
         - "File Validators":
             - Intro: validators/file/intro.md
             - Count: validators/file/count.md

src/Module.php

@@ -36,7 +36,7 @@ public function init($moduleManager)
         $serviceListener->addServiceManager(
             'ValidatorManager',
             'validators',
-            'Zend\ModuleManager\Feature\ValidatorProviderInterface',
+            ValidatorProviderInterface::class,
             'getValidatorConfig'
         );
     }

src/Uuid.php

@@ -0,0 +1,63 @@
+<?php
+/**
+ * @link      http://github.com/zendframework/zend-validator for the canonical source repository
+ * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Validator;
+
+/**
+ * Uuid validator.
+ */
+final class Uuid extends AbstractValidator
+{
+    /**
+     * Matches Uuid's versions 1 to 5.
+     */
+    const REGEX_UUID = '/^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/';
+
+    const INVALID = 'valueNotUuid';
+    const NOT_STRING = 'valueNotString';
+
+    /**
+     * @var array
+     */
+    protected $messageTemplates = [
+        self::NOT_STRING => 'Invalid type given; string expected',
+        self::INVALID => 'Invalid UUID format',
+    ];
+
+    /**
+     * Returns true if and only if $value meets the validation requirements.
+     *
+     * If $value fails validation, then this method returns false, and
+     * getMessages() will return an array of messages that explain why the
+     * validation failed.
+     *
+     * @param mixed $value
+     *
+     * @return bool
+     *
+     * @throws Exception\RuntimeException If validation of $value is impossible
+     */
+    public function isValid($value)
+    {
+        if (! is_string($value)) {
+            $this->error(self::NOT_STRING);
+            return false;
+        }
+
+        $this->setValue($value);
+
+        if (empty($value)
+            || $value !== '00000000-0000-0000-0000-000000000000'
+            && ! preg_match(self::REGEX_UUID, $value)
+        ) {
+            $this->error(self::INVALID);
+            return false;
+        }
+
+        return true;
+    }
+}

src/ValidatorProviderInterface.php

@@ -0,0 +1,29 @@
+<?php
+/**
+ * @link      http://github.com/zendframework/zend-validator for the canonical source repository
+ * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Validator;
+
+/**
+ * Hint to the zend-modulemanager ServiceListener that a module provides validators.
+ *
+ * Module classes implementing this interface hint to
+ * Zend\ModuleManager\ServiceListener that they provide validators for the
+ * ValidatorPluginManager.
+ *
+ * For users of zend-mvc/zend-modulemanager v2, this poses no backwards-compatibility
+ * break as the method getValidatorConfig is still duck-typed within Zend\Validator\Module
+ * when providing configuration to the ServiceListener.
+ */
+interface ValidatorProviderInterface
+{
+    /**
+     * Provide plugin manager configuration for validators.
+     *
+     * @return array
+     */
+    public function getValidatorConfig();
+}

test/UuidTest.php

@@ -0,0 +1,88 @@
+<?php
+/**
+ * @link      http://github.com/zendframework/zend-validator for the canonical source repository
+ * @copyright Copyright (c) 2005-2016 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\Validator;
+
+use PHPUnit_Framework_TestCase as TestCase;
+use stdClass;
+use Zend\Validator\Uuid;
+
+/**
+ * Class UuidTest.
+ *
+ * Uuid test cases based on https://github.com/beberlei/assert/blob/master/tests/Assert/Tests/AssertTest.php
+ */
+final class UuidTest extends TestCase
+{
+    /**
+     * @var Uuid
+     */
+    protected $validator;
+
+    public function setUp()
+    {
+        $this->validator = new Uuid();
+    }
+
+    /**
+     * @param $uuid
+     * @dataProvider validUuidProvider
+     */
+    public function testValidUuid($uuid)
+    {
+        $this->assertTrue($this->validator->isValid($uuid));
+        $messages = $this->validator->getMessages();
+        $this->assertCount(0, $messages);
+    }
+
+    /**
+     * @param $uuid
+     * @dataProvider invalidUuidProvider
+     */
+    public function testInvalidUuid($uuid, $expectedMessageKey)
+    {
+        $this->assertFalse($this->validator->isValid($uuid));
+        $messages = $this->validator->getMessages();
+        $this->assertCount(1, $messages);
+        $this->assertArrayHasKey($expectedMessageKey, $messages);
+        $this->assertNotEmpty($messages[$expectedMessageKey]);
+    }
+
+    /**
+     * @return array
+     */
+    public function validUuidProvider()
+    {
+        return [
+            'zero-fill' => ['00000000-0000-0000-0000-000000000000'],
+            'version-1' => ['ff6f8cb0-c57d-11e1-9b21-0800200c9a66'],
+            'version-2' => ['ff6f8cb0-c57d-21e1-9b21-0800200c9a66'],
+            'version-3' => ['ff6f8cb0-c57d-31e1-9b21-0800200c9a66'],
+            'version-4' => ['ff6f8cb0-c57d-41e1-9b21-0800200c9a66'],
+            'version-5' => ['ff6f8cb0-c57d-51e1-9b21-0800200c9a66'],
+            'uppercase' => ['FF6F8CB0-C57D-11E1-9B21-0800200C9A66'],
+        ];
+    }
+
+    /**
+     * @return array
+     */
+    public function invalidUuidProvider()
+    {
+        return [
+            'invalid-characters' => ['zf6f8cb0-c57d-11e1-9b21-0800200c9a66', Uuid::INVALID],
+            'missing-separators' => ['af6f8cb0c57d11e19b210800200c9a66', Uuid::INVALID],
+            'invalid-segment-2'  => ['ff6f8cb0-c57da-51e1-9b21-0800200c9a66', Uuid::INVALID],
+            'invalid-segment-1'  => ['af6f8cb-c57d-11e1-9b21-0800200c9a66', Uuid::INVALID],
+            'invalid-segement-5' => ['3f6f8cb0-c57d-11e1-9b21-0800200c9a6', Uuid::INVALID],
+            'truncated'          => ['3f6f8cb0', Uuid::INVALID],
+            'empty-string'       => ['', Uuid::INVALID],
+            'all-numeric'        => [123, Uuid::NOT_STRING],
+            'object'             => [new stdClass(), Uuid::NOT_STRING],
+        ];
+    }
+}