Merge branch 'hotfix/12'

Close #12

.gitignore

@@ -6,10 +6,12 @@
 .*.sw*
 .*.un~
 nbproject
+doc/html/
 tmp/
+vendor/
+zf-mkdoc-theme/
 
 clover.xml
 composer.lock
 coveralls-upload.json
 phpunit.xml
-vendor

.travis.yml

@@ -10,6 +10,16 @@ branches:
 cache:
   directories:
     - $HOME/.composer/cache
+    - $HOME/.local
+    - zf-mkdoc-theme
+
+env:
+  global:
+    - SITE_URL: https://zendframework.github.io/zend-permissions-rbac
+    - GH_USER_NAME: "Matthew Weier O'Phinney"
+    - GH_USER_EMAIL: matthew@weierophinney.net
+    - GH_REF: github.com/zendframework/zend-permissions-rbac.git
+    - secure: "ELn6js6W0wG3/HlaNJ4ibkLPODT2brDZve6mouEiKnuEvS7dPLQvZYPBr55wWzRG8jGFbTvNXbyMspoufsBuZu5MeSRxkQG0g+Ka/7EXdAJaC/rNJREjMYoFPBS7jzPiEj6M8zi28fEA4rEXQBPkV2XSdXD1dyYFXNXBwcOD+5LEyvFA5A+CNFjfhlf/SDMssJfpmuY+PyyP9r0rIoWwPDrRCQYA3T4vFN6/T6VtrrvSoV32F3Dr7Hjioe57HuTum5UMkVpG8cllx1gQSwqDOE3T1CPejtrgfA6V4UMH1TmNt0GsOCPs+Y0Bjjq30WW5QkFCfk3R27QsJOLKfOr4gsT/oup90x858qrzgmBJio8lOmh4DpaYk3pX96FcP4uS1klyW6m1QkBD+1LkS96BW/pL6gqSu9Xa8nSeC3NRDIzrJf7Yd4YR88xdg0g0UUJ/Z34rdM4kzEeYFuls6zmgnfrmJzOnFU7yWw9CzInMikrx5jQloJUogARr4QsI0MKggw1KNs+ECqAcQbL/wb/EuVUIIB4u0joTn3Ox71x0TZg+MdRIPSWNwuGmJfMZLZ2nIU9To7qHFs1tMgJ/+JRuWrx+UFAelMBoNf0qRqI0XbpTH2R+FM6EiX9aOqPPFt3aYMdfyFzncIGEsoXv5ySECgvoEU41Sszwa23ekgjjxcs="
 
 matrix:
   fast_finish: true
@@ -20,6 +30,8 @@ matrix:
     - php: 5.6
       env:
         - EXECUTE_TEST_COVERALLS=true
+        - DEPLOY_DOCS="$(if [[ $TRAVIS_BRANCH == 'master' && $TRAVIS_PULL_REQUEST == 'false' ]]; then echo -n 'true' ; else echo -n 'false' ; fi)"
+        - PATH="$HOME/.local/bin:$PATH"
     - php: 7
     - php: hhvm 
   allow_failures:
@@ -42,6 +54,10 @@ script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/phpunit --coverage-clover clover.xml ; fi
   - if [[ $EXECUTE_TEST_COVERALLS != 'true' ]]; then ./vendor/bin/phpunit ; fi
   - if [[ $EXECUTE_CS_CHECK == 'true' ]]; then ./vendor/bin/php-cs-fixer fix -v --diff --dry-run ; fi
