Added migation guide + removed optionals in AssertionInterface

CHANGELOG.md

@@ -17,19 +17,15 @@ All notable changes to this project will be documented in this file, in reverse
   strings are no longer accepted.
 
 - [#34](https://github.com/zendframework/zend-permissions-rbac/pull/34) updates
-  the `Role::addParent(RoleInterface $parent)` method to only accept a
-  `RoleInterface` parameter; strings are no longer accepted.
-
-- [#34](https://github.com/zendframework/zend-permissions-rbac/pull/34) updates
-  the `Zend\Permissions\Rbac\AssertionInterface`, adding two optional parameters
-  to the `assert()` definition and defining a return type, so that it now reads
-  as follows:
+  the `Zend\Permissions\Rbac\AssertionInterface`, adding two parameters to the
+  `assert()` definition and defining a return type, so that it now reads as
+  follows:
 
   ```php
   public function assert(
       Rbac $rbac,
-      string $permission = null,
-      RoleInterface $role = null
+      RoleInterface $role = null,
+      string $permission
   ) : bool
   ```
 

doc/book/methods.md

@@ -20,9 +20,9 @@ Method signature                          | Description
 Custom assertions can be provided to `Rbac::isGranted()` (see below); such
 assertions are provided the `Rbac` instance on invocation.
 
-Method signature                                                            | Description
---------------------------------------------------------------------------- | -----------
-`assert(Rbac $rbac, RoleInterface $role = null, string $permission = null)` | Given an RBAC, an optional role, and an optional permission, determine if permission is granted.
+Method signature                                                     | Description
+-------------------------------------------------------------------- | -----------
+`assert(Rbac $rbac, RoleInterface $role, string $permission) : bool` | Given an RBAC, a role, and a permission, determine if permission is granted.
 
 ## `Zend\Permissions\Rbac\Rbac`
 

doc/book/migration/to-v3-0.md

@@ -0,0 +1,36 @@
+# Upgrading to 3.0
+
+If you upgrade from v2.X you will notice a few changes. The main change is the
+`Zend\Permissiones\Rbac\AssertionInterface::assert` function definition.
+
+## AssertionInterface
+
+The new `assert` functions looks as follows:
+
+```php
+public function assert(Rbac $rbac, RoleInterface $role, string $permission): bool;
+```
+
+In v2.X we had only the first parameter $rbac. In V3.0 we added `$role` and
+`$permission` parameters. This will simplify the implementation of dynamic
+assertion, using the Role and the permission information. For instance, imagine
+you want to disable a specific permission `foo` for an `admin` role, you can
+implement a simple function as follows:
+
+```
+public function assert(Rbac $rbac, RoleInterface $role, string $permission): bool
+{
+    return !($permission === 'foo' && $role->getName() === 'admin');
+}
+```
+
+## Removed Role::setParent()
+
+In v3.0 we removed the function `Role::setParent()` in favor of `Role::addParent()`.
+This function is more consistent with the others function naming like
+`Role::addChild()`.
+
+##  Removed the support of string in Role::addChild()
+
+In v3.0 you cannot add a child using a role name as string. You can only add
+a `RoleInterface` object.

mkdocs.yml

@@ -6,8 +6,9 @@ pages:
     - Reference:
         - Methods: methods.md
         - Examples: examples.md
+        - Migration:
+            - 'v2.X to v3.0': migration/to-v3-0.md
 site_name: zend-permissions-rbac
 site_description: zend-permissions-rbac
 repo_url: 'https://github.com/zendframework/zend-permissions-rbac'
 copyright: 'Copyright (c) 2016 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'
-

src/Assertion/CallbackAssertion.php

@@ -36,7 +36,7 @@ public function __construct(callable $callback)
     /**
      * {@inheritdoc}
      */
-    public function assert(Rbac $rbac, RoleInterface $role = null, string $permission = null) : bool
+    public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool
     {
         return ($this->callback)($rbac, $role, $permission);
     }

src/AssertionInterface.php

@@ -14,5 +14,5 @@ interface AssertionInterface
     /**
      * Assertion method - must return a boolean.
      */
-    public function assert(Rbac $rbac, RoleInterface $role = null, string $permission = null) : bool;
+    public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool;
 }

test/TestAsset/RoleMustMatchAssertion.php

@@ -16,7 +16,7 @@
 
 class RoleMustMatchAssertion implements AssertionInterface
 {
-    public function assert(Rbac $rbac, RoleInterface $role = null, string $permission = null) : bool
+    public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool
     {
         return $role->getName() === 'foo';
     }

test/TestAsset/SimpleFalseAssertion.php

@@ -15,7 +15,7 @@
 
 class SimpleFalseAssertion implements AssertionInterface
 {
-    public function assert(Rbac $rbac, RoleInterface $role = null, string $permission = null) : bool
+    public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool
     {
         return false;
     }

test/TestAsset/SimpleTrueAssertion.php

@@ -15,7 +15,7 @@
 
 class SimpleTrueAssertion implements AssertionInterface
 {
-    public function assert(Rbac $rbac, RoleInterface $role = null, string $permission = null) : bool
+    public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool
     {
         return true;
     }