Skip to content

Commit fc3ed11

Browse files
committed
Use one sentence per line in authorization docs
Unwraps ten sentences and splits two shared lines. No wording changes. Signed-off-by: arhimede <julian@dotkernel.com>
1 parent f76decb commit fc3ed11

1 file changed

Lines changed: 14 additions & 29 deletions

File tree

‎docs/book/v7/core-features/authorization.md‎

Lines changed: 14 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,7 @@ Dotkernel API makes use of `mezzio-authorization-rbac` and includes the full con
2525

2626
The configuration file for the role and permission definitions is `config/autoload/authorization.global.php`.
2727

28-
Roles are the backed enums `Core\Admin\Enum\AdminRoleEnum` (`superuser`, `admin`) and
29-
`Core\User\Enum\UserRoleEnum` (`user`, `guest`), so the array keys are their `->value` strings.
28+
Roles are the backed enums `Core\Admin\Enum\AdminRoleEnum` (`superuser`, `admin`) and `Core\User\Enum\UserRoleEnum` (`user`, `guest`), so the array keys are their `->value` strings.
3029

3130
```php
3231
use Core\Admin\Enum\AdminRoleEnum;
@@ -97,28 +96,21 @@ return [
9796
```
9897

9998
That is the complete shipped configuration, not an excerpt.
100-
Between them the three populated roles grant **38 permissions covering all 38 routes**: every route
101-
the application declares is reachable by at least one role, and no permission names a route that
102-
does not exist.
99+
Between them the three populated roles grant **38 permissions covering all 38 routes**: every route the application declares is reachable by at least one role, and no permission names a route that does not exist.
103100
Only `app::view-index` and `app::create-error-report` are granted twice, to both `admin` and `guest`.
104101

105-
> See [mezzio-authorization-rbac](https://docs.mezzio.dev/mezzio-authorization-rbac/v1/basic-usage/)
106-
> for more information.
102+
> See [mezzio-authorization-rbac](https://docs.mezzio.dev/mezzio-authorization-rbac/v1/basic-usage/) for more information.
107103
108104
## Usage
109105

110-
Based on the configuration file above, we have two admin roles (`superuser`, `admin`) and two user
111-
roles (`user`, `guest`).
106+
Based on the configuration file above, we have two admin roles (`superuser`, `admin`) and two user roles (`user`, `guest`).
112107

113-
A permission in Dotkernel API is a **route name** — the third argument given to the route in a
114-
module's `RoutesDelegator`. To list the names you can grant, run
115-
`php ./bin/cli.php route:list`; see [Displaying Dotkernel API endpoints](../commands/display-available-endpoints.md).
108+
A permission in Dotkernel API is a **route name** — the third argument given to the route in a module's `RoutesDelegator`.
109+
To list the names you can grant, run `php ./bin/cli.php route:list`; see [Displaying Dotkernel API endpoints](../commands/display-available-endpoints.md).
116110

117111
### How inheritance works here
118112

119-
The array under `roles` maps a role to its **parents**, and inheritance runs in the direction that
120-
often surprises people: a **parent receives the permissions of its children**, because
121-
`laminas-permissions-rbac` resolves `hasPermission()` by walking down into child roles.
113+
The array under `roles` maps a role to its **parents**, and inheritance runs in the direction that often surprises people: a **parent receives the permissions of its children**, because `laminas-permissions-rbac` resolves `hasPermission()` by walking down into child roles.
122114

123115
So in the shipped configuration:
124116

@@ -128,12 +120,9 @@ So in the shipped configuration:
128120
| `admin => [superuser]` | `superuser` is the parent of `admin`, so **`superuser` inherits everything granted to `admin`** |
129121
| `guest => [user]` | `user` is the parent of `guest`, so **`user` inherits everything granted to `guest`** |
130122

131-
That is why `superuser` needs no permissions of its own: its list is empty, yet it can reach all 23
132-
routes granted to `admin`.
123+
That is why `superuser` needs no permissions of its own: its list is empty, yet it can reach all 23 routes granted to `admin`.
133124

134-
It is also why `user` ends up with 17 effective permissions — its own 6 plus the 11 granted to
135-
`guest` — while `guest` keeps only its own 11 and cannot reach the account routes reserved for a
136-
signed-in user.
125+
It is also why `user` ends up with 17 effective permissions — its own 6 plus the 11 granted to `guest` — while `guest` keeps only its own 11 and cannot reach the account routes reserved for a signed-in user.
137126

138127
Effective totals, once inheritance is applied:
139128

@@ -146,23 +135,19 @@ Effective totals, once inheritance is applied:
146135

147136
### How a request is authorized
148137

149-
`AuthorizationMiddleware` injects `Mezzio\Authorization\AuthorizationInterface` rather than an RBAC
150-
class directly — the RBAC adapter is bound by `Mezzio\Authorization\Rbac\ConfigProvider`, registered
151-
in `config/config.php`.
138+
`AuthorizationMiddleware` injects `Mezzio\Authorization\AuthorizationInterface` rather than an RBAC class directly — the RBAC adapter is bound by `Mezzio\Authorization\Rbac\ConfigProvider`, registered in `config/config.php`.
152139

153140
For each request it:
154141

155-
1. Reads `oauth_client_id` from the authenticated identity and loads the matching record — `admin` from the `admin` table, `frontend` from the `user` table, or a `Guest` instance when the client is `guest`. An unrecognised client is rejected.
142+
1. Reads `oauth_client_id` from the authenticated identity and loads the matching record — `admin` from the `admin` table, `frontend` from the `user` table, or a `Guest` instance when the client is `guest`.
143+
An unrecognised client is rejected.
156144
2. Rejects an account that is inactive, or a user that has been deleted.
157145
3. Replaces the identity's roles with the role names read from that record.
158146
4. Calls `isGranted()` once per role and allows the request as soon as **any** role grants the route.
159147

160-
If no role grants it, the response is `403 Forbidden` with
161-
`You are not allowed to access this resource.`
148+
If no role grants it, the response is `403 Forbidden` with `You are not allowed to access this resource.`
162149

163-
> Note this middleware returns a plain JSON error body rather than a Problem Details document, so an
164-
> authorization failure does not look like the errors described in
165-
> [Problem details](../extended-features/problem-details.md).
150+
> Note this middleware returns a plain JSON error body rather than a Problem Details document, so an authorization failure does not look like the errors described in [Problem details](../extended-features/problem-details.md).
166151
167152
## FAQ
168153

0 commit comments

Comments
 (0)