You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Dependency injection is a design pattern used in software development to implement inversion of control. In simpler
4
-
terms, it's the act of providing dependencies for an object during instantiation.
3
+
> Introduced in Dotkernel API 5.0.0
5
4
6
-
In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter
7
-
injection and property injection.
5
+
Dependency injection is a design pattern used in software development to implement inversion of control.
6
+
In simpler terms, it's the act of providing dependencies for an object during instantiation.
8
7
9
-
Dotkernel API, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package
10
-
focuses only on constructor injection.
8
+
In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter injection and property injection.
9
+
10
+
Dotkernel API, through its [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package focuses only on constructor injection.
11
11
12
12
## Usage
13
13
14
-
**Dotkernel API** comes out of the box with the
15
-
[dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all we need for
16
-
injecting dependencies into any object you want.
14
+
**Dotkernel API** comes out of the box with the [dot-dependency-injection](https://github.com/dotkernel/dot-dependency-injection) package, which provides all we need for injecting dependencies into any object you want.
17
15
18
-
`dot-dependency-injection` determines the dependencies by looking at the `#[Inject]` attribute, added to the constructor
19
-
of a class. Dependencies are specified as separate parameters of the `#[Inject]` attribute.
16
+
`dot-dependency-injection` determines the dependencies by looking at the `#[Inject]` attribute, added to the constructor of a class.
17
+
Dependencies are specified as separate parameters of the `#[Inject]` attribute.
20
18
21
19
For our example we will inject `UserService` and `config` dependencies into a `UseHandler`.
22
20
@@ -37,11 +35,9 @@ class UserHandler implements RequestHandlerInterface
37
35
}
38
36
```
39
37
40
-
> If your class needs the value of a specific configuration key, you can specify the path using dot notation:
41
-
> `config.example`
38
+
> If your class needs the value of a specific configuration key, you can specify the path using dot notation `config.example`.
42
39
43
-
The next step is to register the class in the `ConfigProvider` under `factories` using
The next step is to register the class in the `ConfigProvider` under `factories` using `Dot\DependencyInjection\Factory\AttributedServiceFactory::class`
45
41
46
42
```php
47
43
public function getDependencies(): array
@@ -54,8 +50,8 @@ public function getDependencies(): array
54
50
}
55
51
```
56
52
57
-
That's it. When your object is instantiated from the container, it will automatically have its
58
-
dependencies resolved.
53
+
That's it.
54
+
When your object is instantiated from the container, it will automatically have its dependencies resolved.
59
55
60
-
> Dependencies injection is available to any object within Dotkernel API. For example, you can inject dependencies in a
61
-
> service, a handler and so on, simply by registering it in the `ConfigProvider`.
56
+
> Dependencies injection is available to any object within Dotkernel API.
57
+
> For example, you can inject dependencies in a service, a handler and so on, simply by registering it in the `ConfigProvider`.
Copy file name to clipboardExpand all lines: docs/book/v5/core-features/error-reporting.md
+2Lines changed: 2 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,7 @@
1
1
# Error reporting endpoint
2
2
3
+
> Backward incompatibility introduced in Dotkernel API 4.1.0
4
+
3
5
The error reporting endpoint was designed to allow the **frontend developers** of your API to report any bugs they encounter in a secure way that is fully under your control.
4
6
To prevent unauthorized usage, the endpoint is protected by a token in the request's header.
Copy file name to clipboardExpand all lines: docs/book/v5/core-features/exceptions.md
+25-36Lines changed: 25 additions & 36 deletions
Original file line number
Diff line number
Diff line change
@@ -2,61 +2,50 @@
2
2
3
3
## What are exceptions?
4
4
5
-
Exceptions are a powerful mechanism for handling errors and other exceptional conditions that may occur during the
6
-
execution of a script.
7
-
They provide a way to manage errors in a structured and controlled manner, separating error-handling code from regular
8
-
code.
5
+
Exceptions are a powerful mechanism for handling errors and other exceptional conditions that may occur during the execution of a script.
6
+
They provide a way to manage errors in a structured and controlled manner, separating error-handling code from regular code.
9
7
10
-
## How we use exceptions?
8
+
## How we use exceptions
11
9
12
-
When it comes to handling exceptions, **Dotkernel API** relies on the usage of easy-to-understand, problem-specific
13
-
exceptions.
14
-
15
-
Out-of-the-box we provide the following custom exceptions:
10
+
When it comes to handling exceptions, **Dotkernel API** relies on the usage of easy-to-understand, problem-specific exceptions.
11
+
Below we will list the available custom exceptions.
16
12
17
13
### `BadRequestException` thrown when
18
14
19
-
* client tries to create/update resource, but the data from the request is invalid/incomplete (example: client tries to
20
-
create an account, but does not send the required `identity` field)
15
+
* The Client tries to **create/update resource**, but the **request data is invalid/incomplete** (example: client tries to create an account, but does not send the required `identity` field)
21
16
22
17
### `ConflictException` thrown when
23
18
24
-
* resource cannot be created because a different resource with the same identifier already exists (example: cannot
25
-
change existing user's identity because another user with the same identity already exists)
26
-
* resource cannot change its state because it is already in the specified state (example: user cannot be activated
27
-
because it is already active)
19
+
* The **resource cannot be created** because a different resource with the same identifier **already exists** (example: cannot change existing user's identity because another user with the same identity already exists)
20
+
* The **resource cannot change its state** because it is **already in the specified state** (example: user cannot be activated because it is already active)
28
21
29
22
### `ExpiredException` thrown when
30
23
31
-
* resource cannot be accessed because it expired (example: account activation link)
32
-
* resource cannot be accessed because it has been consumed (example: one-time password)
24
+
* The **resource cannot be accessed**
25
+
* because it has **expired** (example: account activation link)
26
+
* because it has been **consumed** (example: one-time password)
33
27
34
28
### `ForbiddenException` thrown when
35
29
36
-
* resource cannot be accessed by the authenticated client (example: client authenticated as regular user sends
37
-
a `GET /admin` request)
30
+
* The **resource cannot be accessed** by the authenticated client's **role** (example: client authenticated as regular user sends a `GET /admin` request)
38
31
39
32
### `MethodNotAllowedException` thrown when
40
33
41
-
* client tries to interact with a resource via an invalid HTTP request method (example: client sends a `PATCH /avatar`
42
-
request)
34
+
* The client tries to interact with a resource via an **invalid HTTP request method** (example: client sends a `PATCH /avatar` request)
43
35
44
36
### `NotFoundException` thrown when
45
37
46
-
* client tries to interact with a resource that does not exist on the server (example: client sends
47
-
a `GET /resource-does-not-exist` request)
38
+
* The client tries to interact with a **resource that does not exist** on the server (example: client sends a `GET /resource-does-not-exist` request)
48
39
49
40
### `UnauthorizedException` thrown when
50
41
51
-
* resource cannot be accessed because the client is not authenticated (example: unauthenticated client sends
52
-
a `GET /admin` request)
42
+
* The **resource cannot be accessed** because the **client is not authenticated** (example: unauthenticated client sends a `GET /admin` request)
53
43
54
-
## How it works?
44
+
## How it works
55
45
56
-
During a request, if there is no uncaught exception **Dotkernel API** will return a JSON response with the data provided
57
-
by the handler that handled the request.
46
+
During a request, if there is no uncaught exception, **Dotkernel API** will return a JSON response with the data provided by the handler that processed the request.
58
47
59
-
Else, it will build and send a response based on the exception thrown:
48
+
Otherwise, it will build and send a response based on the exception thrown:
60
49
61
50
*`BadRequestException` will return a `400 Bad Request` response
62
51
*`UnauthorizedException` will return a `401 Unauthorized` response
@@ -67,11 +56,12 @@ Else, it will build and send a response based on the exception thrown:
67
56
*`ExpiredException` will return a `410 Gone` response
68
57
*`MailException`, `RuntimeException` and the generic `Exception` will return a `500 Internal Server Error` response
69
58
70
-
## How to extend?
59
+
## How to extend
71
60
72
-
In this example we will create a custom exception called `CustomException`, place it next to the already existing custom
73
-
exceptions (you can use your preferred location) and finally return a custom HTTP status code when `CustomException` is
74
-
encountered.
61
+
In this example we will
62
+
* Create a custom exception called `CustomException`
63
+
* Place it next to the already existing custom exceptions (you can use your preferred location)
64
+
* Return a custom HTTP status code when `CustomException` is encountered.
75
65
76
66
### Step 1: Create exception file
77
67
@@ -106,8 +96,7 @@ Save and close the file.
106
96
107
97
### Step 3: Test for failure
108
98
109
-
Access your API's home page URL and make sure it returns `500 Internal Server Error` HTTP status code and the following
110
-
content:
99
+
Access your API's home page URL and make sure it returns `500 Internal Server Error` HTTP status code and the following content:
111
100
112
101
```json
113
102
{
@@ -133,5 +122,5 @@ Save and close the file.
133
122
134
123
### Step 5: Test for success
135
124
136
-
Again, access your API's home page URL, which should return the same content.
125
+
Access your API's home page URL, which should return the same content.
137
126
Notice that this time it returns `418 I'm a teapot` HTTP status code.
Copy file name to clipboardExpand all lines: docs/book/v5/tutorials/api-evolution.md
+11-13Lines changed: 11 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,6 @@
1
1
# API Evolution pattern
2
2
3
-
API evolution: Updating an API while keeping it compatible for existing consumers by adding new features, fixing bugs,
4
-
planning and removing outdated features.
3
+
API evolution: Updating an API while keeping it compatible for existing consumers by adding new features, fixing bugs, planning and removing outdated features.
5
4
6
5
## How it works
7
6
@@ -13,10 +12,10 @@ We use response headers to inform the consumers about the future changes by usin
13
12
14
13
**Both headers are independent, you can use them separately.**
15
14
16
-
> Make sure you have the `DeprecationMiddleware:class` piped in your `pipeline` list. In our case it's
17
-
> `config/pipeline.php`.
15
+
> Make sure you have the `DeprecationMiddleware:class` piped in your `pipeline` list.
16
+
> In our case it's `config/pipeline.php`.
18
17
19
-
###Marking an entire endpoint as deprecated
18
+
## Marking an entire endpoint as deprecated
20
19
21
20
When you want to mark an entire resource as deprecated you have to use the `ResourceDeprecation` attribute.
22
21
@@ -34,8 +33,7 @@ class HomeHandler implements RequestHandlerInterface
34
33
...
35
34
```
36
35
37
-
In the example above, the ``ResourceDeprecation`` attribute is attached to the class, marking the entire `/` (home)
38
-
endpoint as deprecated starting from `2038-01-01`.
36
+
In the example above, the `ResourceDeprecation` attribute is attached to the class, marking the entire `/` (home) endpoint as deprecated starting from `2038-01-01`.
39
37
40
38
Running the following curl will print out the response headers where we can see the **Sunset** and **Link** headers.
Most of the time you want to deprecate only an endpoint, so you will need to use the `MethodDeprecation` attribute which
62
-
has the same parameters, but it attaches to a handler method.
59
+
Most of the time you want to deprecate only an endpoint, so you will need to use the `MethodDeprecation` attribute which has the same parameters, but it attaches to a handler method.
63
60
64
61
```php
65
62
...
@@ -90,6 +87,8 @@ If you followed along you can run the below curl:
90
87
curl --head -X GET http://0.0.0.0:8080 -H "Content-Type: application/json"
91
88
```
92
89
90
+
The response lists the **Sunset** and **Link** headers.
0 commit comments