feat(geolcation): Update docs and modify admin test part

Author: julienloizelet

docs/USER_GUIDE.md

@@ -65,7 +65,8 @@ These configurations are divided in three main parts : `CrowdSec`, `Theme custom
 
 #### General settings
 
-In the `CrowdSec` part, you will set your connection details and refine bouncing according to your needs.
+In the `CrowdSec` part, you will set your connection details and refine bouncing according to your needs. You will 
+also be able to test your settings.
 
 ![Connection details](images/screenshots/config-connection.jpg)
 
@@ -98,7 +99,9 @@ If enabled, the admin is not bounced.
 
 ***
 
-`Test your settings`
+![Setting tests](images/screenshots/config-test-your-settings.jpg)
+
+`Test your settings → Test bouncing`
 
 Click the "Test bouncing" button and the configured bouncer will try to get the remediation (bypass, captcha or ban) 
 for 
@@ -109,6 +112,13 @@ This test allows you to know if your connection, bouncing and cache settings are
 
 ***
 
+`Test your settings → Test geolocation`
+
+Click the "Test geolocation" button to try getting country for the IP entered in the text field.
+
+This test allows you to know if your geolocation settings are correct.
+
+
 
 #### Theme customization
 
@@ -124,7 +134,7 @@ In the `Theme customization` part, you can modify texts and colors of ban and ca
 #### Advanced settings
 
 In the `Advanced` part, you can enable/disable the stream mode, choose your cache system for your CrowdSec
-LAPI, handle your remediation policy and adjust some debug and log parameters.
+LAPI, handle your remediation policy, manage geolocation feature, adjust some debug parameters and testing parameters. 
 
 ![Communication mode](images/screenshots/config-communication-mode.jpg)
 
@@ -192,6 +202,14 @@ we store in cache some values in order to know if he has to resolve or not the c
 
 Minimum 1 second. Default: 86400 seconds.
 
+***
+
+`Caching configuration → Geolocation cache lifetime`
+
+The lifetime of cached country geolocation result for some IP.
+
+Minimum 1 second. Default: 86400 seconds.
+
 
 ***
 
@@ -215,6 +233,50 @@ If you use a CDN, a reverse proxy or a load balancer, it is possible to indicate
 
 Enable if you want to hide CrowdSec mentions on the Ban and Captcha walls.
 
+
+***
+
+![Geolocation](images/screenshots/config-geolocation.jpg)
+
+***
+
+`Geolocation → Enable geolocation feature`
+
+Enable if you want to use also CrowdSec country scoped decisions.
+If enabled, bounced IP will be geolocalized and the final remediation will take into account any country related decision.
+
+***
+
+`Geolocation → Geolocation type`
+
+
+For now, only `Maxmind database` type is allowed
+
+***
+
+`Geolocation → MaxMind database type`
+
+Choose between `Country` and `City`.
+
+
+***
+
+`Geolocation → Path to the MaxMind database`
+
+Relative path from `wp-content/plugins/cs-wordpress-bouncer/geolocation` folder.
+
+***
+
+`Geolocation → Save geolocalized country in cache`
+
+Enabling this will avoid multiple call to the geolocation system (e.g. MaxMind database)
+If enabled, the geolocalized country associated to the IP will be saved in cache.
+See the `Geolocation cache lifetime` setting above to set the lifetime of this result.
+
+***
+
+
+
 ![Debug](images/screenshots/config-debug.jpg)
 
 ***
@@ -235,6 +297,27 @@ When this mode is enabled, you will see every unexpected bouncing errors in the
 Should be disabled in production.
 
 
+***
+
+![Test](images/screenshots/config-test.jpg)
+
+***
+
+
+`Test settings → Forced test IP`
+
+This Ip will be used instead of the current detected browser IP.
+**Must be empty in production.**
+
+***
+
+`Test settings → Forced test X-Forwarded-For IP`
+
+This Ip will be used instead of the current X-Forwarded-For Ip if any.
+**Must be empty in production.**
+
+
+
 ### Auto Prepend File mode
 
 By default, this extension will bounce every web requests that pass through the classical process of WordPress core loading.

docs/images/screenshots/config-cache.jpg

@@ -197,15 +197,17 @@ function adminAdvancedSettings()
     }, ' seconds. <p>The lifetime of cached captcha flow for some IP. <br>If a user has to interact with a captcha wall, we store in cache some values in order to know if he has to resolve or not the captcha again.<br>Minimum 1 second. Default: '.Constants::CACHE_EXPIRATION_FOR_CAPTCHA.'.', Constants::CACHE_EXPIRATION_FOR_CAPTCHA, 'width: 115px;', 'number');
 
     // Field "crowdsec_geolocation_cache_duration"
-    addFieldString('crowdsec_geolocation_cache_duration', 'Geolocation cache duration', 'crowdsec_plugin_advanced_settings', 'crowdsec_advanced_settings', 'crowdsec_admin_advanced_cache', function ($input) {
+    addFieldString('crowdsec_geolocation_cache_duration', 'Geolocation cache lifetime', 'crowdsec_plugin_advanced_settings',
+        'crowdsec_advanced_settings', 'crowdsec_admin_advanced_cache', function ($input) {
         if ( (int) $input <= 0) {
             add_settings_error('Geolocation cache duration', 'crowdsec_error', 'Geolocation cache duration: Minimum is 1 second.');
 
             return Constants::CACHE_EXPIRATION_FOR_GEO;
         }
 
         return (int) $input > 0 ? (int) $input : Constants::CACHE_EXPIRATION_FOR_CAPTCHA ;
-    }, ' seconds. <p>The lifetime of cached country geolocation result for some IP.<br>Minimum 1 second. Default: '.Constants::CACHE_EXPIRATION_FOR_GEO.'.', Constants::CACHE_EXPIRATION_FOR_GEO, 'width: 115px;', 'number');
+    }, ' seconds. <p>The lifetime of cached country geolocation result for some IP.<br>Minimum 1 second. Default: '
+       .Constants::CACHE_EXPIRATION_FOR_GEO.'.<br>See the <i>Geolocation</i> settings below to enable geolocalized country result save.', Constants::CACHE_EXPIRATION_FOR_GEO, 'width: 115px;', 'number');
 
 
     /***************************
@@ -327,7 +329,7 @@ function convertInlineIpRangesToComparableIpBounds(string $inlineIpRanges): arra
 
     addFieldCheckbox('crowdsec_geolocation_save_result', 'Save geolocalized country in cache', 'crowdsec_plugin_advanced_settings',
         'crowdsec_advanced_settings', 'crowdsec_admin_advanced_geolocation', function () {}, function () {}, '
-    <p>Enabling this will avoid multiple call to the geolocation system (e.g. MaxMind database)</p> If enabled, the geolocalized country associated to the IP will be saved in cache.<br>See the <i>Geolocation cache duration</i> setting above to set the lifetime of this result.');
+    <p>Enabling this will avoid multiple call to the geolocation system (e.g. MaxMind database)</p> If enabled, the geolocalized country associated to the IP will be saved in cache.<br>See the <i>Geolocation cache lifetime</i> setting above to set the lifetime of this result.');
 
 
     /*******************************
@@ -368,7 +370,7 @@ function convertInlineIpRangesToComparableIpBounds(string $inlineIpRanges): arra
     }, '<p>This Ip will be used instead of the current detected browser IP: '.$_SERVER['REMOTE_ADDR'].'.<br><strong>Must be empty in production.</strong></p>',
     '1.2.3.4', '');
 
-    addFieldString('crowdsec_forced_test_forwarded_ip', 'Forced test X-Forwrded-For IP', 'crowdsec_plugin_advanced_settings', 'crowdsec_advanced_settings', 'crowdsec_admin_advanced_test', function ($input) {
+    addFieldString('crowdsec_forced_test_forwarded_ip', 'Forced test X-Forwarded-For IP', 'crowdsec_plugin_advanced_settings', 'crowdsec_advanced_settings', 'crowdsec_admin_advanced_test', function ($input) {
         return $input;
     }, '<p>This Ip will be used instead of the current X-Forwarded-For Ip if any.<br><strong>Must be empty in production.</strong></p>',
         '1.2.3.4', '');

docs/images/screenshots/config-connection.jpg

@@ -128,6 +128,9 @@ function testBouncerConnexionInAdminPage($ip)
     function testGeolocationInAdminPage($ip)
     {
         try {
+            if (!get_option('crowdsec_geolocation_maxmind_database_path')) {
+                throw new BouncerException("Maxmind database path can not be empty");
+            }
             $settings = getDatabaseSettings();
             $bouncer = getBouncerInstance($settings);
             $geolocationConfig =  $settings['geolocation'];