+  - if [[ $DEPLOY_DOCS == "true" && "$TRAVIS_TEST_RESULT" == "0" ]]; then wget -O theme-installer.sh "https://raw.githubusercontent.com/zendframework/zf-mkdoc-theme/master/theme-installer.sh" ; chmod 755 theme-installer.sh ; ./theme-installer.sh ; fi
+
+after_success:
+  - if [[ $DEPLOY_DOCS == "true" ]]; then echo "Preparing to build and deploy documentation" ; ./zf-mkdoc-theme/deploy.sh ; echo "Completed deploying documentation" ; fi
 
 after_script:
   - if [[ $EXECUTE_TEST_COVERALLS == 'true' ]]; then ./vendor/bin/coveralls ; fi

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file, in reverse chronological order by release.
+
+## 2.5.2 - TBD
+
+### Added
+
+- [#12](https://github.com/zendframework/zend-permissions-rbac/pull/12) adds
+  and publishes the documentation to https://zendframework.github.io/zend-permissions-rbac/
+
+### Deprecated
+
+- Nothing.
+
+### Removed
+
+- Nothing.
+
+### Fixed
+
+- Nothing.

README.md

@@ -6,4 +6,4 @@
 Provides role-based access control (RBAC) permissions management.
 
 - File issues at https://github.com/zendframework/zend-permissions-rbac
-- Documentation is at http://framework.zend.com/docs
+- Documentation is at https://zendframework.github.io/zend-permissions-rbac/

doc/book/zend.permissions.rbac.examples.md → doc/book/examples.md

@@ -1,13 +1,12 @@
 # Examples
 
-The following is a list of common use-case examples for `Zend\Permission\Rbac`.
+The following is a list of common use-case examples for zend-permission-rbac.
 
 ## Roles
 
-Extending and adding roles via instantiation.
+Extending and adding roles via instantiation:
 
 ```php
-<?php
 use Zend\Permissions\Rbac\Rbac;
 use Zend\Permissions\Rbac\AbstractRole;
 
@@ -25,10 +24,9 @@ $rbac->addRole($foo);
 var_dump($rbac->hasRole('foo')); // true
 ```
 
-Adding roles directly to RBAC with the default `Zend\Permission\Rbac\Role`.
+Adding roles directly to RBAC with the default `Zend\Permission\Rbac\Role`:
 
 ```php
-<?php
 use Zend\Permissions\Rbac\Rbac;
 
 $rbac = new Rbac();
@@ -37,10 +35,9 @@ $rbac->addRole('foo');
 var_dump($rbac->hasRole('foo')); // true
 ```
 
-Handling roles with children.
+Handling roles with children:
 
 ```php
-<?php
 use Zend\Permissions\Rbac\Rbac;
 use Zend\Permissions\Rbac\Role;
 
@@ -54,13 +51,12 @@ $rbac->addRole($foo);
 
 // 2 - Same as one, only via rbac container.
 $rbac->addRole('boo', 'baz'); // baz is a parent of boo
-$rbac->addRole('baz', array('out', 'of', 'roles')); // create several parents of baz
+$rbac->addRole('baz', ['out', 'of', 'roles']); // create several parents of baz
 ```
 
 ## Permissions
 
 ```php
-<?php
 use Zend\Permissions\Rbac\Rbac;
 use Zend\Permissions\Rbac\Role;
 
@@ -81,10 +77,9 @@ $rbac->isGranted('foo', 'baz'); // true
 ## Dynamic Assertions
 
 Checking permission using `isGranted()` with a class implementing
-`Zend\Permissions\Rbac\AssertionInterface`.
+`Zend\Permissions\Rbac\AssertionInterface`:
 
 ```php
-<?php
 use Zend\Permissions\Rbac\AssertionInterface;
 use Zend\Permissions\Rbac\Rbac;
 
@@ -105,10 +100,11 @@ class AssertUserIdMatches implements AssertionInterface
 
     public function assert(Rbac $rbac)
     {
-        if (!$this->article) {
+        if (! $this->article) {
             return false;
         }
-        return $this->userId == $this->article->getUserId();
+
+        return ($this->userId === $this->article->getUserId());
     }
 }
 
@@ -145,14 +141,13 @@ if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
 }
 ```
 
-Performing the same as above with a Closure.
+Performing the same as above with a closure:
 
 ```php
-<?php
 // assume same variables from previous example
 
 $assertion = function($rbac) use ($user, $news) {
-    return $user->getId() == $news->getUserId();
+    return ($user->getId() === $news->getUserId());
 };
 
 // true

doc/book/index.html

@@ -0,0 +1,11 @@
+<div class="container">
+    <div class="jumbotron">
+        <h1>zend-permissions-rbac</h1>
+
+        <p>
+            Provide and query Role-Based Access Controls for your application.
+        </p>
+
+        <pre><code class="language-bash">$ composer require zendframework/zend-permissions-rbac</code></pre>
+    </div>
+</div>

doc/book/index.md

@@ -0,0 +1 @@
+../../README.md

doc/book/intro.md

