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
+
Dependency injection is a design pattern used in software development to implement inversion of control.
4
+
In simpler terms, it's the act of providing dependencies for an object during instantiation.
5
5
6
-
In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter
7
-
injection and property injection.
6
+
In PHP, dependency injection can be implemented in various ways, including through constructor injection, setter injection and property injection.
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
+
> Introduced in Dotkernel API 5.0.0
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/exceptions.md
+26-36Lines changed: 26 additions & 36 deletions
Display the source diff
Display the rich diff
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,13 @@ 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
60
+
61
+
In this example we will
71
62
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.
63
+
* Create a custom exception called `CustomException`
64
+
* Place it next to the already existing custom exceptions (you can use your preferred location)
65
+
* Return a custom HTTP status code when `CustomException` is encountered.
75
66
76
67
### Step 1: Create exception file
77
68
@@ -106,8 +97,7 @@ Save and close the file.
106
97
107
98
### Step 3: Test for failure
108
99
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:
100
+
Access your API's home page URL and make sure it returns `500 Internal Server Error` HTTP status code and the following content:
111
101
112
102
```json
113
103
{
@@ -133,5 +123,5 @@ Save and close the file.
133
123
134
124
### Step 5: Test for success
135
125
136
-
Again, access your API's home page URL, which should return the same content.
126
+
Access your API's home page URL, which should return the same content.
137
127
Notice that this time it returns `418 I'm a teapot` HTTP status code.
This directory is a storage for project data files and service caches.
70
+
It contains these folders:
71
+
72
+
*`cache`: cache for e.g. Twig files
73
+
*`doctrine`: database migrations and fixtures
74
+
*`oauth`: encryption, private and public keys needed for authentication
75
+
*`data/lock` - lock files generated by [`dotkernel/dot-cli`](https://docs.dotkernel.org/dot-cli/v3/lock-files/)
76
+
77
+
> AVOID storing sensitive data on VCS.
78
+
79
+
### `log` directory
80
+
81
+
This directory stores daily log files.
82
+
When you access the application from the browser, (if not already created) a new log file gets created in the format specified in the `config/autoload/error-handling.global.php` config file under the `stream` array key.
83
+
84
+
### `public` directory
85
+
86
+
This directory contains all publicly available assets and serves as the entry point of the application:
87
+
88
+
*`uploads`: a folder that normally contains files uploaded via the application
89
+
*`.htaccess`: server configuration file used by Apache web server; it enables the URL rewrite functionality
90
+
*`index.php`: the application's main entry point
91
+
*`robots.txt.dist`: a sample robots.txt file that allows/denies bot access to certain areas of your application; activate it by duplicating the file as `robots.txt` and comment out the lines that don't match your environment
92
+
27
93
## `src` directory
28
94
29
-
This directory contains all source code related to the Module. It should contain following directories, if they’re not empty:
95
+
This folder contains a separate folder for each Module.
96
+
Each Module folder, in turn, should contain following directories, unless they are empty:
30
97
31
98
* Handler - Action classes (similar to Controllers but can only perform one action)
32
-
* Entity - For database entities
99
+
* Entity - Used by database entities
33
100
* Service - Service classes
34
101
* Collection - Database entities collections
35
102
* Repository - Entity repository folder
36
103
37
-
> The above example is just some of the directories a project may include, but these should give you an idea of how the structure should look like.
104
+
> The above example is just some of the directories a project may include, but they should give you an idea about the recommended structure.
38
105
39
106
Other classes in the `src` directory may include `InputFilter`, `EventListener`, `Helper`, `Command`, `Factory` etc.
40
107
41
-
The `src` directory should also contain 2 files:
108
+
The `src` directory normally also contains these files:
42
109
43
-
*`ConfigProvider.php` - Provides configuration data
44
-
*`RoutesDelegator.php` - Module main routes entry file
110
+
*`ConfigProvider.php` - Configuration data for the module
111
+
*`OpenAPI.php` - Detailed descriptions for each endpoint in the OpenAPI format
112
+
*`RoutesDelegator.php` - Module specific route registrations Module main routes entry file
45
113
46
114
## `templates` directory
47
115
48
116
This directory contains the template files, used for example to help render e-mail templates.
49
117
50
118
> Dotkernel API uses twig as Templating Engine. All template files have the extension .html.twig
51
-
52
-
## `data` directory
53
-
54
-
This directory contains project-related data (such as cache, file uploads)
55
-
56
-
We recommend using the following directory structure:
57
-
58
-
*`data/cache` - location where caches are stored
59
-
*`data/oauth` - encryption, private and public keys needed for authentication.
60
-
*`data/doctrine` - fixtures and migrations
61
-
*`data/lock` - lock files generated by `dotkernel/dot-cli`[See more](https://docs.dotkernel.org/dot-cli/v3/lock-files/)
* Mechanism for event-based extension and collaboration
26
+
* Interfaces implemented in [php-fig/event-dispatcher](https://github.com/php-fig/event-dispatcher)
27
+
* PSR-15: [HTTP Server Request Handlers](https://www.php-fig.org/psr/psr-15/)
28
+
* Interfaces for HTTP server request handlers and HTTP server middleware components that use HTTP messages
29
+
* Interfaces implemented in [php-fig/http-server-handler](https://github.com/php-fig/http-server-handler) and [php-fig/http-server-middleware](https://github.com/php-fig/http-server-middleware)
0 commit comments