Skip to content

Commit 01898ac

Browse files
alexmerlinalexmerlin
committed
Added v5 documentation
Signed-off-by: alexmerlin <[email protected]>
1 parent 7d5cf17 commit 01898ac

28 files changed

+2343
-1
lines changed

‎docs/book/v5/commands/create-admin-account.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Creating admin accounts in DotKernel API
2+
3+
## Usage
4+
5+
Run the following command in your application’s root directory:
6+
7+
```shell
8+
php ./bin/cli.php admin:create -i {IDENTITY} -p {PASSWORD} -f {FIRST_NAME} -l {LAST_NAME}
9+
```
10+
11+
OR
12+
13+
```shell
14+
php ./bin/cli.php admin:create --identity {IDENTITY} --password {PASSWORD} --firstName {FIRST_NAME} --lastName {LAST_NAME}
15+
```
16+
17+
after replacing:
18+
19+
* {IDENTITY} with a valid username OR email address
20+
* {PASSWORD} with a valid password
21+
* {FIRST_NAME} and {LAST_NAME} with valid names
22+
23+
**NOTE:**
24+
25+
* if the specified fields contain special characters, make sure you surround them with double quote signs
26+
* this method does not allow specifying an admin role – newly created accounts will have role of admin
27+
28+
If the submitted data is valid, the outputted response is:
29+
30+
```text
31+
Admin account has been created.
32+
```
33+
34+
The new admin account is ready to use.
35+
36+
You can get more help with this command by running:
37+
38+
```shell
39+
php ./bin/cli.php help admin:create
40+
```

‎docs/book/v5/commands/display-available-endpoints.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Displaying DotKernel API endpoints using dot-cli
2+
3+
## Usage
4+
5+
Run the following command in your application’s root directory:
6+
7+
```shell
8+
php ./bin/cli.php route:list
9+
```
10+
11+
The command runs through all routes and extracts endpoint information in realtime.
12+
The output should be similar to the following:
13+
14+
```text
15+
+--------+---------------------------------+--------------------------------+
16+
| Method | Name | Path |
17+
+--------+---------------------------------+--------------------------------+
18+
| POST | account.activate.request | /account/activate |
19+
| PATCH | account.activate | /account/activate/{hash} |
20+
| PATCH | account.modify-password | /account/reset-password/{hash} |
21+
| POST | account.recover-identity | /account/recover-identity |
22+
| POST | account.register | /account/register |
23+
| POST | account.reset-password.request | /account/reset-password |
24+
| GET | account.reset-password.validate | /account/reset-password/{hash} |
25+
| POST | admin.create | /admin |
26+
| DELETE | admin.delete | /admin/{uuid} |
27+
| GET | admin.list | /admin |
28+
| PATCH | admin.my-account.update | /admin/my-account |
29+
| GET | admin.my-account.view | /admin/my-account |
30+
| GET | admin.role.list | /admin/role |
31+
| GET | admin.role.view | /admin/role/{uuid} |
32+
| PATCH | admin.update | /admin/{uuid} |
33+
| GET | admin.view | /admin/{uuid} |
34+
| POST | error.report | /error-report |
35+
| GET | home | / |
36+
| POST | security.generate-token | /security/generate-token |
37+
| POST | security.refresh-token | /security/refresh-token |
38+
| POST | user.activate | /user/{uuid}/activate |
39+
| POST | user.avatar.create | /user/{uuid}/avatar |
40+
| DELETE | user.avatar.delete | /user/{uuid}/avatar |
41+
| GET | user.avatar.view | /user/{uuid}/avatar |
42+
| POST | user.create | /user |
43+
| DELETE | user.delete | /user/{uuid} |
44+
| GET | user.list | /user |
45+
| DELETE | user.my-account.delete | /user/my-account |
46+
| PATCH | user.my-account.update | /user/my-account |
47+
| GET | user.my-account.view | /user/my-account |
48+
| POST | user.my-avatar.create | /user/my-avatar |
49+
| DELETE | user.my-avatar.delete | /user/my-avatar |
50+
| GET | user.my-avatar.view | /user/my-avatar |
51+
| GET | user.role.list | /user/role |
52+
| GET | user.role.view | /user/role/{uuid} |
53+
| PATCH | user.update | /user/{uuid} |
54+
| GET | user.view | /user/{uuid} |
55+
+--------+---------------------------------+--------------------------------+
56+
```
57+
58+
## Filtering results
59+
60+
The following filters can be applied when displaying the routes list:
61+
62+
* Filter routes by name, using: `-i|--name[=NAME]`
63+
* Filter routes by path, using: `-p|--path[=PATH]`
64+
* Filter routes by method, using: `-m|--method[=METHOD]`
65+
66+
The filters are case-insensitive and can be combined.
67+
68+
Get more help by running this command:
69+
70+
```shell
71+
php ./bin/cli.php route:list --help
72+
```

