From 0fea069c5af253ada1d09545308f8c137a22b7bf Mon Sep 17 00:00:00 2001
From: Gary Hockin <gary@hock.in>
Date: Sun, 17 Jan 2016 15:13:15 -0700
Subject: [PATCH] Added base documentation

---
 doc/book/zend.permissions.rbac.examples.md | 162 +++++++++++++++++++++
 doc/book/zend.permissions.rbac.intro.md    |  38 +++++
 doc/book/zend.permissions.rbac.methods.md  |  34 +++++
 doc/bookdown.json                          |   9 ++
 4 files changed, 243 insertions(+)
 create mode 100644 doc/book/zend.permissions.rbac.examples.md
 create mode 100644 doc/book/zend.permissions.rbac.intro.md
 create mode 100644 doc/book/zend.permissions.rbac.methods.md
 create mode 100644 doc/bookdown.json

diff --git a/doc/book/zend.permissions.rbac.examples.md b/doc/book/zend.permissions.rbac.examples.md
new file mode 100644
index 00000000..4b3e660c
--- /dev/null
+++ b/doc/book/zend.permissions.rbac.examples.md
@@ -0,0 +1,162 @@
+# Examples
+
+The following is a list of common use-case examples for `Zend\Permission\Rbac`.
+
+## Roles
+
+Extending and adding roles via instantiation.
+
+```php
+<?php
+use Zend\Permissions\Rbac\Rbac;
+use Zend\Permissions\Rbac\AbstractRole;
+
+class MyRole extends AbstractRole
+{
+    // .. implementation
+}
+
+// Creating roles manually
+$foo  = new MyRole('foo');
+
+$rbac = new Rbac();
+$rbac->addRole($foo);
+
+var_dump($rbac->hasRole('foo')); // true
+```
+
+Adding roles directly to RBAC with the default `Zend\Permission\Rbac\Role`.
+
+```php
+<?php
+use Zend\Permissions\Rbac\Rbac;
+
+$rbac = new Rbac();
+$rbac->addRole('foo');
+
+var_dump($rbac->hasRole('foo')); // true
+```
+
+Handling roles with children.
+
+```php
+<?php
+use Zend\Permissions\Rbac\Rbac;
+use Zend\Permissions\Rbac\Role;
+
+$rbac = new Rbac();
+$foo  = new Role('foo');
+$bar  = new Role('bar');
+
+// 1 - Add a role with child role directly with instantiated classes.
+$foo->addChild($bar);
+$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
+```
+
+## Permissions
+
+```php
+<?php
+use Zend\Permissions\Rbac\Rbac;
+use Zend\Permissions\Rbac\Role;
+
+$rbac = new Rbac();
+$foo  = new Role('foo');
+$foo->addPermission('bar');
+
+var_dump($foo->hasPermission('bar')); // true
+
+$rbac->addRole($foo);
+$rbac->isGranted('foo', 'bar'); // true
+$rbac->isGranted('foo', 'baz'); // false
+
+$rbac->getRole('foo')->addPermission('baz');
+$rbac->isGranted('foo', 'baz'); // true
+```
+
+## Dynamic Assertions
+
+Checking permission using `isGranted()` with a class implementing
+`Zend\Permissions\Rbac\AssertionInterface`.
+
+```php
+<?php
+use Zend\Permissions\Rbac\AssertionInterface;
+use Zend\Permissions\Rbac\Rbac;
+
+class AssertUserIdMatches implements AssertionInterface
+{
+    protected $userId;
+    protected $article;
+
+    public function __construct($userId)
+    {
+        $this->userId = $userId;
+    }
+
+    public function setArticle($article)
+    {
+        $this->article = $article;
+    }
+
+    public function assert(Rbac $rbac)
+    {
+        if (!$this->article) {
+            return false;
+        }
+        return $this->userId == $this->article->getUserId();
+    }
+}
+
+// User is assigned the foo role with id 5
+// News article belongs to userId 5
+// Jazz article belongs to userId 6
+
+$rbac = new Rbac();
+$user = $mySessionObject->getUser();
+$news = $articleService->getArticle(5);
+$jazz = $articleService->getArticle(6);
+
+$rbac->addRole($user->getRole());
+$rbac->getRole($user->getRole())->addPermission('edit.article');
+
+$assertion = new AssertUserIdMatches($user->getId());
+$assertion->setArticle($news);
+
+// true always - bad!
+if ($rbac->isGranted($user->getRole(), 'edit.article')) {
+    // hacks another user's article
+}
+
+// true for user id 5, because he belongs to write group and user id matches
+if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
+    // edits his own article
+}
+
+$assertion->setArticle($jazz);
+
+// false for user id 5
+if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
+    // can not edit another user's article
+}
+```
+
+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();
+};
+
+// true
+if ($rbac->isGranted($user->getRole(), 'edit.article', $assertion)) {
+    // edits his own article
+}
+```
diff --git a/doc/book/zend.permissions.rbac.intro.md b/doc/book/zend.permissions.rbac.intro.md
new file mode 100644
index 00000000..2c54d73c
--- /dev/null
+++ b/doc/book/zend.permissions.rbac.intro.md
@@ -0,0 +1,38 @@
+# Introduction to Zend\\Permissions\\Rbac
+
+The `Zend\Permissions\Rbac` component provides a lightweight role-based access control
+implementation based around PHP 5.3's SPL 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
+
+The easiest way to create a role is by extending the abstract class
+`Zend\Permission\Rbac\AbstractRole` or simply using the default class provided in
+`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.
diff --git a/doc/book/zend.permissions.rbac.methods.md b/doc/book/zend.permissions.rbac.methods.md
new file mode 100644
index 00000000..0806b6ca
--- /dev/null
+++ b/doc/book/zend.permissions.rbac.methods.md
@@ -0,0 +1,34 @@
+# Methods
+
+`Zend\Permissions\Rbac\AbstractIterator`  
+- current
+- getChildren
+- hasChildren
+- key
+- next
+- rewind
+- valid
+
+`Zend\Permissions\Rbac\AbstractRole`  
+- addChild
+- addPermission
+- getName
+- hasPermission
+- setParent
+- getParent
+
+`Zend\Permissions\Rbac\AssertionInterface`  
+- assert
+
+`Zend\Permissions\Rbac\Rbac`  
+- addRole
+- getCreateMissingRoles
+- getRole
+- hasRole
+- isGranted
+- setCreateMissingRoles
+
+`Zend\Permissions\Rbac\Role`  
+- \_\_construct
+
+
diff --git a/doc/bookdown.json b/doc/bookdown.json
new file mode 100644
index 00000000..1d31ae84
--- /dev/null
+++ b/doc/bookdown.json
@@ -0,0 +1,9 @@
+{
+    "title": "Zend\\Permissions.rbac",
+    "target": "html/",
+    "content": [
+        "book/zend.permissions.rbac.intro.md",
+        "book/zend.permissions.rbac.methods.md",
+        "book/zend.permissions.rbac.examples.md"
+    ]
+}
\ No newline at end of file