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.
Copy file name to clipboardExpand all lines: docs/phpstorm.md
+12-14Lines changed: 12 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,22 +4,20 @@ This document describing how you can configure your IDE [PhpStorm](https://www.j
4
4
## Configuring PhpStorm
5
5
### General
6
6
* Go to `Settings -> Plugins` and install next plugins:
7
-
- .env files support
8
7
- .ignore
9
-
- Elasticsearch (Paid)
10
-
- Makefile Language
11
8
- Php Annotations
12
9
- Php Inspections (EA Extended)
13
10
- Php Toolbox
14
-
- Symfony support (Has some paid functions, [homepage](https://espend.de/phpstorm/plugin/symfony))
15
-
- Rainbow brackets
11
+
- JetBrains AI Assistant
12
+
- Symfony Plugin (Has some paid functions, [homepage](https://espend.de/phpstorm/plugin/symfony))
13
+
- Rainbow Brackets
16
14
- String Manipulation
17
-
-Extra ToolWindow Colorful Icons
15
+
-Elasticsearch (Paid)
18
16
* Go to `Settings -> Php -> Symfony` and check `Enable plugin for this project` and set Web Directory value as `public`.
19
-
* If you want control quality of your PHP project - pay your attention to the tools, described [here](development.md).
17
+
* If you want to control quality of your PHP project - pay your attention to the tools, described [here](development.md).
20
18
21
19
### CLI Interpreter
22
-
You need to set correct CLI interpreter for your PhpStorm.
20
+
You need to set a correct CLI interpreter for your PhpStorm.
23
21
In order to do it please open `Settings -> PHP` section and follow recommendations [configuring remote PHP interpreters](https://www.jetbrains.com/help/phpstorm/configuring-remote-interpreters.html).
24
22
25
23
@@ -37,7 +35,7 @@ You need to configure how your local files will be mapped inside docker containe
37
35
38
36
39
37
### Test Frameworks
40
-
If you want to run tests directly from your IDE you need to do following configuration in `Settings -> PHP -> Test Frameworks`:
38
+
If you want to run tests directly from your IDE you need to do a following configuration in `Settings -> PHP -> Test Frameworks`:
41
39
42
40
43
41
@@ -63,30 +61,30 @@ Anyway you can always import our recommended code style if you don't have commit
Note: make sure that you have proper local path for the MessDetector ruleset `phpmd_ruleset.xml`.
71
+
Note: make sure that you have a proper local path for the MessDetector ruleset `phpmd_ruleset.xml`.
74
72
75
73
76
74
77
75
* If you don't have committed folder `.idea/`, go to `Settings -> Editor -> Inspections` and import profile `Project Default` (Inspections.xml) from [docs/phpstorm](phpstorm):
78
76
79
77
80
78
81
-
* Go to `Settings -> Tools -> External tools` and create ecs tool:
79
+
* Go to `Settings -> Tools -> External Tools` and create ecs tool:
82
80
83
81
84
82
85
83
Note: Arguments value should be `exec-bash cmd="./vendor/bin/ecs --clear-cache check $FilePathRelativeToProjectRoot$"`.
86
84
87
85
Note: In order to use it - right click on the necessary file/folder in PhpStorm and select context menu `External Tools -> ecs`.
88
86
89
-
* Go to `Settings -> Tools -> External tools` and create phpcs tool:
87
+
* Go to `Settings -> Tools -> External Tools` and create phpcs tool:
90
88
91
89
92
90
@@ -95,7 +93,7 @@ Note: Arguments value should be `exec-bash cmd="./vendor/bin/phpcs --version &&
95
93
Note: In order to use it - right click on the necessary file/folder in PhpStorm and select context menu `External Tools -> phpcs`.
96
94
97
95
98
-
For inspecting your code you can use main menu item `Code -> Inspect Code`. Code will be processed by code quality tools like PHP CS Fixer, PHP Mess Detector, PHP CodeSniffer, PHPStan.
96
+
For inspecting your code you can use main menu item `Code -> Inspect Code`. Code will be processed by code quality tools like PHP CS Fixer, PHP CodeSniffer, PHPStan, PHP Mess Detector.
This document describing how you can run tests within this environment.
2
+
This document describing how you can run tests.
3
3
4
4
### General
5
-
This environment contains next [types](https://symfony.com/doc/current/testing.html#types-of-tests) of tests:
5
+
This environment contains the next [types](https://symfony.com/doc/current/testing.html#types-of-tests) of tests:
6
6
7
7
* Application tests
8
8
* Integration tests
@@ -15,14 +15,14 @@ Note 1: Please note that this environment does not use simple phpunit as does Sy
15
15
Note 2: `Application` test === `Functional` test, please use naming convention(`Application`) as described [here](https://symfony.com/doc/current/testing.html#application-tests).
16
16
17
17
### Commands to run tests
18
-
You can run tests using following local shell command(s):
18
+
You can run tests using the following local shell command(s):
19
19
```bash
20
20
make phpunit # Run all tests
21
21
```
22
22
23
-
After execution above local shell command you are able to check code coverage report. Please open `reports/coverage/index.html` with your browser.
23
+
After execution above local shell command, you are able to check a code coverage report. Please open `reports/coverage/index.html` with your browser.
24
24
25
-
If you want to run single test or all tests in specified directory you can use next steps:
25
+
If you want to run a single test or all tests in specified directory, you can use the next steps:
26
26
27
27
1.Use next local shell command in order to enter into symfony container shell:
28
28
```bash
@@ -31,23 +31,12 @@ make ssh # Enter symfony container shell
31
31
2.Use next symfony container shell command(s) in order to run test(s):
32
32
```bash
33
33
./vendor/bin/phpunit ./tests/Application/Controller/ApiKeyControllerTest.php # Just this single test class
34
-
./vendor/bin/phpunit ./tests/Application/Controller/ # All tests in this directory
34
+
./vendor/bin/phpunit ./tests/Application/Controller/ # All tests in the directory
35
35
```
36
36
37
37
### Separate environment for testing
38
-
By default this environment is using separate database for testing.
38
+
By default, this environment is using a separate database for testing.
39
39
If you need to change separate environment for testing (f.e. change database or another stuff) you need to edit `.env.test` file.
40
40
41
-
42
-
## Metrics
43
-
This environment contains [PhpMetrics](https://github.com/phpmetrics/phpmetrics) to make some code analysis.
44
-
Use next local shell command in order to run it:
45
-
```bash
46
-
make phpmetrics
47
-
```
48
-
Note: You need run tests before this local shell command.
49
-
50
-
After execution above local shell command please open `reports/phpmetrics/index.html` with your browser.
51
-
52
41
## PhpStorm
53
42
You can run tests directly from your IDE PhpStorm. Please follow [PhpStorm](phpstorm.md) documentation in order to do it.
Copy file name to clipboardExpand all lines: docs/xdebug.md
+24-25Lines changed: 24 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,69 +1,68 @@
1
1
# Xdebug
2
-
This document describing how you can use [Xdebug](https://xdebug.org/) and [PhpStorm](https://www.jetbrains.com/phpstorm/)within DEV environment.
2
+
This document describing how you can use [Xdebug](https://xdebug.org/) and [PhpStorm](https://www.jetbrains.com/phpstorm/)for the DEV environment.
3
3
4
4
## Configuration and usage
5
-
Please follow [PhpStorm](phpstorm.md) documentation before actions described bellow.
5
+
Please follow [PhpStorm](phpstorm.md) documentation before actions described below.
6
6
7
7
### PhpStorm basic configuration
8
8
1.Check /docker/dev/xdebug-main.ini or /docker/dev/xdebug-osx.ini (optional)
9
9
10
-
-In case you need debug only requests with IDE KEY: PHPSTORM from frontend in your browser:
10
+
-Set option in case you need to debug every request to an api (by default):
11
11
```bash
12
-
xdebug.start_with_request = no
12
+
xdebug.start_with_request = yes
13
13
```
14
-
Install locally in Firefox extension "Xdebug helper" and set in settings IDE KEY: PHPSTORM
15
14
16
-
-In case you need debug any request to an api (by default):
15
+
-Set option in case you need to debug only requests with IDE KEY: PHPSTORM from frontend in your browser:
17
16
```bash
18
-
xdebug.start_with_request = yes
17
+
xdebug.start_with_request = no
19
18
```
20
19
21
20
2.Go to `Settings -> Php -> Debug` and set Xdebug port `10000`
22
21
23
-
3.Check your `Run/Debug Configurations` as on image bellow
24
-
25
-
4.Install needed browser extensions (optional, see step 1). For example for Firefox install extension "Xdebug helper" and set in extension settings IDE KEY: PHPSTORM
22
+
3.Check your `Run/Debug Configurations` as on image below:
26
23
27
24
28
25
29
26
30
27
28
+
4.Install browser extensions (optional, see step 1). For example, for Firefox, install extension "Xdebug helper" and set in extension settings IDE KEY: PHPSTORM
29
+
31
30
### Using Xdebug
32
-
After actions above you can start to listen incoming PHP debug connections:
31
+
After actions above, you can start listening for incoming PHP debug connections:
33
32
34
33
1. Add breakpoint to your code
35
34
2. Enable Xdebug in your browser (optional, required only when xdebug.start_with_request = no)
36
35
3. Click `Debug` button in PhpStorm
37
-
4. Reload browser page
36
+
4. Reload page in the browser
38
37
39
-
If everything configured properly you will get something like next:
38
+
If everything configured properly, you will get something like next:
40
39
41
40
42
41
43
42
## Debug Postman requests
44
-
If you're using [Postman](https://www.getpostman.com/) to test/debug your application when `xdebug.start_with_request = no` you need to add `?XDEBUG_SESSION_START=PHPSTORM` to each URL
45
-
that you use with Postman. If you have default configuration (`xdebug.start_with_request = yes`) - nothing to do and your Xdebug should work out of the box.
43
+
If you're using [Postman](https://www.getpostman.com/) to test/debug your application, when `xdebug.start_with_request = no`, you need to add `?XDEBUG_SESSION_START=PHPSTORM` to each URL that you use with Postman.
44
+
If you have default configuration (`xdebug.start_with_request = yes`) - nothing to do and your Xdebug should work out of the box.
If you want to debug console commands or messenger async handlers you just need to uncomment/edit (nothing to do in case MacOS and `XDEBUG_CONFIG=osx`) option `xdebug.client_host`in config `docker/dev/xdebug-main.ini`:
47
+
If you want to debug console commands or messenger async handlers, you need to uncomment/edit (nothing to do in case MacOS and `XDEBUG_CONFIG=osx`) option `xdebug.client_host`inside config `docker/dev/xdebug-main.ini`:
49
48
```bash
50
49
xdebug.client_host=172.17.0.1
51
50
```
52
51
Just find out the proper host ip in your docker bridge configuration and set above option (in general it is `172.17.0.1`).
53
52
Don't forget to rebuild docker containers according to [general](../readme.md) documentation.
54
53
55
-
If you want to debug your messenger async jobs just follow next steps:
54
+
If you want to debug your messenger async jobs, please follow the next steps:
56
55
57
-
1. Enter in`supervisord` docker container shell using your local shell command `make ssh-supervisord`
58
-
2.In`supervisord` container shell run next command `supervisorctl`
59
-
3. Stop program `messenger-consume:messenger-consume_00` using next command `stop messenger-consume:messenger-consume_00` and make sure that you can see message `messenger-consume:messenger-consume_00: stopped`
60
-
4. Exit from supervisorctl shell using next command `exit`
61
-
5. Exit from `supervisord` docker container using command `exit`. Make sure that you are in local shell.
62
-
6. Enter in`symfony` docker container shell using your local shell command `make ssh`
56
+
1. Enter inside`supervisord` docker container shell using your local shell command `make ssh-supervisord`
57
+
2.Inside`supervisord` container shell run the next command `supervisorctl`
58
+
3. Stop program `messenger-consume:messenger-consume_00` using the next command `stop messenger-consume:messenger-consume_00` and make sure that you can see message `messenger-consume:messenger-consume_00: stopped`
59
+
4. Exit from supervisorctl shell using the next command `exit`
60
+
5. Exit from `supervisord` docker container using command `exit`. Make sure that you are in the local shell.
61
+
6. Enter inside`symfony` docker container shell using your local shell command `make ssh`
63
62
7. Put necessary message in queue or make sure that it is already there
64
63
8. Run PHPStorm debug
65
-
9. Run in`symfony` docker container shell next command in order to run your async handlers `/usr/local/bin/php bin/console messenger:consume async_priority_high async_priority_low --limit=1` (where limit option is a number of messages that you want to debug)
66
-
10. Have fun with debugging and don't forget to switch on program `messenger-consume:messenger-consume_00` (step 1, 2 and execute `start messenger-consume:messenger-consume_00`) in`supervisord` docker container when you'll finish your debugging (or you can simply restart environment using your local shell command `make restart`).
64
+
9. Run inside`symfony` docker container shell the next command to run your async handlers `/usr/local/bin/php bin/console messenger:consume async_priority_high async_priority_low --limit=1` (where limit option is a number of messages that you want to debug)
65
+
10. Have fun with debugging and don't forget to turn on the program `messenger-consume:messenger-consume_00` (step 1, 2 and execute `start messenger-consume:messenger-consume_00`) inside`supervisord` docker container when you'll finish your debugging (or you can simply restart environment using your local shell command `make restart`).
67
66
68
67
## External documentations
69
68
*[Debugging PHP (web and cli) with Xdebug using Docker and PHPStorm](https://thecodingmachine.io/configuring-xdebug-phpstorm-docker)
0 commit comments