11![ CrowdSec Logo] ( images/logo_crowdsec.png )
2+
23# CrowdSec LAPI PHP client
34
45## Developer guide
56
6-
77<!-- START doctoc generated TOC please keep comment here to allow auto update -->
88<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
99** Table of Contents**
1010
1111- [ Local development] ( #local-development )
12- - [ DDEV setup] ( #ddev-setup )
13- - [ DDEV installation] ( #ddev-installation )
14- - [ Prepare DDEV PHP environment] ( #prepare-ddev-php-environment )
15- - [ DDEV Usage] ( #ddev-usage )
16- - [ Use composer to update or install the lib] ( #use-composer-to-update-or-install-the-lib )
17- - [ Unit test] ( #unit-test )
18- - [ Integration test] ( #integration-test )
19- - [ Coding standards] ( #coding-standards )
20- - [ Testing timeout in the CrowdSec container] ( #testing-timeout-in-the-crowdsec-container )
12+ - [ DDEV setup] ( #ddev-setup )
13+ - [ DDEV installation] ( #ddev-installation )
14+ - [ Prepare DDEV PHP environment] ( #prepare-ddev-php-environment )
15+ - [ DDEV Usage] ( #ddev-usage )
16+ - [ Use composer to update or install the lib] ( #use-composer-to-update-or-install-the-lib )
17+ - [ Unit test] ( #unit-test )
18+ - [ Integration test] ( #integration-test )
19+ - [ Coding standards] ( #coding-standards )
20+ - [ Testing timeout in the CrowdSec container] ( #testing-timeout-in-the-crowdsec-container )
2121- [ Commit message] ( #commit-message )
22- - [ Allowed message ` type ` values] ( #allowed-message-type-values )
22+ - [ Allowed message ` type ` values] ( #allowed-message-type-values )
2323- [ Update documentation table of contents] ( #update-documentation-table-of-contents )
2424- [ Release process] ( #release-process )
2525
2626<!-- END doctoc generated TOC please keep comment here to allow auto update -->
2727
28-
29-
3028## Local development
3129
3230There are many ways to install this library on a local PHP environment.
@@ -35,16 +33,15 @@ We are using [DDEV](https://docs.ddev.com/en/stable/) because it is quite simple
3533
3634Of course, you may use your own local stack, but we provide here some useful tools that depends on DDEV.
3735
38-
3936### DDEV setup
4037
4138For a quick start, follow the below steps.
4239
43-
4440#### DDEV installation
4541
4642This project is fully compatible with DDEV 1.21.4, and it is recommended to use this specific version.
47- For the DDEV installation, please follow the [ official instructions] ( https://docs.ddev.com/en/stable/users/install/ddev-installation/ ) .
43+ For the DDEV installation, please follow
44+ the [ official instructions] ( https://docs.ddev.com/en/stable/users/install/ddev-installation/ ) .
4845
4946#### Prepare DDEV PHP environment
5047
@@ -68,6 +65,7 @@ crowdsec-lapi-dev-project (choose the name you want for this folder)
6865```
6966
7067- Create an empty folder that will contain all necessary sources:
68+
7169``` bash
7270mkdir crowdsec-lapi-dev-project
7371```
@@ -93,10 +91,8 @@ mkdir -p my-code/lapi-client
9391cd my-code/lapi-client
&& git clone
[email protected] :crowdsecurity/php-lapi-client.git ./
9492```
9593
96-
9794### DDEV Usage
9895
99-
10096#### Use composer to update or install the lib
10197
10298Run:
@@ -119,6 +115,12 @@ First, create a bouncer and keep the result key.
119115ddev create-bouncer
120116```
121117
118+ Create also a watcher with default login/password for integration tests:
119+
120+ ``` bash
121+ ddev create-watcher
122+ ```
123+
122124Then, as we use a TLS ready CrowdSec container, you have to copy some certificates and key:
123125
124126``` bash
@@ -159,7 +161,6 @@ We are using the [PHP Coding Standards Fixer](https://cs.symfony.com/)
159161
160162With ddev, you can do the following:
161163
162-
163164``` bash
164165ddev phpcsfixer my-code/lapi-client/tools/coding-standards/php-cs-fixer ../
165166```
@@ -168,13 +169,11 @@ ddev phpcsfixer my-code/lapi-client/tools/coding-standards/php-cs-fixer ../
168169
169170To use the [ PHPSTAN] ( https://github.com/phpstan/phpstan ) tool, you can run:
170171
171-
172172``` bash
173173ddev phpstan /var/www/html/my-code/lapi-client/tools/coding-standards phpstan/phpstan.neon /var/www/html/my-code/lapi-client/src
174174
175175```
176176
177-
178177##### PHP Mess Detector
179178
180179To use the [ PHPMD] ( https://github.com/phpmd/phpmd ) tool, you can run:
198197ddev phpcbf ./my-code/lapi-client/tools/coding-standards my-code/lapi-client/src PSR12
199198```
200199
201-
202200##### PSALM
203201
204202To use [ PSALM] ( https://github.com/vimeo/psalm ) tools, you can run:
@@ -211,20 +209,20 @@ ddev psalm ./my-code/lapi-client/tools/coding-standards ./my-code/lapi-client/to
211209
212210In order to generate a code coverage report, you have to:
213211
214-
215212- Enable ` xdebug ` :
213+
216214``` bash
217215ddev xdebug
218216```
219217
220218To generate a html report, you can run:
219+
221220``` bash
222221ddev php -dxdebug.mode=coverage ./my-code/lapi-client/tools/coding-standards/vendor/bin/phpunit --configuration ./my-code/lapi-client/tools/coding-standards/phpunit/phpunit.xml
223222```
224223
225224You should find the main report file ` dashboard.html ` in ` tools/coding-standards/phpunit/code-coverage ` folder.
226225
227-
228226If you want to generate a text report in the same folder:
229227
230228``` bash
@@ -236,15 +234,19 @@ ddev php -dxdebug.mode=coverage ./my-code/lapi-client/tools/coding-standards/ven
236234If you need to test a timeout, you can use the following command:
237235
238236Install ` iproute2 `
237+
239238``` bash
240239ddev exec -s crowdsec apk add iproute2
241240```
241+
242242Add the delay you want:
243+
243244``` bash
244245ddev exec -s crowdsec tc qdisc add dev eth0 root netem delay 500ms
245246```
246247
247248To remove the delay:
249+
248250``` bash
249251ddev exec -s crowdsec tc qdisc del dev eth0 root netem
250252```
@@ -256,8 +258,6 @@ ddev exec BOUNCER_KEY=<BOUNCER_KEY> AGENT_TLS_PATH=/var/www/html/cfssl APPSEC_UR
256258LAPI_URL=https://crowdsec:8080 php ./my-code/lapi-client/vendor/bin/phpunit ./my-code/lapi-client/tests/Integration --testdox --group timeout
257259```
258260
259-
260-
261261## Commit message
262262
263263In order to have an explicit commit history, we are using some commits message convention with the following format:
@@ -273,8 +273,7 @@ Example:
273273
274274 feat(bouncer): Add a new endpoint for bouncer
275275
276-
277- You can use the ` commit-msg ` git hook that you will find in the ` .githooks ` folder :
276+ You can use the ` commit-msg ` git hook that you will find in the ` .githooks ` folder :
278277
279278```
280279cp .githooks/commit-msg .git/hooks/commit-msg
@@ -293,10 +292,10 @@ chmod +x .git/hooks/commit-msg
293292- style (formatting; no production code change)
294293- test (adding missing tests, refactoring tests; no production code change)
295294
296-
297295## Update documentation table of contents
298296
299- To update the table of contents in the documentation, you can use [ the ` doctoc ` tool] ( https://github.com/thlorenz/doctoc ) .
297+ To update the table of contents in the documentation, you can use [ the
298+ ` doctoc ` tool] ( https://github.com/thlorenz/doctoc ) .
300299
301300First, install it:
302301
@@ -310,20 +309,19 @@ Then, run it in the documentation folder:
310309doctoc docs/* --maxlevel 4
311310```
312311
313-
314312## Release process
315313
316- We are using [ semantic versioning] ( https://semver.org/ ) to determine a version number.
314+ We are using [ semantic versioning] ( https://semver.org/ ) to determine a version number.
317315
318316Before publishing a new release, there are some manual steps to take:
319317
320318- Change the version number in the ` Constants.php ` file
321319- Update the ` CHANGELOG.md ` file
322320
323- Then, you have to [ run the action manually from the GitHub repository ] ( https://github.com/crowdsecurity/php-lapi-client/actions/workflows/release.yml )
324-
321+ Then, you have
322+ to [ run the action manually from the GitHub repository ] ( https://github.com/crowdsecurity/php-lapi-client/actions/workflows/release.yml )
325323
326- Alternatively, you could use the [ GitHub CLI] ( https://github.com/cli/cli ) to publish a release:
324+ Alternatively, you could use the [ GitHub CLI] ( https://github.com/cli/cli ) to publish a release:
327325
328326```
329327gh workflow run release.yml -f tag_name=vx.y.z
0 commit comments