Merge pull request #41 from crowdsecurity/improve-php-doc

improve php doc

Author: mobula9

docs/api/ApiCache.md

@@ -75,7 +75,7 @@ The cache mecanism to store every decisions from LAPI/CAPI. Symfony Cache compon
 **Description**
 
 ```php
-public configure (void)
+public configure (bool $liveMode, string $apiUrl, int $timeout, string $userAgent, string $apiKey, int $cacheExpirationForCleanIp, int $cacheExpirationForBadIp, string $fallbackRemediation)
 ```
 
 Configure this instance. 
@@ -84,7 +84,22 @@ Configure this instance.
 
 **Parameters**
 
-`This function has no parameters.`
+* `(bool) $liveMode`
+: If we use the live mode (else we use the stream mode)  
+* `(string) $apiUrl`
+: The URL of the LAPI  
+* `(int) $timeout`
+: The timeout well calling LAPI  
+* `(string) $userAgent`
+: The user agent to use when calling LAPI  
+* `(string) $apiKey`
+: The Bouncer API Key to use to connect LAPI  
+* `(int) $cacheExpirationForCleanIp`
+: The duration to cache an IP considered as clean by LAPI  
+* `(int) $cacheExpirationForBadIp`
+: The duration to cache an IP considered as bad by LAPI  
+* `(string) $fallbackRemediation`
+: The remediation to use when the remediation sent by LAPI is not supported by this library  
 
 **Return Values**
 
@@ -165,7 +180,7 @@ Used for the stream mode when we have to update the remediations list.
 
 `array`
 
-> number of deleted and new decisions
+> number of deleted and new decisions, and errors when processing decisions
 
 
 <hr />
@@ -220,9 +235,9 @@ Used when the stream mode has just been activated.
 
 **Return Values**
 
-`int`
+`array`
 
-> number of decisions added
+> "count": number of decisions added, "errors": decisions not added
 
 
 <hr />

docs/api/Bouncer.md

