[stdlib] Add guard utils and traits

library/Zend/Stdlib/Guard/AllGuardsTrait.php

@@ -0,0 +1,22 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Stdlib\Guard;
+
+/**
+ * An aggregate for all guard traits
+ */
+trait AllGuardsTrait
+{
+
+    use ArrayOrTraversableGuardTrait;
+    use EmptyGuardTrait;
+    use NullGuardTrait;
+
+}

library/Zend/Stdlib/Guard/ArrayOrTraversableGuardTrait.php

@@ -0,0 +1,41 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Stdlib\Guard;
+
+/**
+ * Provide a guard method for array or Traversable data
+ */
+trait ArrayOrTraversableGuardTrait
+{
+
+    /**
+     * Verifies that the data is an array or Traversable
+     *
+     * @param  mixed  $data           the data to verify
+     * @param  string $dataName       the data name
+     * @param  string $exceptionClass FQCN for the exception
+     * @throws \Exception
+     */
+    protected function guardForArrayOrTraversable(
+        $data,
+        $dataName = 'Argument',
+        $exceptionClass = 'Zend\Stdlib\Exception\InvalidArgumentException'
+    ) {
+        if (!is_array($data) && !($data instanceof \Traversable)) {
+            $message = sprintf(
+                "%s must be an array or Traversable, [%s] given",
+                $dataName,
+                is_object($data) ? get_class($data) : gettype($data)
+            );
+            throw new $exceptionClass($message);
+        }
+    }
+
+}

library/Zend/Stdlib/Guard/EmptyGuardTrait.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Stdlib\Guard;
+
+/**
+ * Provide a guard method against empty data
+ */
+trait EmptyGuardTrait
+{
+
+    /**
+     * Verify that the data is not empty
+     *
+     * @param  mixed  $data           the data to verify
+     * @param  string $dataName       the data name
+     * @param  string $exceptionClass FQCN for the exception
+     * @throws \Exception
+     */
+    protected function guardAgainstEmpty(
+        $data,
+        $dataName = 'Argument',
+        $exceptionClass = 'Zend\Stdlib\Exception\InvalidArgumentException'
+    ) {
+        if (empty($data)) {
+            $message = sprintf('%s cannot be empty', $dataName);
+            throw new $exceptionClass($message);
+        }
+    }
+
+}

library/Zend/Stdlib/Guard/GuardUtils.php

@@ -0,0 +1,86 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Stdlib\Guard;
+
+/**
+ * Static guard helper class
+ *
+ * Bridges the gap for allowing refactoring until traits can be used by default.
+ *
+ * @deprecated
+ */
+abstract class GuardUtils
+{
+
+    const DEFAULT_EXCEPTION_CLASS = 'Zend\Stdlib\Exception\InvalidArgumentException';
+
+
+    /**
+     * Verifies that the data is an array or Traversable
+     *
+     * @param  mixed  $data           the data to verify
+     * @param  string $dataName       the data name
+     * @param  string $exceptionClass FQCN for the exception
+     * @throws \Exception
+     */
+    public static function guardForArrayOrTraversable(
+        $data,
+        $dataName = 'Argument',
+        $exceptionClass = self::DEFAULT_EXCEPTION_CLASS
+    ) {
+        if (!is_array($data) && !($data instanceof \Traversable)) {
+            $message = sprintf(
+                '%s must be an array or Traversable, [%s] given',
+                $dataName,
+                is_object($data) ? get_class($data) : gettype($data)
+            );
+            throw new $exceptionClass($message);
+        }
+    }
+
+    /**
+     * Verify that the data is not empty
+     *
+     * @param  mixed  $data           the data to verify
+     * @param  string $dataName       the data name
+     * @param  string $exceptionClass FQCN for the exception
+     * @throws \Exception
+     */
+    public static function guardAgainstEmpty(
+        $data,
+        $dataName = 'Argument',
+        $exceptionClass = self::DEFAULT_EXCEPTION_CLASS
+    ) {
+        if (empty($data)) {
+            $message = sprintf('%s cannot be empty', $dataName);
+            throw new $exceptionClass($message);
+        }
+    }
+
+    /**
+     * Verify that the data is not null
+     *
+     * @param  mixed  $data           the data to verify
+     * @param  string $dataName       the data name
+     * @param  string $exceptionClass FQCN for the exception
+     * @throws \Exception
+     */
+    public static function guardAgainstNull(
+        $data,
+        $dataName = 'Argument',
+        $exceptionClass = self::DEFAULT_EXCEPTION_CLASS
+    ) {
+        if (is_null($data)) {
+            $message = sprintf('%s cannot be null', $dataName);
+            throw new $exceptionClass($message);
+        }
+    }
+
+}

