Merge pull request #94 from julienloizelet/feat/coding-standards-rework

Feat/coding standards rework

Author: julienloizelet

.github/workflows/test-suite.yml

@@ -28,7 +28,7 @@ jobs:
 
       - name: Install DDEV
         env:
-          DDEV_VERSION: v1.19.1
+          DDEV_VERSION: v1.19.3
         run: |
           # @see https://ddev.readthedocs.io/en/stable/#installationupgrade-script-linux-and-macos-armarm64-and-amd64-architectures
           sudo apt-get -qq update
@@ -90,11 +90,11 @@ jobs:
 
       - name: Run PHP UNIT tests (IP verification)
         run: |
-          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/IpVerificationTest.php
+          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/IpVerificationTest.php
 
       - name: Run PHP UNIT tests (Geolocation)
         run: |
-          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} LAPI_URL=http://crowdsec:8080  /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/GeolocationTest.php
+          ddev exec BOUNCER_KEY=${{ env.BOUNCER_KEY }} LAPI_URL=http://crowdsec:8080  /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/GeolocationTest.php
 
       - name: Prepare Standalone Bouncer end-to-end tests
         run: |

.gitignore

@@ -1,6 +1,6 @@
 # Composer
 vendor
-/composer.lock
+composer.lock
 
 # Systems
 .DS_Store
@@ -12,7 +12,7 @@ super-linter.log
 tools/php-cs-fixer/composer.lock
 
 # App
-/var/
+var/
 .bouncer-key
 .cache
 

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "crowdsec/bouncer",
-    "description": "The official PHP bouncer library for the CrowdSec LAPI/CAPI",
+    "description": "The official PHP bouncer library for the CrowdSec LAPI",
     "type": "library",
     "license": "MIT",
     "minimum-stability": "stable",
@@ -22,6 +22,11 @@
             "CrowdSecBouncer\\": "src/"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "CrowdSecBouncer\\Tests\\": "tests/"
+        }
+    },
     "authors": [
         {
             "name": "Lucas Cherifi",
@@ -43,8 +48,6 @@
         "geoip2/geoip2": "^2.12.2"
     },
     "require-dev": {
-        "phpunit/phpunit": "8.5.21",
-        "phpmd/phpmd": "@stable",
-        "squizlabs/php_codesniffer": "^3.6.2"
+        "phpunit/phpunit": "8.5.27"
     }
 }

docs/DEVELOPER.md

@@ -69,14 +69,14 @@ For a quick start, follow the below steps.
 
 #### DDEV installation
 