@@ -11,7 +11,7 @@ The main Class of this package. This is the first entry point of any PHP Bouncer
 | Name | Description |
 |------|-------------|
 |[__construct](#bouncer__construct)||
-|[buildCaptchaCouple](#bouncerbuildcaptchacouple)||
+|[buildCaptchaCouple](#bouncerbuildcaptchacouple)|Build a captcha couple.|
 |[checkCaptcha](#bouncercheckcaptcha)||
 |[clearCache](#bouncerclearcache)|This method clear the full data in cache.|
 |[configure](#bouncerconfigure)|Configure this instance.|
@@ -56,10 +56,10 @@ The main Class of this package. This is the first entry point of any PHP Bouncer
 **Description**
 
 ```php
- buildCaptchaCouple (void)
+public static buildCaptchaCouple (void)
 ```
 
- 
+Build a captcha couple. 
 
 
 
@@ -69,7 +69,9 @@ The main Class of this package. This is the first entry point of any PHP Bouncer
 
 **Return Values**
 
-`void`
+`array`
+
+> an array composed of two items, a "phrase" string representing the phrase and a "inlineImage" representing the image data
 
 
 <hr />
@@ -117,7 +119,9 @@ This method clear the full data in cache.
 
 **Return Values**
 
-`void`
+`bool`
+
+> If the cache has been successfully cleared or not
 
 
 <hr />
@@ -128,7 +132,7 @@ This method clear the full data in cache.
 **Description**
 
 ```php
-public configure (void)
+public configure (array $config)
 ```
 
 Configure this instance. 
@@ -137,7 +141,8 @@ Configure this instance.
 
 **Parameters**
 
-`This function has no parameters.`
+* `(array) $config`
+: An array with all configuration parameters  
 
 **Return Values**
 
@@ -152,7 +157,7 @@ Configure this instance.
 **Description**
 
 ```php
-public static getAccessForbiddenHtmlTemplate (void)
+public static getAccessForbiddenHtmlTemplate (array $config)
 ```
 
 Returns a default "CrowdSec 403" HTML template to display to a web browser using a banned IP. 
@@ -161,11 +166,14 @@ The input $config should match the TemplateConfiguration input format.
 
 **Parameters**
 
-`This function has no parameters.`
+* `(array) $config`
+: An array of template configuration parameters  
 
 **Return Values**
 
-`void`
+`string`
+
+> The HTML compiled template
 
 
 <hr />
@@ -176,7 +184,7 @@ The input $config should match the TemplateConfiguration input format.
 **Description**
 
 ```php
-public static getCaptchaHtmlTemplate (void)
+public static getCaptchaHtmlTemplate (array $config)
 ```
 
 Returns a default "CrowdSec Captcha" HTML template to display to a web browser using a captchable IP. 
@@ -185,11 +193,14 @@ The input $config should match the TemplateConfiguration input format.
 
 **Parameters**
 
-`This function has no parameters.`
+* `(array) $config`
+: An array of template configuration parameters  
 
 **Return Values**
 
-`void`
+`string`
+
+> The HTML compiled template
 
 
 <hr />
@@ -213,7 +224,9 @@ Returns the logger instance.
 
 **Return Values**
 
-`void`
+`\LoggerInterface`
+
+> the logger used by this library
 
 
 <hr />
@@ -224,7 +237,7 @@ Returns the logger instance.
 **Description**
 
 ```php
-public getRemediationForIp (void)
+public getRemediationForIp (string $ip)
 ```
 
 Get the remediation for the specified IP. This method use the cache layer. 
@@ -234,7 +247,8 @@ the cache system will call the API to check if there is a decision.
 
 **Parameters**
 
-`This function has no parameters.`
+* `(string) $ip`
+: The IP to check  
 
 **Return Values**
 
@@ -264,7 +278,9 @@ This method prune the cache: it removes all the expired cache items.
 
 **Return Values**
 
-`void`
+`bool`
+
+> If the cache has been successfully pruned or not
 
 
 <hr />
@@ -290,7 +306,7 @@ This method should be called periodically (ex: crontab) in a asynchronous way to
 
 `array`
 
-> number of deleted and new decisions
+> Number of deleted and new decisions, and errors when processing decisions
 
 
 <hr />
@@ -314,7 +330,9 @@ Test the connection to the cache system (Redis or Memcached).
 
 **Return Values**
 
-`void`
+`bool`
+
+> If the connection was successful or not
 
 
 **Throws Exceptions**
@@ -344,9 +362,9 @@ This method should be called only to force a cache warm up.
 
 **Return Values**
 
-`int`
+`array`
 
-> number of decisions added
+> "count": number of decisions added, "errors": decisions not added
 
 
 <hr />

src/ApiCache.php

@@ -48,6 +48,11 @@ class ApiCache
     /** @var bool */
     private $warmedUp = null;
 
+    /**
+     * @param LoggerInterface $logger    The logger to use
+     * @param ApiClient       $apiClient The APIClient instance to use
+     * @param AbstractAdapter $adapter   The AbstractAdapter adapter to use
+     */
     public function __construct(LoggerInterface $logger, ApiClient $apiClient = null, AbstractAdapter $adapter = null)
     {
         $this->logger = $logger;
@@ -57,6 +62,15 @@ public function __construct(LoggerInterface $logger, ApiClient $apiClient = null
 
     /**
      * Configure this instance.
+     *
+     * @param bool   $liveMode                  If we use the live mode (else we use the stream mode)
+     * @param string $apiUrl                    The URL of the LAPI
+     * @param int    $timeout                   The timeout well calling LAPI
+     * @param string $userAgent                 The user agent to use when calling LAPI
+     * @param string $apiKey                    The Bouncer API Key to use to connect LAPI
+     * @param int    $cacheExpirationForCleanIp The duration to cache an IP considered as clean by LAPI
+     * @param int    $cacheExpirationForBadIp   The duration to cache an IP considered as bad by LAPI
+     * @param string $fallbackRemediation       The remediation to use when the remediation sent by LAPI is not supported by this library
      */
     public function configure(
         bool $liveMode,

src/Bouncer.php

@@ -50,6 +50,8 @@ public function __construct(AbstractAdapter $cacheAdapter = null, LoggerInterfac
 
     /**
      * Configure this instance.
+     *
+     * @param array $config An array with all configuration parameters
      */
     public function configure(array $config): void
     {
@@ -80,6 +82,10 @@ public function configure(array $config): void
 
     /**
      * Cap the remediation to a fixed value given in configuration.
+     *
+     * @param string $remediation The maximum remediation that can ban applied (ex: 'ban', 'captcha', 'bypass')
+     *
+     * @return string $remediation The resulting remediation to use (ex: 'ban', 'captcha', 'bypass')
      */
     private function capRemediationLevel(string $remediation): string
     {
@@ -96,6 +102,8 @@ private function capRemediationLevel(string $remediation): string
      * In live mode, when no remediation was found in cache,
      * the cache system will call the API to check if there is a decision.
      *
+     * @param string $ip The IP to check
+     *
      * @return string the remediation to apply (ex: 'ban', 'captcha', 'bypass')
      */
     public function getRemediationForIp(string $ip): string
@@ -112,6 +120,10 @@ public function getRemediationForIp(string $ip): string
     /**
      * Returns a default "CrowdSec 403" HTML template to display to a web browser using a banned IP.
      * The input $config should match the TemplateConfiguration input format.
+     *
+     * @param array $config An array of template configuration parameters
+     *
+     * @return string The HTML compiled template
      */
     public static function getAccessForbiddenHtmlTemplate(array $config): string
     {
@@ -129,6 +141,10 @@ public static function getAccessForbiddenHtmlTemplate(array $config): string
     /**
      * Returns a default "CrowdSec Captcha" HTML template to display to a web browser using a captchable IP.
      * The input $config should match the TemplateConfiguration input format.
+     *
+     * @param array $config An array of template configuration parameters
+     *
+     * @return string The HTML compiled template
      */
     public static function getCaptchaHtmlTemplate(bool $error, string $captchaImageSrc, string $captchaResolutionFormUrl, array $config): string
     {
@@ -158,7 +174,7 @@ public function warmBlocklistCacheUp(): array
      * Used in stream mode only.
      * This method should be called periodically (ex: crontab) in a asynchronous way to update the bouncer cache.
      *
-     * @return array number of deleted and new decisions, and errors when processing decisions
+     * @return array Number of deleted and new decisions, and errors when processing decisions
      */
     public function refreshBlocklistCache(): array
     {
@@ -167,6 +183,8 @@ public function refreshBlocklistCache(): array
 
     /**
      * This method clear the full data in cache.
+     *
+     * @return bool If the cache has been successfully cleared or not
      */
     public function clearCache(): bool
     {
@@ -175,6 +193,8 @@ public function clearCache(): bool
 
     /**
      * This method prune the cache: it removes all the expired cache items.
+     *
+     * @return bool If the cache has been successfully pruned or not
      */
     public function pruneCache(): bool
     {
@@ -183,12 +203,19 @@ public function pruneCache(): bool
 
     /**
      * Returns the logger instance.
+     *
+     * @return LoggerInterface the logger used by this library
      */
     public function getLogger(): LoggerInterface
     {
         return $this->logger;
     }
 
+    /**
+     * Build a captcha couple.
+     *
+     * @return array an array composed of two items, a "phrase" string representing the phrase and a "inlineImage" representing the image data
+     */
     public static function buildCaptchaCouple()
     {
         $captchaBuilder = new CaptchaBuilder();
@@ -199,6 +226,11 @@ public static function buildCaptchaCouple()
         ];
     }
 
+    /**
+     * @param string $expected The expected phrase
+     * @param string $expected The phrase to check (the user input)
+     * @param string $ip       Th IP of the use (for logging purpose)
+     */
     public function checkCaptcha(string $expected, string $try, string $ip)
     {
         $solved = PhraseBuilder::comparePhrases($expected, $try);
@@ -214,6 +246,8 @@ public function checkCaptcha(string $expected, string $try, string $ip)
     /**
      * Test the connection to the cache system (Redis or Memcached).
      *
+     * @return bool If the connection was successful or not
+     *
      * @throws BouncerException if the connection was not successful
      * */
     public function testConnection()