Added ability to set multiple assertions and their condition for permissions

docs/06. Using the Authorization Service.md

@@ -187,6 +187,77 @@ return [
 
 Now, every time you check for `myPermission`, `myAssertion` will be checked as well.
 
+
+
+### Multiple assertions
+
+The assertion map also accepts multiple assertions as a simple array:
+
+```php
+return [
+    'zfc_rbac' => [
+        'assertion_map' => [
+            'myPermission'  => 'myAssertion', // single assertion
+            'myPermission2' => [              // multiple assertions
+                'myAssertion',
+                'myAssertion2'
+            ]
+        ]
+    ]
+];
+```
+
+Or with an additional condition definition:
+
+```php
+return [
+    'zfc_rbac' => [
+        'assertion_map' => [
+             // single assertion
+            'myPermission'  => 'myAssertion',
+            'myPermission2' => [ 
+                 // multiple assertions
+                'assertions' => [
+                    'myAssertion',
+                    'myAssertion2'
+                ], 
+                // condition
+                'condition' => \ZfcRbac\Assertion\AssertionSet::CONDITION_AND
+            ]
+        ]
+    ]
+];
+```
+
+If 'AND' condition is specified (this is default) all of the assertions must pass the check.
+If 'OR' condition is specified at least one of the assertions must pass the check.
+This in the background will create an instance of ZfcRbac\Assertion\AssertionSet and adds the given assertions to it.  
+
+### Assertion Set
+
+ZfcRbac\Assertion\AssertionSet class is basically a container for multiple assertions as well as assertion condition.
+An instance of the class get's actually created automatically when you specify multiple assertions (see above) 
+in the background, but you can also extend the class or create your own instance containing your custom assertions 
+and specify that in assertion map instead.
+
+```php
+return [
+    'zfc_rbac' => [
+        'assertion_manager' => [
+            'factories' => [
+                'myAssertionSet' => MyAssertionSetFactory::class
+            ]
+        ],
+
+        'assertion_map' => [
+            'myPermission'  => 'myAssertion', // single assertion
+            'myPermission2' => 'myAssertionSet' // multiple assertions in set
+        ]
+    ]
+];
+```
+
+
 ### Checking permissions in a service
 
 So let's check for a permission, shall we?

src/ZfcRbac/Assertion/AssertionSet.php

@@ -0,0 +1,200 @@
+<?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license.
+ */
+namespace ZfcRbac\Assertion;
+
+use ZfcRbac\Exception\InvalidArgumentException;
+use ZfcRbac\Service\AuthorizationService;
+
+/**
+ * Assertion set to hold and process multiple assertions
+ *
+ * @author  David Havl
+ * @licence MIT
+ */
+
+class AssertionSet implements AssertionInterface, \IteratorAggregate
+{
+    /**
+     * Condition constants
+     */
+    const CONDITION_OR  = 'OR';
+    const CONDITION_AND = 'AND';
+
+    /**
+     * @var $assertions array
+     */
+    protected $assertions = [];
+
+    /**
+     * @var $condition string
+     */
+    protected $condition = 'AND';
+
+    /**
+     * Constructor.
+     *
+     * @param array|AssertionInterface[] $assertions An array of assertions.
+     */
+    public function __construct(array $assertions = array())
+    {
+        $this->setAssertions($assertions);
+    }
+
+    /**
+     * Set assertions.
+     *
+     * @param AssertionInterface[] $assertions The assertions to set
+     *
+     * @return $this
+     */
+    public function setAssertions(array $assertions)
+    {
+        $this->assertions = [];
+
+        // if definition contains condition, set it.
+        if (isset($assertions['condition'])) {
+            if ($assertions['condition'] != self::CONDITION_AND && $assertions['condition'] != self::CONDITION_OR) {
+                throw new InvalidArgumentException('Invalid assertion condition given.');
+            }
+            $this->setCondition($assertions['condition']);
+        }
+
+        // if there are multiple assertions under a key 'assertions', get them.
+        if (isset($assertions['assertions']) && is_array($assertions['assertions'])) {
+            $assertions = $assertions['assertions'];
+        }
+
+        // set each assertion
+        foreach ($assertions as $name => $assertion) {
+            $this->setAssertion($assertion, is_int($name) ? null : $name);
+        }
+        return $this;
+    }
+
+    /**
+     * Set an assertion.
+     *
+     * @param string|AssertionInterface $assertion The assertion instance or it's name
+     * @param string $name A name/alias
+     * @return $this
+     */
+    public function setAssertion(AssertionInterface $assertion, $name = null)
+    {
+        if (null !== $name) {
+            $this->assertions[$name] = $assertion;
+        } else {
+            $this->assertions[] = $assertion;
+        }
+    }
+
+    /**
+     * Returns true if the assertion if defined.
+     *
+     * @param string $name The assertion name
+     *
+     * @return bool true if the assertion is defined, false otherwise
+     */
+    public function hasAssertion($name)
+    {
+        return isset($this->assertions[$name]);
+    }
+
+    /**
+     * Gets a assertion value.
+     *
+     * @param string $name The assertion name
+     *
+     * @return AssertionInterface The assertion instance
+     *
+     * @throws InvalidArgumentException if the assertion is not defined
+     */
+    public function getAssertion($name)
+    {
+        if (!$this->hasAssertion($name)) {
+            throw new InvalidArgumentException(sprintf('The assertion "%s" is not defined.', $name));
+        }
+        return $this->assertions[$name];
+    }
+
+    /**
+     * Gets all assertions.
+     *
+     * @return AssertionInterface[] The assertion instance
+     */
+    public function getAssertions()
+    {
+        return $this->assertions;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCondition()
+    {
+        return $this->condition;
+    }
+
+    /**
+     * Set condition
+     *
+     * @param string $condition
+     */
+    public function setCondition($condition)
+    {
+        $this->condition = $condition;
+    }
+
+    /**
+     * Retrieve an external iterator
+     * @return \ArrayIterator
+     */
+    public function getIterator()
+    {
+        return new \ArrayIterator($this->assertions);
+    }
+
+    /**
+     * Check if assertions are successful
+     *
+     * @param  AuthorizationService $authorizationService
+     * @param  mixed                $context
+     * @return bool
+     */
+    public function assert(AuthorizationService $authorizationService, $context = null)
+    {
+        if (self::CONDITION_AND === $this->condition) {
+            foreach ($this->assertions as $assertion) {
+                if (!$assertion->assert($authorizationService, $context)) {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
+        if (self::CONDITION_OR === $this->condition) {
+            foreach ($this->assertions as $assertion) {
+                if ($assertion->assert($authorizationService, $context)) {
+                    return true;
+                }
+            }
+
+            return false;
+        }
+    }
+}

src/ZfcRbac/Service/AuthorizationService.php

@@ -22,6 +22,7 @@
 use Rbac\Permission\PermissionInterface;
 use ZfcRbac\Assertion\AssertionPluginManager;
 use ZfcRbac\Assertion\AssertionInterface;
+use ZfcRbac\Assertion\AssertionSet;
 use ZfcRbac\Exception;
 use ZfcRbac\Identity\IdentityInterface;
 
@@ -72,11 +73,34 @@ public function __construct(Rbac $rbac, RoleService $roleService, AssertionPlugi
      * Set an assertion
      *
      * @param string|PermissionInterface         $permission
-     * @param string|callable|AssertionInterface $assertion
+     * @param string|callable|array|AssertionInterface $assertion
      * @return void
      */
     public function setAssertion($permission, $assertion)
     {
+        // if is name of the assertion, retrieve an actual instance from assertion plugin manager
+        if (is_string($assertion)) {
+            $assertion = $this->assertionPluginManager->get($assertion);
+        } elseif (is_array($assertion)) { // else if multiple assertion definition, create assertion set.
+
+            // move assertion definition under a key 'assertions'.
+            if (!isset($assertion['assertions'])) {
+                $assertion['assertions'] = (array)$assertion;
+            } elseif (!is_array($assertion['assertions'])) {
+                $assertion['assertions'] = (array)$assertion['assertions'];
+            }
+
+            // retrieve an actual instance from assertion plugin manager if necessary
+            foreach ($assertion['assertions'] as $key => $value) {
+                if (is_string($value)) {
+                    $assertion['assertions'][$key] = $this->assertionPluginManager->get($value);
+                }
+            }
+
+            // create assertion set
+            $assertion = new AssertionSet($assertion);
+        }
+
         $this->assertions[(string) $permission] = $assertion;
     }
 
@@ -88,7 +112,10 @@ public function setAssertion($permission, $assertion)
      */
     public function setAssertions(array $assertions)
     {
-        $this->assertions = $assertions;
+        $this->assertions = [];
+        foreach ($assertions as $permissionName => $assertionData) {
+            $this->setAssertion($permissionName, $assertionData);
+        }
     }
 
     /**
@@ -149,10 +176,6 @@ protected function assert($assertion, $context = null)
         if (is_callable($assertion)) {
             return $assertion($this, $context);
         } elseif ($assertion instanceof AssertionInterface) {
-            return $assertion->assert($this, $context);
-        } elseif (is_string($assertion)) {
-            $assertion = $this->assertionPluginManager->get($assertion);
-
             return $assertion->assert($this, $context);
         }