-This project is fully compatible with DDEV 1.19.1, and it is recommended to use this specific version.
+This project is fully compatible with DDEV 1.19.3, and it is recommended to use this specific version.
 For the DDEV installation, please follow the [official instructions](https://ddev.readthedocs.io/en/stable/#installation).
 On a Linux distribution, you can run:
 ```
 sudo apt-get -qq update
 sudo apt-get -qq -y install libnss3-tools
 curl -LO https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh
-bash install_ddev.sh v1.19.1
+bash install_ddev.sh v1.19.3
 rm install_ddev.sh
 ```
 
@@ -86,18 +86,18 @@ rm install_ddev.sh
 The final structure of the project will look like below.
 
 ```
-php-project-sources
+php-project-sources (choose the name you want for this folder)
 │   
 │ (your php project sources; could be a simple index.php file)    
 │
-└───.ddev
+└───.ddev (do not change this folder name)
 │   │   
 │   │ (Cloned sources of a PHP specific ddev repo)
 │   
-└───my-own-modules
-    │   
+└───my-own-modules (do not change this folder name)
     │
-    └───crowdsec-php-lib
+    │
+    └───crowdsec-php-lib (do not change this folder name)
        │   
        │ (Clone of this repo)
          
@@ -212,7 +212,7 @@ Finally, run
 
 
 ```bash
-ddev exec BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/IpVerificationTest.php
+ddev exec BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080 MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/IpVerificationTest.php
 ```
 
 For geolocation Unit Test, you should first put 2 free MaxMind databases in the `tests` folder : `GeoLite2-City.mmdb`
@@ -222,7 +222,7 @@ and`GeoLite2-Country.mmdb`. You can download these databases by creating a maxmi
 Then, you can run:
 
 ```bash
-ddev exec BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080  /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/GeolocationTest.php
+ddev exec BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080  /usr/bin/php ./my-own-modules/crowdsec-php-lib/vendor/bin/phpunit --testdox --colors --exclude-group ignore ./my-own-modules/crowdsec-php-lib/tests/Integration/GeolocationTest.php
 
 ```
 
@@ -295,30 +295,42 @@ yarn global add cross-env
 
 #### Coding standards
 
+We set up some coding standards tools that you will find in the `tools/coding-standards` folder.
+In order to use these, you will need to work with a PHP version >= 7.4 and run first:
+
+```
+ddev composer update --working-dir=./my-own-modules/crowdsec-php-lib/tools/coding-standards
+```
+
 ##### PHPCS Fixer
 
 We are using the [PHP Coding Standards Fixer](https://cs.symfony.com/)
 
 With ddev, you can do the following:
 
+
 ```bash
-ddev composer update --working-dir=./my-own-modules/crowdsec-php-lib/tools/php-cs-fixer
+ddev phpcsfixer my-own-modules/crowdsec-php-lib/tools/coding-standards/php-cs-fixer ../
+
 ```
-And then:
+
+##### PHPSTAN
+
+To use the [PHPSTAN](https://github.com/phpstan/phpstan) tool, you can run:
+
 
 ```bash
-ddev phpcsfixer my-own-modules/crowdsec-php-lib tools/php-cs-fixer
+ddev phpstan /var/www/html/my-own-modules/crowdsec-php-lib/tools/coding-standards phpstan/phpstan.neon /var/www/html/my-own-modules/crowdsec-php-lib/src
 
 ```
 
-**N.B**: to use PHPCS Fixer, you will need to work with a PHP version >= 7.4.
 
 ##### PHP Mess Detector
 
 To use the [PHPMD](https://github.com/phpmd/phpmd) tool, you can run:
 
 ```bash
-ddev phpmd ./my-own-modules/crowdsec-php-lib tools/phpmd/rulesets.xml src
+ddev phpmd ./my-own-modules/crowdsec-php-lib/tools/coding-standards phpmd/rulesets.xml ../../src
 
 ```
 
@@ -327,15 +339,51 @@ ddev phpmd ./my-own-modules/crowdsec-php-lib tools/phpmd/rulesets.xml src
 To use [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) tools, you can run:
 
 ```bash
-ddev phpcs ./my-own-modules/crowdsec-php-lib/vendor/bin/phpcs my-own-modules/crowdsec-php-lib/src
+ddev phpcs ./my-own-modules/crowdsec-php-lib/tools/coding-standards my-own-modules/crowdsec-php-lib/src PSR12
 ```
 
 and:
 
 ```bash
-ddev phpcbf ./my-own-modules/crowdsec-php-lib/vendor/bin/phpcs my-own-modules/crowdsec-php-lib/src
+ddev phpcbf  ./my-own-modules/crowdsec-php-lib/tools/coding-standards my-own-modules/crowdsec-php-lib/src PSR12
+```
+
+
+##### PSALM
+
+To use [PSALM](https://github.com/vimeo/psalm) tools, you can run:
+
+```bash
+ddev psalm ./my-own-modules/crowdsec-php-lib/tools/coding-standards ./my-own-modules/crowdsec-php-lib/tools/coding-standards/psalm
 ```
 
+##### PHP Unit Code coverage
+
+In order to generate a code coverage report, you have to:
+
+- Enable `xdebug`:
+```bash
+ddev xdebug
+```
+
+To generate a html report, you can run:
+```bash
+ddev exec XDEBUG_MODE=coverage BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080
+MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php  ./my-own-modules/crowdsec-php-lib/tools/coding-standards/vendor/bin/phpunit  --configuration ./my-own-modules/crowdsec-php-lib/tools/coding-standards/phpunit/phpunit.xml
+
+```
+
+You should find the main report file `dashboard.html` in `tools/coding-standards/phpunit/code-coverage` folder.
+
+
+If you want to generate a text report in the same folder:
+
+```bash
+ddev exec XDEBUG_MODE=coverage BOUNCER_KEY=your-bouncer-key LAPI_URL=http://crowdsec:8080
+MEMCACHED_DSN=memcached://memcached:11211 REDIS_DSN=redis://redis:6379 /usr/bin/php  ./my-own-modules/crowdsec-php-lib/tools/coding-standards/vendor/bin/phpunit  --configuration ./my-own-modules/crowdsec-php-lib/tools/coding-standards/phpunit/phpunit.xml --coverage-text=./my-own-modules/crowdsec-php-lib/tools/coding-standards/phpunit/code-coverage/report.txt 
+```
+
+
 
 #### Generate CrowdSec tools and settings on start
 

docs/INSTALLATION_GUIDE.md

@@ -25,7 +25,7 @@
 ## Requirements
 
 - PHP >= 7.2
-- required php extensions : `ext-curl`, `ext-gd`
+- required php extensions : `ext-json`, `ext-gd`
 
 ## Installation
 

docs/USER_GUIDE.md

@@ -42,7 +42,7 @@ Please note that first and foremost a CrowdSec agent must be installed on a serv
 
 ## Features
 
-- CrowdSec LAPI Support (CAPI not supported yet)
+- CrowdSec LAPI Support
   - Handle IP, IP ranges and Country scoped decisions
   - Clear, prune and refresh the LAPI cache
   - `Live mode` or `Stream mode`
@@ -73,7 +73,8 @@ On the other hand, all texts are also fully customizable. This will allow you, f
 
 ### Create your own bouncer
 
-You can use this library to develop your own PHP application bouncer.
+You can use this library to develop your own PHP application bouncer. Any custom bouncer should extend the 
+[`AbstractBounce`](../src/AbstractBounce.php) class.
 
 #### Quick start
 
@@ -234,8 +235,7 @@ Here is the list of available settings:
 #### The `Standalone` example
 
 This library includes the [`StandaloneBounce`](../src/StandaloneBounce.php) class. You can see that class as a good 
-example for creating your own bouncer. This class extends [`AbstractBounce`](../src/AbstractBounce.php) and 
-implements [IBounce](../src/IBounce.php). All bouncers should do the same. In order to add the bounce logic, you 
+example for creating your own bouncer. This class extends [`AbstractBounce`](../src/AbstractBounce.php). All bouncers should do the same. In order to add the bounce logic, you 
 should first instantiate your bouncer:
 
 ```php