‎docs/book/v5/commands/generate-database-migrations.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Generate a database migration without dropping custom tables
2+
3+
## Usage
4+
5+
Run the following command in your application’s root directory:
6+
7+
```shell
8+
vendor/bin/doctrine-migrations diff
9+
```
10+
11+
If you have mapping modifications, this will create a new migration file under `data/doctrine/migrations/` directory.
12+
Opening the migration file, you will notice that it contains some queries that will drop your `oauth_*` tables because they are unmapped (there is no doctrine entity describing them).
13+
You should delete your latest migration with the DROP queries in it as we will create another one, without the DROP queries in it.
14+
In order to avoid dropping these tables, you need to add a parameter called `filter-expression`.
15+
16+
The command to be executed without dropping these tables looks like this:
17+
18+
On Windows (use double quotes):
19+
20+
```shell
21+
vendor/bin/doctrine-migrations diff --filter-expression="/^(?!oauth_)/"
22+
```
23+
24+
On Linux/macOS (use single quotes):
25+
26+
```shell
27+
vendor/bin/doctrine-migrations diff --filter-expression='/^(?!oauth_)/'
28+
```
29+
30+
## Filtering multiple unmapped table patterns
31+
32+
If your database contains multiple unmapped table groups, then the pattern in `filter-expression` should hold all table prefixes concatenated by pipe character (`|`).
33+
For example, if you need to filter tables prefixed with `foo_` and `bar_`, then the command should look like this:
34+
35+
On Windows:
36+
37+
```shell
38+
vendor/bin/doctrine-migrations diff --filter-expression="/^(?!foo_|bar_)/"
39+
```
40+
41+
On Linux/macOS:
42+
43+
```shell
44+
vendor/bin/doctrine-migrations diff --filter-expression='/^(?!foo_|bar_)/'
45+
```
46+
47+
## Troubleshooting
48+
49+
On Windows, running the command in PowerShell might still add the `DROP TABLE oauth_*` queries to the migration file.
50+
This happens because for PowerShell the caret (`^`) is a special character, so it gets dropped (`"/^(?!oauth_)/"` becomes `"/(?!oauth_)/"` when it reaches your command).
51+
Escaping it will not help either.
52+
In this case, we recommend running the command:
53+
54+
* directly from your IDE
55+
* using `Linux shell`
56+
* from the `Command Prompt`
57+
58+
## Help
59+
60+
You can get more help with this command by running:
61+
62+
```shell
63+
vendor/bin/doctrine-migrations help diff
64+
```