@@ -0,0 +1,40 @@
+# Introduction
+
+zend-permissions-rbac provides a lightweight role-based access control (RBAC)
+implementation based around PHP's `RecursiveIterator` and
+`RecursiveIteratorIterator`. RBAC differs from access control lists (ACL) by
+putting the emphasis on roles and their permissions rather than objects
+(resources).
+
+For the purposes of this documentation:
+
+- an **identity** has one or more roles.
+- a **role** requests access to a permission.
+- a **permission** is given to a role.
+
+Thus, RBAC has the following model:
+
+- many to many relationship between **identities** and **roles**.
+- many to many relationship between **roles** and **permissions**.
+- **roles** can have a parent role.
+
+## Roles
+
+To create a role, extend the abstract class `Zend\Permission\Rbac\AbstractRole`
+or use the default role class, `Zend\Permission\Rbac\Role`. You can instantiate
+a role and add it to the RBAC container or add a role directly using the RBAC
+container `addRole()` method.
+
+## Permissions
+
+Each role can have zero or more permissions and can be set directly to the role
+or by first retrieving the role from the RBAC container. Any parent role will
+inherit the permissions of their children.
+
+## Dynamic Assertions
+
+In certain situations simply checking a permission key for access may not be
+enough. For example, assume two users, Foo and Bar, both have `article.edit`
+permission. What's to stop Bar from editing Foo's articles? The answer is
+dynamic assertions which allow you to specify extra runtime credentials that
+must pass for access to be granted.

doc/book/methods.md

@@ -0,0 +1,61 @@
+# Methods
+
+## `Zend\Permissions\Rbac\AbstractIterator`
+
+The `AbstractIterator` is used as the basis for both the primary `Rbac` class
+and the `AbstractRole`.
+
+Method signature                    | Description
+----------------------------------- | -----------
+`current() : RoleInterface`         | Return the current role instance.
+`getChildren() : RecursiveIterator` | Returns a recursive iterator of all children of the current role.
+`hasChildren() : bool`              | Indicates if the current role has children.
+`key() : int`                       | Index of the current role instance.
+`next() : void`                     | Advance to the next role instance.
+`rewind() : void`                   | Seek to the first item in the iterator.
+`valid() : bool`                    | Is the current index valid?
+
+## `Zend\Permissions\Rbac\AbstractRole`
+
+The `AbstractRole` provides the base functionality required by the
+`RoleInterface`, and is the foundation for the `Role` class.
+
+Method signature                               | Description
+---------------------------------------------- | -----------
+`addChild(string|RoleInterface $child) : void` | Add a child role to the current instance.
+`addPermission(string $name) : void`           | Add a permission for the current role.
+`getName() : string`                           | Retrieve the name assigned to this role.
+`hasPermission(string $name) : bool`           | Does the role have the given permission?
+`setParent(RoleInterface $parent) : void`      | Assign the provided role as the current role's parent.
+`getParent() null|RoleInterface`               | Retrive the current role's parent, if one exists.
+
+## `Zend\Permissions\Rbac\AssertionInterface`
+
+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) : bool` | Given an RBAC, determine if permission is granted.
+
+## `Zend\Permissions\Rbac\Rbac`
+
+`Rbac` is the object with which you will interact within your application in
+order to query for permissions. It extends `AbstractIterator`.
+
+Method signature                                                            | Description
+--------------------------------------------------------------------------- | -----------
+`addRole(string|RoleInterface $child, array|RoleInterface $parents = null)` | Add a role to the RBAC. If `$parents` is non-null, the `$child` is also added to any parents provided.
+`getRole(string|RoleInterface $role) : RoleInterface`                       | Recursively queries the RBAC for the given role, returning it if found, and raising an exception otherwise.
+`hasRole(string|RoleInterface $role) : bool`                                | Recursively queries the RBAC for the given role, returning `true` if found, `false` otherwise.
+`getCreateMissingRoles() : bool`                                            | Retrieve the flag that determines whether or not `$parent` roles are added automatically if not present when calling `addRole()`.
+`setCreateMissingRoles(bool $flag) : void`                                  | Set the flag that determines whether or not `$parent` roles are added automatically if not present when calling `addRole()`.
+`isGranted(string|RoleInterface $role, string $permission, $assert = null)` | Determine if the role has the given permission. If `$assert` is provided and either an `AssertInterface` instance or callable, it will be queried before checking against the given role.
+
+## `Zend\Permissions\Rbac\Role`
+
+`Role` inherits from `AbstractRole` and `AbstractIterator`.
+
+Method signature                   | Description
+---------------------------------- | -----------
+`__construct(string $name) : void` | Create a new instance with the provided name.

mkdocs.yml

@@ -0,0 +1,13 @@
+docs_dir: doc/book
+site_dir: doc/html
+pages:
+    - index.md
+    - Intro: intro.md
+    - Reference:
+        - Methods: methods.md
+        - Examples: examples.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>'
+