Merge pull request #346 from chukShirley/docs-grammar-readability-fixes

Make grammar and readability improvements to documentation

Author: prolic

docs/01. Introduction.md

@@ -10,7 +10,7 @@ In this part, the following questions will be answered:
 
 ## Why should I use an authorization module?
 
-The authorization part of an application is an essential aspect to secure your application. While the authentication
+The authorization part of an application is an essential aspect of securing your application. While the authentication
 part tells you who is using your website, the authorization answers if the given identity has the permission to
 perform specific actions.
 
@@ -30,20 +30,20 @@ The basic idea of Rbac is to use roles and permissions:
 
 By default, ZfcRbac can be used for two kinds of Rbac model:
 
-* Flat RBAC model: in this model, roles cannot have children. This is ideal for smaller application, as it is easier
+* Flat RBAC model: in this model, roles cannot have children. This is ideal for smaller applications, as it is easier
 to understand, and the database design is simpler (no need for a join table).
-* Hierarchical RBAC model: in this model, roles can have children roles. When evaluating if a given role has a
+* Hierarchical RBAC model: in this model, roles can have child roles. When evaluating if a given role has a
 permission, this model also checks recursively if any of its child roles also have the permission.
 
 
 ## How can I integrate ZfcRbac into my application?
 
 ZfcRbac offers multiple ways to protect your application:
 
-* Using **Guards**: those classes act as "firewalls" that block access to routes and/or controllers. Guards are usually
+* Using **Guards**: these classes act as "firewalls" that block access to routes and/or controllers. Guards are usually
   configured using PHP arrays, and are executed early in the MVC dispatch process. Typically this happens right after
   the route has been matched.
-* Using **AuthorizationService**: a complementary method is to use the `AuthorizationService` and inject them into your
+* Using **AuthorizationService**: a complementary method is to use the `AuthorizationService` class and inject it into your
   service classes to protect them from unwanted access.
 
 While it is advised to use both methods to make your application even more secure, this is completely optional and you

docs/02. Quick Start.md

@@ -2,17 +2,17 @@
 
 In this section, you will learn:
 
-* How to setup the module
+* How to set up the module
 * How to specify an identity provider
-* How to add simple role provider
+* How to add a simple role provider
 
 Before starting the quick start, make sure you have properly installed the module by following the instructions in
 the README file.
 
 ## Specifying an identity provider
 
 By default, ZfcRbac internally uses the `Zend\Authentication\AuthenticationService` service key to retrieve the user (logged or
-not). Therefore, you must implement and register this service in your application by adding those lines in your `module.config.php` file:
+not). Therefore, you must implement and register this service in your application by adding these lines in your `module.config.php` file:
 
 ```php
 return [
@@ -27,12 +27,12 @@ return [
 ```
 The identity given by `Zend\Authentication\AuthenticationService` must implement `ZfcRbac\Identity\IdentityInterface`. Note that the default identity provided with ZF2 does not implement this interface, neither does the ZfcUser suite.
 