library/Zend/Stdlib/Guard/NullGuardTrait.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace Zend\Stdlib\Guard;
+
+/**
+ * Provide a guard method against null data
+ */
+trait NullGuardTrait
+{
+
+    /**
+     * Verify that the data is not null
+     *
+     * @param  mixed  $data           the data to verify
+     * @param  string $dataName       the data name
+     * @param  string $exceptionClass FQCN for the exception
+     * @throws \Exception
+     */
+    protected function guardAgainstNull(
+        $data,
+        $dataName = 'Argument',
+        $exceptionClass = 'Zend\Stdlib\Exception\InvalidArgumentException'
+    ) {
+        if (is_null($data)) {
+            $message = sprintf('%s cannot be null', $dataName);
+            throw new $exceptionClass($message);
+        }
+    }
+
+}

tests/ZendTest/Stdlib/Guard/ArrayOrTraversableGuardTraitTest.php

@@ -0,0 +1,54 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\Stdlib\Guard;
+
+use PHPUnit_Framework_TestCase as TestCase;
+use ZendTest\Stdlib\TestAsset\GuardedObject;
+use Zend\Stdlib\ArrayObject;
+
+/**
+ * @requires PHP 5.4
+ * @group    Zend_StdLib_Guard
+ * @covers   Zend\Stdlib\Guard\ArrayOrTraversableGuardTrait
+ */
+class ArrayOrTraversableGuardTraitTest extends TestCase
+{
+
+    public function setUp()
+    {
+        if (version_compare(PHP_VERSION, '5.4.0', '<')) {
+            $this->markTestSkipped('Only valid for php >= 5.4');
+        }
+    }
+
+    public function testGuardForArrayOrTraversableThrowsException()
+    {
+        $object = new GuardedObject;
+        $this->setExpectedException(
+            'Zend\Stdlib\Exception\InvalidArgumentException',
+            'Argument must be an array or Traversable, [string] given'
+        );
+        $object->setArrayOrTraversable('');
+    }
+
+    public function testGuardForArrayOrTraversableAllowsArray()
+    {
+        $object = new GuardedObject;
+        $this->assertNull($object->setArrayOrTraversable(array()));
+    }
+
+    public function testGuardForArrayOrTraversableAllowsTraversable()
+    {
+        $object      = new GuardedObject;
+        $traversable = new ArrayObject;
+        $this->assertNull($object->setArrayOrTraversable($traversable));
+    }
+
+}

tests/ZendTest/Stdlib/Guard/EmptyGuardTraitTest.php

@@ -0,0 +1,46 @@
+<?php
+/**
+ * Zend Framework (http://framework.zend.com/)
+ *
+ * @link      http://github.com/zendframework/zf2 for the canonical source repository
+ * @copyright Copyright (c) 2005-2013 Zend Technologies USA Inc. (http://www.zend.com)
+ * @license   http://framework.zend.com/license/new-bsd New BSD License
+ */
+
+namespace ZendTest\Stdlib\Guard;
+
+use PHPUnit_Framework_TestCase as TestCase;
+use ZendTest\Stdlib\TestAsset\GuardedObject;
+
+/**
+ * @requires PHP 5.4
+ * @group    Zend_StdLib_Guard
+ * @covers   Zend\Stdlib\Guard\EmptyGuardTrait
+ */
+class EmptyGuardTraitTest extends TestCase
+{
+
+    public function setUp()
+    {
+        if (version_compare(PHP_VERSION, '5.4.0', '<')) {
+            $this->markTestSkipped('Only valid for php >= 5.4');
+        }
+    }
+
+    public function testGuardAgainstEmptyThrowsException()
+    {
+        $object = new GuardedObject;
+        $this->setExpectedException(
+            'Zend\Stdlib\Exception\InvalidArgumentException',
+            'Argument cannot be empty'
+        );
+        $object->setNotEmpty('');
+    }
+
+    public function testGuardAgainstEmptyAllowsNonEmptyString()
+    {
+        $object = new GuardedObject;
+        $this->assertNull($object->setNotEmpty('foo'));
+    }
+
+}