Merge remote-tracking branch 'origin/feature/release-3.0.0' into feat…

…ure/release-3.0.0

CHANGELOG.md

@@ -24,7 +24,7 @@ All notable changes to this project will be documented in this file, in reverse
   ```php
   public function assert(
       Rbac $rbac,
-      RoleInterface $role = null,
+      RoleInterface $role,
       string $permission
   ) : bool
   ```
@@ -53,8 +53,8 @@ All notable changes to this project will be documented in this file, in reverse
 ### Fixed
 
 - [#30](https://github.com/zendframework/zend-permissions-rbac/issues/30) fixes
-  circular references within the used in `Role::addChild()` and
-  `Role::addParent()` algorithms.
+  circular references within the `Role::addChild()` and `Role::addParent()`
+  algorithms.
 
 ## 2.6.0 - 2018-02-01
 

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

@@ -1,36 +1,85 @@
 # 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.
+If you upgrade from version 2 releases, you will notice a few changes. This
+document details the changes
+
+## Minimum supported PHP version
+
+Version 3 drops support for PHP versions prior to PHP 7.1.
 
 ## AssertionInterface
 
-The new `assert` functions looks as follows:
+The primary change is the `Zend\Permissions\Rbac\AssertionInterface::assert()`
+method definition.
+
+The new `assert` method has the following signature:
 
 ```php
-public function assert(Rbac $rbac, RoleInterface $role, string $permission): bool;
+namespace Zend\Permissions\Rbac;
+
+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:
+The version 2 releases defined the method such that it only accepted a single
+parameter, `Rbac $rbac`. Version 3 adds the `$role` and `$permission`
+parameters. This simplifies implementation of dynamic assertions using the role
+and the permission information.
 
-```
-public function assert(Rbac $rbac, RoleInterface $role, string $permission): bool
+For instance, imagine you want to disable a specific permission `foo` for an
+`admin` role; you can implement that as follows:
+
+```php
+public function assert(Rbac $rbac, RoleInterface $role, string $permission) : bool
 {
-    return !($permission === 'foo' && $role->getName() === 'admin');
+    return ! ($permission === 'foo' && $role->getName() === 'admin');
 }
 ```
 
-## Removed Role::setParent()
+If you were previously implementing `AssertionInterface`, you will need to
+update the `assert()` signature to match the changes in version 3.
+
+If you were creating assertions as PHP callables, you may continue to use the
+existing signature; however, you may also expand them to accept the new
+arguments should they assist you in creating more complex, dynamic assertions.
+
+## RoleInterface
+
+`Zend\Permissions\Rbac\RoleInterface` also received a number of changes,
+including type hints and method name changes.
+
+### Type hints
+
+With the update to [PHP 7.1](#minimum-supported-php-version), we also updated
+the `RoleInterface` to provide:
+
+- scalar type hints where applicable (`addPermission()` and `hasPermission()`).
+- add return type hints (including scalar type hints) to all methods.
+
+You will need to examine the `RoleInterface` definitions to determine what
+changes to make to your implementations.
+
+### setParent becomes addParent
+
+In version 3, we renamed the method `Role::setParent()` to `Role::addParent()`.
+This naming is more consistent with other method names, such as
+`Role::addChild()`, and also makes clear that more than one parent may be
+provided to any given role.
+
+### getParent becomes getParents
+
+In line with the previous change, `getParent()` was also renamed to
+`getParents()`, which returns an array of `RoleInterface` instances.
+
+### Removed support for string arguments in Role::addChild
 
-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()`.
+Version 3 no longer allows adding a child using a string role name; you may only
+provide `RoleInterface` instances.
 
-##  Removed the support of string in Role::addChild()
+### Adds getChildren
 
-In v3.0 you cannot add a child using a role name as string. You can only add
-a `RoleInterface` object.
+Since roles may have multiple children, the method `getChildren()` was added; it
+returns an array of `RoleInterface` instances.