-ZfcRbac is flexible enough to use something else than the built-in `AuthenticationService`, by specifying custom
+ZfcRbac is flexible enough to use something other than the built-in `AuthenticationService`, by specifying custom
 identity providers. For more information, refer [to this section](/docs/03. Role providers.md#identity-providers).
 
 ## Adding a guard
 
-A guard allows to block access to routes and/or controllers using a simple syntax. For instance, this configuration
+A guard allows your application to block access to routes and/or controllers using a simple syntax. For instance, this configuration
 grants access to any route that begins with `admin` (or is exactly `admin`) to the `admin` role only:
 
 ```php
@@ -47,15 +47,15 @@ return [
 ];
 ```
 
-ZfcRbac have several built-in guards, and you can also register your own guards. For more information, refer
+ZfcRbac has several built-in guards, and you can also register your own guards. For more information, refer
 [to this section](/docs/04. Guards.md#built-in-guards).
 
 ## Adding a role provider
 
 RBAC model is based on roles. Therefore, for ZfcRbac to work properly, it must be aware of all the roles that are
 used inside your application.
 
-This configuration creates an *admin* role that has a children role called *member*. The *admin* role automatically
+This configuration creates an *admin* role that has a child role called *member*. The *admin* role automatically
 inherits the *member* permissions.
 
 ```php
@@ -76,10 +76,10 @@ return [
 ];
 ```
 
-In this example, the *admin* role have two permissions: `delete` and `edit` (because it inherits the permissions from
-its child), while the *member* role only has the permission `edit`.
+In this example, the *admin* role has two permissions: `delete` and `edit` (because it inherits the permissions from
+its child), while the *member* role only has the `edit` permission.
 
-ZfcRbac have several built-in role providers, and you can also register your own role providers. For more information,
+ZfcRbac has several built-in role providers, and you can also register your own role providers. For more information,
 refer [to this section](/docs/03. Role providers.md#built-in-role-providers).
 
 ## Registering a strategy
@@ -101,16 +101,16 @@ public function onBootstrap(EventInterface $e)
 }
 ```
 
-By default, `RedirectStrategy` redirects all unauthorized requests to a route named "login" when user is not connected 
-and to a route named "home" when user is connected. This is, of course, entirely configurable.
+By default, `RedirectStrategy` redirects all unauthorized requests to a route named "login" when the user is not connected 
+and to a route named "home" when the user is connected. This is, of course, entirely configurable.
 
-> For flexibility purpose, ZfcRbac **does not** register any strategy for you by default!
+> For flexibility purposes, ZfcRbac **does not** register any strategy for you by default!
 
 For more information about built-in strategies, refer [to this section](/docs/05. Strategies.md#built-in-strategies).
 
 ## Using the authorization service
 
-Now that ZfcRbac is properly configured, you can inject the authorization service in any class and use it to check
+Now that ZfcRbac is properly configured, you can inject the authorization service into any class and use it to check
 if the current identity is granted to do something.
 
 The authorization service is registered inside the service manager using the following key: `ZfcRbac\Service\AuthorizationService`.

docs/03. Role providers.md

@@ -13,13 +13,13 @@ A role provider is an object that returns a list of roles. Each role provider mu
 `ZfcRbac\Role\RoleProviderInterface` interface. The only required method is `getRoles`, and must return an array
 of `Rbac\Role\RoleInterface` objects.
 
-Roles can come from any sources: in memory, from a file, from a database... However, please note that since ZfcRbac
-2.0, you can specify only one role provider per application. The reason is that having multiple role providers make
+Roles can come from one of many sources: in memory, from a file, from a database... However, please note that since ZfcRbac
+2.0, you can specify only one role provider per application. The reason is that having multiple role providers makes
 the workflow harder and can lead to security problems that are very hard to spot.
 
 ## Identity providers?
 
-Identity providers return the current identity. Most of the time, this means the logged user. ZfcRbac comes with a
+Identity providers return the current identity. Most of the time, this means the logged in user. ZfcRbac comes with a
 default identity provider (`ZfcRbac\Identity\AuthenticationIdentityProvider`) that uses the
 `Zend\Authentication\AuthenticationService` service.
 
@@ -83,7 +83,7 @@ return [
 ];
 ```
 
-The `children` and `permissions` subkeys are entirely optionals. Internally, the `InMemoryRoleProvider` creates
+The `children` and `permissions` subkeys are entirely optional. Internally, the `InMemoryRoleProvider` creates
 either a `Rbac\Role\Role` object if the role does not have any children, or a `Rbac\Role\HierarchicalRole` if
 the role has at least one child.
 
@@ -162,7 +162,7 @@ Please note that your entity fetched from the table MUST implement the `Rbac\Rol
 
 ## Creating custom role providers
 
-To create a custom role providers, you first need to create a class that implements the `ZfcRbac\Role\RoleProviderInterface`
+To create a custom role provider, you first need to create a class that implements the `ZfcRbac\Role\RoleProviderInterface`
 interface.
 
 Then, you need to add it to the role provider manager:

docs/04. Guards.md

@@ -2,14 +2,14 @@
 
 In this section, you will learn:
 
-* What are guards
+* What guards are
 * How to use and configure built-in guards
 * How to create custom guards
 
-## What are guards and when to use them?
+## What are guards and when should you use them?
 
 Guards (called firewalls in older versions of ZfcRbac) are listeners that are registered on a specific event of
-the MVC workflow. They allow to quickly unauthorized requests.
+the MVC workflow. They allow your application to quickly mark a request as unauthorized.
 
 Here is a simple workflow without guards:
 
@@ -27,14 +27,14 @@ If you want to protect a route for a set of permissions, you must use RoutePermi
 you may want to grant access to a route "post/delete" only to roles having the "delete" permission.
 Note that in a RBAC system, a permission is linked to a role, not to a user.
 
-Albeit simple to use, guards should not be the only protection in your application, and you should always also
-protect your service. The reason is that your business logic should be handled by your service. Protecting a given
+Albeit simple to use, guards should not be the only protection in your application, and you should always
+protect your services as well. The reason is that your business logic should be handled by your service. Protecting a given
 route or controller does not mean that the service cannot be access from elsewhere (another action for instance).
 
 ### Protection policy
 
-By default, when a guard is added, it will perform check only on the specified guard rules. Any route or controller
-that are not specified in the rules will be "granted" by default. Therefore, the default is a "blacklist"
+By default, when a guard is added, it will perform a check only on the specified guard rules. Any route or controller
+that is not specified in the rules will be "granted" by default. Therefore, the default is a "blacklist"
 mechanism.
 
 However, you may want a more restrictive approach (also called "whitelist"). In this mode, once a guard is added,
@@ -87,15 +87,15 @@ more rules in another module. All the rules will be automatically merged.
 you decide to use both conjointly, I recommend you to set the protection policy to "allow" (otherwise, you will
 need to define rules for every routes AND every controller, which can become quite frustrating!).
 
-Please note that if your application use both route and controller guards, route guards are always executed
+Please note that if your application uses both route and controller guards, route guards are always executed
 **before** controller guards (they have a higher priority).
 
 ### RouteGuard
 
 > The RouteGuard listens to the `MvcEvent::EVENT_ROUTE` event with a priority of -5.
 
-The RouteGuard allows to protect a route or a hierarchy of route. You must provide an array of "key" => "value",
-where the key is a route pattern, and value an array of role names:
+The RouteGuard allows your application to protect a route or a hierarchy of routes. You must provide an array of "key" => "value",
+where the key is a route pattern and the value is an array of role names:
 
 ```php
 return [
@@ -110,7 +110,7 @@ return [
 ];
 ```
 
-> Only one role in a rule need to be matched (it is an OR condition).
+> Only one role in a rule needs to be matched (it is an OR condition).
 
 Those rules grant access to all admin routes to users that have the "admin" role, and grant access to the "login"
 route to users that have the "guest" role (eg.: most likely unauthenticated users).
@@ -168,8 +168,8 @@ return [
 
 > The RoutePermissionsGuard listens to the `MvcEvent::EVENT_ROUTE` event with a priority of -8.
 
-The RoutePermissionsGuard allows to protect a route or a hierarchy of route. You must provide an array of "key" => "value",
-where the key is a route pattern, and value an array of permissions names:
+The RoutePermissionsGuard allows your application to protect a route or a hierarchy of routes. You must provide an array of "key" => "value",
+where the key is a route pattern and the value is an array of permission names:
 
 ```php
 return [
@@ -243,14 +243,14 @@ return [
 ];
 ```
 
-This rule will be inaccessible.
+This route will be inaccessible.
 
 
 ### ControllerGuard
 
 > The ControllerGuard listens to the `MvcEvent::EVENT_ROUTE` event with a priority of -10.
 
-The ControllerGuard allows to protect a controller. You must provide an array of array:
+The ControllerGuard allows your application to protect a controller. You must provide an array of arrays:
 
 ```php
 return [
@@ -292,7 +292,7 @@ return [
 ];
 ```
 
-You can combine a generic rule and a specific action rule for the same controller, as follow:
+You can combine a generic rule and a specific action rule for the same controller, as follows:
 
 ```php
 return [
@@ -314,14 +314,14 @@ return [
 ];
 ```
 
-Those rules grant access to each actions of the controller to users that have the "member" role, but restrict the
+These rules grant access to each controller action to users that have the "member" role, but restrict the
 "delete" action to "admin" only.
 
 ### ControllerPermissionsGuard
 
 > The ControllerPermissionsGuard listens to the `MvcEvent::EVENT_ROUTE` event with a priority of -13.
 
-The ControllerPermissionsGuard allows to protect a controller using permissions. You must provide an array of array:
+The ControllerPermissionsGuard allows your application to protect a controller using permissions. You must provide an array of arrays:
 
 ```php
 return [
@@ -341,7 +341,7 @@ return [
 > All permissions in a rule must be matched (it is an AND condition).
 
 In the previous example, the user must have ```post.update``` **AND** ```post.delete``` permissions
-to access each actions of the MyController controller.
+to access each action of the MyController controller.
 
 As for all other guards, you can use a wildcard (*) character for permissions.
 
@@ -350,15 +350,15 @@ The configuration rules are the same as for ControllerGuard.
 ### Security notice
 
 RouteGuard and ControllerGuard listen to the `MvcEvent::EVENT_ROUTE` event. Therefore, if you use the
-`forward` method into your controller, those guards will not intercept and check requests (because internally
+`forward` method in your controller, those guards will not intercept and check requests (because internally
 ZF2 does not trigger again a new MVC loop).
 
 Most of the time, this is not an issue, but you must be aware of it, and this is an additional reason why you
 should always protect your services too.
 
 ## Creating custom guards
 
-ZfcRbac is flexible enough to allow you to create custom guard. Let's say we want to create a guard that will
+ZfcRbac is flexible enough to allow you to create custom guards. Let's say we want to create a guard that will
 refuse access based on an IP addresses blacklist.
 
 First create the guard:
@@ -412,9 +412,9 @@ By default, guards are listening to the event `MvcEvent::EVENT_ROUTE` with a pri
 event to listen by overriding the `EVENT_NAME` constant in your guard subclass). However, in this case, we don't
 even need to wait for the route to be matched, so we overload the `EVENT_PRIORITY` constant to be executed earlier.
 
-The `isGranted` method simply retrieves the client IP address, and check it against the blacklist.
+The `isGranted` method simply retrieves the client IP address, and checks it against the blacklist.
 
-However, for this to work, we must register the newly created guard to the guard plugin manager. To do so, add the
+However, for this to work, we must register the newly created guard with the guard plugin manager. To do so, add the
 following code in your config:
 
 ```php
@@ -429,7 +429,7 @@ return [
 ];
 ```
 
-The `guard_manager` config follows a conventional service manager config format.
+The `guard_manager` config follows a conventional service manager configuration format.
 
 Now, let's create the factory:
 
@@ -467,9 +467,9 @@ class IpGuardFactory implements FactoryInterface, MutableCreationOptionsInterfac
 ```
 
 The `MutableCreationOptionsInterface` was introduced in Zend Framework 2.2, and allows your factories to accept
-options. In fact, in a real use case, you would likely fetched the blacklist from database.
+options. In fact, in a real use case, you would likely fetched the blacklist from a database.
 
-Now, we just need to add the guard to the `guards` option, so that ZfcRbac execute the logic behind this guard. In
+Now we just need to add the guard to the `guards` option, so that ZfcRbac can execute the logic behind this guard. In
 your config, add the following code:
 
 ```php

docs/05. Strategies.md

@@ -2,14 +2,14 @@
 
 In this section, you will learn:
 
-* What are strategies
+* What strategies are
 * How to use built-in strategies
-* Creating custom strategies
+* How to create custom strategies
 
 ## What are strategies?
 
 A strategy is an object that listens to the `MvcEvent::EVENT_DISPATCH_ERROR` event. It is used to describe what
-happens when an access to a resource is unauthorized by ZfcRbac.
+happens when access to a resource is unauthorized by ZfcRbac.
 
 ZfcRbac strategies all check if an `ZfcRbac\Exception\UnauthorizedExceptionInterface` has been thrown.
 
@@ -33,10 +33,10 @@ ZfcRbac comes with two built-in strategies: `RedirectStrategy` and `Unauthorized
 
 ### RedirectStrategy
 
-This strategy allows to redirect any unauthorized request to another route, by optionally appending the previous
-URL as a query param.
+This strategy allows your application to redirect any unauthorized request to another route by optionally appending the previous
+URL as a query parameter.
 
-To register it, copy-paste this code in your Module.php class:
+To register it, copy-paste this code into your Module.php class:
 
 ```php
 public function onBootstrap(EventInterface $e)
@@ -65,17 +65,17 @@ return [
 ];
 ```
 
-If a user tries to access to an unauthorized resource (eg.: http://www.example.com/delete), he/she will be
-redirect to the "login" route if is not connected and to the "home" route otherwise (it must exists in your route config,
+If users try to access an unauthorized resource (eg.: http://www.example.com/delete), they will be
+redirected to the "login" route if is not connected and to the "home" route otherwise (it must exist in your route configuration
 of course) with the previous URL appended : http://www.example.com/login?redirectTo=http://www.example.com/delete
 
 You can prevent redirection when a user is connected (i.e. so that the user gets a 403 page) by setting `redirect_when_connected` to `false`.
 
 ### UnauthorizedStrategy
 
-This strategy allows to render a template on any unauthorized request.
+This strategy allows your application to render a template on any unauthorized request.
 
-To register it, copy-paste this code in your Module.php class:
+To register it, copy-paste this code into your Module.php class:
 
 ```php
 public function onBootstrap(EventInterface $e)