Skip to content

Commit 0a2a644

Browse files
alexmerlinalexmerlin
authored
Merge pull request #142 from dotkernel/issue-141
Issue #141: Added `v7` documentation
2 parents 64deaf7 + 98ab632 commit 0a2a644

53 files changed

Lines changed: 4756 additions & 3 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
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-admin -i {IDENTITY} -p {PASSWORD} -f {FIRST_NAME} -l {LAST_NAME}
9+
```
10+
11+
OR
12+
13+
```shell
14+
php ./bin/cli.php admin:create-admin --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+
> If the specified fields contain special characters, make sure you surround them with double quote signs this method does not allow specifying an admin role – newly created accounts will have a role of admin.
24+
25+
If the submitted data is valid, the outputted response is:
26+
27+
```text
28+
Admin account has been created.
29+
```
30+
31+
The new admin account is ready to use.
32+
33+
You can get more help with this command by running:
34+
35+
```shell
36+
php ./bin/cli.php help admin:create
37+
```

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

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
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+
+-------------------- 37 Routes ------+-------------------------------------+
16+
| Request method | Route name | Route path |
17+
+----------------+-------------------------------------+-------------------------------------+
18+
| GET | app::view-index | / |
19+
| GET | admin::list-admin | /admin |
20+
| POST | admin::create-admin | /admin |
21+
| GET | admin::view-account | /admin/account |
22+
| PATCH | admin::update-account | /admin/account |
23+
| GET | admin::list-role | /admin/role |
24+
| GET | admin::view-role | /admin/role/{uuid} |
25+
| DELETE | admin::delete-admin | /admin/{uuid} |
26+
| GET | admin::view-admin | /admin/{uuid} |
27+
| PATCH | admin::update-admin | /admin/{uuid} |
28+
| POST | app::create-error-report | /error-report |
29+
| POST | security::token | /security/token |
30+
| GET | user::list-user | /user |
31+
| POST | user::create-user | /user |
32+
| DELETE | user::delete-account | /user/account |
33+
| GET | user::view-account | /user/account |
34+
| PATCH | user::update-account | /user/account |
35+
| POST | user::create-account | /user/account |
36+
| POST | user::request-activate-account | /user/account/activate |
37+
| PATCH | user::activate-account | /user/account/activate/{hash} |
38+
| DELETE | user::delete-account-avatar | /user/account/avatar |
39+
| GET | user::view-account-avatar | /user/account/avatar |
40+
| POST | user::create-account-avatar | /user/account/avatar |
41+
| POST | user::recover-account | /user/account/recover |
42+
| POST | user::create-account-reset-password | /user/account/reset-password |
43+
| GET | user::check-account-reset-password | /user/account/reset-password/{hash} |
44+
| PATCH | user::update-account-reset-password | /user/account/reset-password/{hash} |
45+
| GET | user::list-role | /user/role |
46+
| GET | user::view-role | /user/role/{uuid} |
47+
| DELETE | user::delete-user | /user/{uuid} |
48+
| GET | user::view-user | /user/{uuid} |
49+
| PATCH | user::update-user | /user/{uuid} |
50+
| PATCH | user::activate-user | /user/{uuid}/activate |
51+
| DELETE | user::delete-user-avatar | /user/{uuid}/avatar |
52+
| GET | user::view-user-avatar | /user/{uuid}/avatar |
53+
| POST | user::create-user-avatar | /user/{uuid}/avatar |
54+
| PATCH | user::deactivate-user | /user/{uuid}/deactivate |
55+
+------+----------------+-------------------------------------+-------------------------------------+
56+
57+
```
58+
59+
## Filtering results
60+
61+
The following filters can be applied when displaying the route list:
62+
63+
* Filter routes by name, using: `-i|--name[=NAME]`
64+
* Filter routes by path, using: `-p|--path[=PATH]`
65+
* Filter routes by method, using: `-m|--method[=METHOD]`
66+
67+
The filters are case-insensitive and can be combined.
68+
69+
Get more help by running this command:
70+
71+
```shell
72+
php ./bin/cli.php route:list --help
73+
```

‎docs/book/v7/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+
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/v7/commands/generate-tokens.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
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+
> If your application is NOT in development mode, make sure you clear your config cache by executing:
61+
62+
```shell
63+
php ./bin/clear-config-cache.php
64+
```

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

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

0 commit comments

Comments
 (0)