‎docs/book/v5/commands/generate-tokens.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Generating tokens in DotKernel API
2+
3+
This is a multipurpose command that allows creating tokens required by different parts of the API.
4+
5+
## Usage
6+
7+
Go to your application's root directory.
8+
9+
Run the token generator command by executing the following command:
10+
11+
```shell
12+
php ./bin/cli.php token:generate <type>
13+
```
14+
15+
Where `<type>` is one of the following:
16+
17+
* [error-reporting](#generate-error-reporting-token)
18+
19+
If you need help using the command, execute the following command:
20+
21+
```shell
22+
php ./bin/cli.php token:generate --help
23+
```
24+
25+
### Generate error reporting token
26+
27+
You can generate an error reporting token by executing the following command:
28+
29+
```shell
30+
php ./bin/cli.php token:generate error-reporting
31+
```
32+
33+
The output should look similar to this:
34+
35+
```text
36+
Error reporting token:
37+
38+
0123456789abcdef0123456789abcdef01234567
39+
```
40+
41+
Copy the generated token.
42+
43+
Open `config/autoload/error-handling.global.php` and paste the copied token as shown below:
44+
45+
```php
46+
return [
47+
...
48+
ErrorReportServiceInterface::class => [
49+
...
50+
'tokens' => [
51+
'0123456789abcdef0123456789abcdef01234567',
52+
],
53+
...
54+
]
55+
]
56+
```
57+
58+
Save and close `config/autoload/error-handling.global.php`.
59+
60+
**Note**:
61+
62+
If your application is NOT in development mode, make sure you clear your config cache by executing:
63+
64+
```shell
65+
php ./bin/clear-config-cache.php
66+
```

‎docs/book/v5/core-features/authentication.md

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Authentication
2+
3+
Authentication is the process by which an identity is presented to the application. It ensures that the entity
4+
making the request has the proper credentials to access the API.
5+
6+
**DotKernel API** identities are delivered to the application from the client through the `Authorization` request.
7+
If it is present, the application tries to find and assign the identity to the application. If it is not presented,
8+
DotKernel API assigns a default `guest` identity, represented by an instance of the class
9+
`Mezzio\Authentication\UserInterface`.
10+
11+
## Configuration
12+
13+
Authentication in DotKernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already
14+
configured out of the box. But if you want to dig more, the configuration is stored in
15+
`config/autoload/local.php` under the `authentication` key.
16+
17+
> You can check the
18+
> [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)
19+
> configuration part for more info.
20+
21+
## How it works
22+
23+
DotKernels API authentication system can be used for SPAs (single-page applications), mobile applications, and
24+
simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts.
25+
26+
The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
27+
28+
## Database
29+
30+
When you install **DotKernel API** for the first time, you need to run the migrations and seeders. All the tables
31+
required for authentication are automatically created and populated.
32+
33+
In DotKernel API, authenticated users come from either the `admin` or the `user` table. We choose to keep the admin
34+
table separated from the users to prevent users of the application from accessing sensitive data, which only the
35+
administrators of the application should access.
36+
37+
The `oauth_clients` table is pre-populated with the default `admin` and `frontend` clients with the same password as
38+
their names (**we recommend you change the default passwords**).
39+
40+
As you guessed each client serves to authenticate `admin` or `user`.
41+
42+
Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
43+
44+
### Issuing API Tokens
45+
46+
Token generation in DotKernel API is done using the `password` `grand_type` scenario, which in this case allows
47+
authentication to an API using the user's credentials (generally a username and password).
48+
49+
The client sends a POST request to the `/security/generate-token` with the following parameters:
50+
51+
- `grant_type` = password.
52+
- `client_id` = column `name` from the `oauth_clients` table
53+
- `client_secret` = column `secret` from the `oauth_clients` table
54+
- `scope` = column `scope` from the `oauth_scopes` table
55+
- `username` = column `identity` from table `admin`/`user`
56+
- `password` = column `password` from table `admin`/`user`
57+
58+
```shell
59+
POST /security/generate-token HTTP/1.1
60+
Accept: application/json
61+
Content-Type: application/json
62+
{
63+
"grant_type": "password",
64+
"client_id": "frontend",
65+
"client_secret": "frontend",
66+
"scope": "api",
67+
"username": "[email protected]",
68+
"password": "dotkernel"
69+
}
70+
```
71+
72+
The server responds with a JSON as follows:
73+
74+
```json
75+
{
76+
"token_type": "Bearer",
77+
"expires_in": 86400,
78+
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
79+
"refresh_token": "def5020087199939a49d0f2f818..."
80+
}
81+
```
82+
83+
Next time when you make a request to the server to an authenticated endpoint, the client should use
84+
the `Authorization` header request.
85+
86+
```shell
87+
GET /users/1 HTTP/1.1
88+
Accept: application/json
89+
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
90+
```
91+
92+
### Refreshing tokens
93+
94+
DotKernel API can refresh the access token, based on the expired access token's `refresh_token`.
95+
96+
The clients need to send a `POST` request to the `/security/refresh-token` with the following request
97+
98+
```shell
99+
POST /security/refresh-token HTTP/1.1
100+
Accept: application/json
101+
Content-Type: application/json
102+
{
103+
"grant_type": "refresh_token",
104+
"client_id": "frontend",
105+
"client_secret": "frontend",
106+
"scope": "api",
107+
"refresh_token" : "def5020087199939a49d0f2f818..."
108+
}
109+
```
110+
111+
The server responds with a JSON as follows:
112+
113+
```json
114+
{
115+
"token_type": "Bearer",
116+
"expires_in": 86400,
117+
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
118+
"refresh_token": "def5020087199939a49d0f2f818..."
119+
}
120+
```

0 commit comments

Comments
 (0)