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
* All Exceptions that should terminate the current request (and return an error message to the user) should be handled
25
-
using Symfony [best practice](https://symfony.com/doc/current/controller/error_pages.html#use-kernel-exception-event).
26
-
* All Exceptions that should be handled in the controller, or just logged for debugging, should be wrapped in a
27
-
try catch block (catchable Exceptions).
24
+
* All Exceptions that should terminate the current request (and return an error message to the user) should be handled using Symfony [best practice](https://symfony.com/doc/current/controller/error_pages.html#use-kernel-exception-event).
25
+
* All Exceptions that should be handled in the controller, or just logged for debugging, should be wrapped in a try catch block (catchable Exceptions).
28
26
* Use custom Exceptions for all catchable scenarios, and try to use standard Exceptions for fatal Exceptions.
29
27
* Use custom Exceptions to log.
30
28
31
29
#### Entities
32
-
Entities should only be data-persistence layers, i.e. defines relationships, attributes, helper methods
33
-
but does not fetch collections of data. Entities are located on the Domain layer (according to DDD approach) and shouldn't
34
-
know anything about other layers (Application/Infrastructure) or framework. In this application we made some "exception"
35
-
for such components like Doctrine/Swagger/Serializer/Validator (for the first time) and you can find such
36
-
dependencies inside Entities.
37
-
38
-
Within this application we are using uuid v1 for the primary key inside Entities. Also we have id field as
39
-
binary type ([details](https://uuid.ramsey.dev/en/stable/database.html#using-as-a-primary-key)). If you need to convert
40
-
id into binary ordered time or from bin ordered time into a string inside query, please use MySql 8 internal functions [UUID_TO_BIN](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid-to-bin) and [BIN_TO_UUID](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_bin-to-uuid).
30
+
Entities should only be data-persistence layers, i.e. defines relationships, attributes, helper methods but does not fetch collections of data.
31
+
Entities are located on the Domain layer (according to DDD approach) and shouldn't know anything about other layers (Application/Infrastructure) or framework.
32
+
In this application we made some "exception" for such components like Doctrine/Swagger/Serializer/Validator (for the first time) and you can find such dependencies inside Entities.
33
+
34
+
Inside this application we are using uuid v1 for the primary key inside Entities. Also we have id field as binary type ([details](https://uuid.ramsey.dev/en/stable/database.html#using-as-a-primary-key)).
35
+
If you need to convert id into binary ordered time or from bin ordered time into a string inside query, please use MySql 8 internal functions [UUID_TO_BIN](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid-to-bin) and [BIN_TO_UUID](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_bin-to-uuid).
41
36
For instance `... WHERE id = UUID_TO_BIN(:id, 1)`, or when you need to convert uuid binary ordered time into string representative `... WHERE BIN_TO_UUID(id, 1) = :id`.
42
-
The second argument determines if the byte order should be swapped, therefore when using uuid_binary you should pass 0 and when using uuid_binary_ordered_time you should pass 1.
37
+
The second argument determines if the byte order should be swapped. Therefore, when using uuid_binary, you should pass 0. When using uuid_binary_ordered_time you should pass 1.
43
38
44
39
#### Repositories
45
-
Repositories need to be responsible for parameter handling and query builder callbacks/joins. Should be located on
46
-
infrastructure layer. Parameter handling can help with generic REST queries.
40
+
Repositories need to be responsible for parameter handling and query builder callbacks/joins. Should be located on infrastructure layer. Parameter handling can help with generic REST queries.
47
41
48
42
#### Resources
49
-
Resource services are services between your controller/command and repository. Should be located on application layer.
50
-
Within this service it is possible to control how to `mutate` repository data for application needs.
43
+
Resource services are services between controller/command and repository. Should be located on application layer.
44
+
Inside this service it is possible to control how to `mutate` repository data for application needs.
51
45
Resource services are basically the application foundation and it can control your request and response as you like.
52
-
We have provided 2 examples how to build resource services: 1)resource with all-in-one actions (create/update/delete/etc, see example src/ApiKey/Application/Resource/ApiKeyResource.php)
46
+
47
+
We have provided 2 examples how to build resource services:
48
+
49
+
1)resource with all-in-one actions (create/update/delete/etc, see example src/ApiKey/Application/Resource/ApiKeyResource.php)
50
+
53
51
2)resource with single responsibility (f.e. count, see example src/ApiKey/Application/Resource/ApiKeyCountResource.php).
54
52
55
53
#### Controllers
56
-
Should be located on Transport layer. Keep controllers clean of application logic. They should ideally just inject
54
+
Should be located on the Transport layer. Keep controllers clean of application logic. They should ideally just inject
57
55
resources/services - either through the constructor (if used more than once) or in the controller method itself.
58
-
We have provided 2 examples how to build controllers: 1)controller with all-in-one actions (create/update/delete/etc, see example src/ApiKey/Transport/Controller/Api/v1/ApiKey/ApiKeyController.php)
56
+
57
+
We have provided 2 examples how to build controllers:
58
+
59
+
1)controller with all-in-one actions (create/update/delete/etc, see example src/ApiKey/Transport/Controller/Api/v1/ApiKey/ApiKeyController.php)
60
+
59
61
2)controller with single responsibility (f.e. count, see example src/ApiKey/Transport/Controller/Api/v2/ApiKey/ApiKeyCountController.php)
60
62
61
63
#### Events
@@ -70,7 +72,7 @@ Isolate 3rd party dependencies into Service classes for simple refactoring/exten
70
72
71
73
## PHP code quality
72
74
You can control code quality of your PHP project using already integrated code quality tools. Before creating merge request you can run on your local PC code quality tools and get the report with issues that you can fix.
73
-
Also code quality tools integrated inside CI environment and after creating merge request you can check if you have some issues inside your code. Please find the list of code quality tools that we recommend to use while PHP backend development.
75
+
Also code quality tools integrated inside CI environment and, after creating merge request, you can check if you have some issues inside your code. Please find the list of code quality tools that we recommend to use for PHP backend development.
74
76
75
77
### PHP coding standard
76
78
This tool is an essential development tool that ensures your code remains coding standard.
@@ -80,7 +82,7 @@ PHP coding standard is available for dev/test environment using next local shell
80
82
make ecs
81
83
```
82
84
83
-
If you want to fix all possible issues in auto mode(some issues can be fixed only manually) just use next local shell command:
85
+
If you want to fix all possible issues in auto mode(some issues can be fixed only manually), just use next local shell command:
84
86
```bash
85
87
make ecs-fix
86
88
```
@@ -93,8 +95,7 @@ PHP Code Sniffer is available for dev/test environment using next local shell co
93
95
make phpcs
94
96
```
95
97
96
-
If you are using [PhpStorm](https://www.jetbrains.com/phpstorm/) you can configure PHP Code Sniffer using recommendation
If you are using [PhpStorm](https://www.jetbrains.com/phpstorm/) you can configure PHP Code Sniffer using recommendation [here](https://www.jetbrains.com/help/phpstorm/using-php-code-sniffer.html).
98
99
99
100
### PHPStan static analysis tool
100
101
PHPStan focuses on finding errors in your code without actually running it. It catches whole classes of bugs even before you write tests for the code.
@@ -135,18 +136,18 @@ make phpcpd-html-report
135
136
```
136
137
137
138
### Composer tools
138
-
To normalize or validate your composer.json you can use next local shell commands:
139
+
To normalize or validate your composer.json, you can use next local shell commands:
139
140
```bash
140
141
make composer-normalize
141
142
make composer-validate
142
143
```
143
144
144
-
If you need to find unused packages by scanning your code you can use next local shell commands:
145
+
If you need to find unused packages by scanning your code, you can use next local shell commands:
145
146
```bash
146
147
make composer-unused
147
148
```
148
149
149
-
In order to check the defined dependencies against your code you can use next local shell commands:
150
+
In order to check the defined dependencies against your code, you can use next local shell commands:
150
151
```bash
151
152
make composer-require-checker
152
153
```
@@ -157,7 +158,7 @@ Use next local shell command in order to run it:
157
158
```bash
158
159
make phpmetrics
159
160
```
160
-
Note: You need run tests before this local shell command.
161
+
Note: You need to run tests before this local shell command.
161
162
162
163
After execution above local shell command please open `reports/phpmetrics/index.html` with your browser.
163
164
@@ -203,7 +204,7 @@ Please use next workflow for migrations:
203
204
204
205
Above commands you can run in symfony container shell using next: `./bin/console doctrine:migrations:<command>`.
205
206
206
-
Using above workflow allow you make database changes on your application.
207
+
Using above workflow allows you make database changes on your application.
207
208
Also you do not need to make any migrations files by hand (Doctrine will handle it).
208
209
Please always check generated migration files to make sure that those doesn't contain anything that you really don't want.
0 commit comments