v0.9.8

**Added**
- ApiResponse class is now the return type for all API endpoint methods **break change**
- New parameter confidenceScore in blacklist() method (suscribers feature)

**Changed**
- method loadFromConfig and json helper removed (moved to client) **break change**
- field userId removed (not used). ApiHandler constructor changed **break change**
- `clear()` and `getBlacklist()` method renamed to `clearAddress()` and `blacklist()` (all method names match now api endpoint in camel case) **break change**
- scrict types

README.md

@@ -14,9 +14,9 @@ Features
 - IP block check request **✓** 
 - Blacklist request **✓** 
 - Single IP report request **✓** 
-- Bulk report request (send cvs file) **✓** 
+- Bulk report request (send `csv` file) **✓** 
-- Clear IP address request (remove own reports) **✓**
+- Clear IP address request (remove your own reports) **✓**
-- Auto cleaning report comment from sensitive data  **✓** 
+- Auto cleaning report comments from sensitive data (email, custom ip/domain names list)  **✓** 
 
 Requirements
 ------------    
@@ -32,18 +32,18 @@ Deploy with composer:
 ```json
 ...
 "require": {
-    "kristuff/abuseipdb": ">=0.9.7-stable"
+    "kristuff/abuseipdb": ">=0.9.8-stable"
 },
 ```
 
-Usage
+More infos
 -----
 
-```php
+- [Project website](https://kristuff.fr/projects/abuseipdb)
-<?php
+- [Api documentation](https://kristuff.fr/projects/abuseipdb/doc)
+- [Config/Install guide](https://kristuff.fr/projects/abuseipdb/technical#configuration)
+- [CLI version](https://kristuff.fr/projects/abuseipdbcli)
 
-echo ('TODO');
-```
 
 License
 -------

lib/ApiBase.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 /**
  *     _    _                    ___ ____  ____  ____
@@ -14,7 +14,7 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @version    0.9.7
+ * @version    0.9.8
  * @copyright  2020-2021 Kristuff
  */
 
@@ -42,14 +42,6 @@ abstract class ApiBase
      */
     protected $aipdbApiKey = null; 
   
-    /**
-     * AbuseIPDB user id 
-     * 
-     * @access protected
-     * @var string $aipdbUserId  
-     */
-    protected $aipdbUserId = null; 
-
     /**
      * AbuseIPDB API v2 categories
      * shorname, id (string), long name
@@ -142,6 +134,7 @@ abstract class ApiBase
      * Get the list of report categories
      * 
      * @access public
+     *  
      * @return array
      */
     public function getCategories()
@@ -240,7 +233,7 @@ abstract class ApiBase
 
             // check if found
             if ($catIndex === false ){
-                throw new \InvalidArgumentException('Invalid report category was given : ['. $cat .  ']');
+                throw new \InvalidArgumentException('Invalid report category was given.');
             }
 
             // get Id
@@ -265,7 +258,7 @@ abstract class ApiBase
         }
 
         if ($needAnother !== false){
-            throw new \InvalidArgumentException('Invalid report category paremeter given: some categories can\'t be used alone');
+            throw new \InvalidArgumentException('Invalid report category parameter given: this category can\'t be used alone.');
         }
 
         // if here that ok

lib/ApiHandler.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 /**
  *     _    _                    ___ ____  ____  ____
@@ -14,7 +14,7 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @version    0.9.7
+ * @version    0.9.8
  * @copyright  2020-2021 Kristuff
  */
 
@@ -33,11 +33,11 @@ class ApiHandler extends ApiBase
     use CurlTrait;
 
     /**
-     * The ips to remove from message
+     * The ips to remove from report messages
-     * Generally you will add to this list yours ipv4 and ipv6, and the hostname
+     * Generally you will add to this list yours ipv4 and ipv6, hostname, domain names
      * 
      * @access protected
-     * @var array $selfIps  
+     * @var array  
      */
     protected $selfIps = []; 
 
@@ -46,14 +46,12 @@ class ApiHandler extends ApiBase
      * 
      * @access public
      * @param string  $apiKey     The AbuseIPDB api key
-     * @param string  $userId     The AbuseIPDB user's id
+     * @param array   $myIps      The Ips/domain name you don't want to display in report messages
-     * @param array   $myIps      The Ips/domain name you dont want to display in report messages
      * 
      */
-    public function __construct(string $apiKey, string $userId, array $myIps = [])
+    public function __construct(string $apiKey, array $myIps = [])
     {
         $this->aipdbApiKey = $apiKey;
-        $this->aipdbUserId = $userId;
         $this->selfIps = $myIps;
     }
 
@@ -61,56 +59,17 @@ class ApiHandler extends ApiBase
      * Get the current configuration in a indexed array
      * 
      * @access public
+     * 
      * @return array
      */
-    public function getConfig()
+    public function getConfig(): array
     {
         return array(
-            'userId'  => $this->aipdbUserId,
             'apiKey'  => $this->aipdbApiKey,
             'selfIps' => $this->selfIps,
-            // TODO  default report cat 
         );
     }
 
-    /**
-     * Get a new instance of ApiHandler with config stored in a Json file
-     * 
-     * @access public 
-     * @static
-     * @param string    $configPath     The configuration file path
-     * 
-     * @return \Kristuff\AbuseIPDB\ApiHandler
-     * @throws \InvalidArgumentException                        If the given file does not exist
-     * @throws \Kristuff\AbuseIPDB\InvalidPermissionException   If the given file is not readable 
-     */
-    public static function fromConfigFile(string $configPath)
-    {
-
-        // check file exists
-        if (!file_exists($configPath) || !is_file($configPath)){
-            throw new \InvalidArgumentException('The file [' . $configPath . '] does not exist.');
-        }
-
-        // check file is readable
-        if (!is_readable($configPath)){
-            throw new InvalidPermissionException('The file [' . $configPath . '] is not readable.');
-        }
-
-        $keyConfig = self::loadJsonFile($configPath);
-        $selfIps = [];
-        
-        // Look for other optional config files in the same directory 
-        $selfIpsConfigPath = pathinfo($configPath, PATHINFO_DIRNAME) . DIRECTORY_SEPARATOR . 'self_ips.json';
-        if (file_exists($selfIpsConfigPath)){
-            $selfIps = self::loadJsonFile($selfIpsConfigPath)->self_ips;
-        }
-
-        $app = new self($keyConfig->api_key, $keyConfig->user_id, $selfIps);
-        
-        return $app;
-    }
-
     /**
      * Performs a 'report' api request
      * 
@@ -124,14 +83,14 @@ class ApiHandler extends ApiBase
      * 
      * @access public
      * @param string    $ip             The ip to report
-     * @param string    $categories     The report categories
+     * @param string    $categories     The report category(es)
      * @param string    $message        The report message
-     * @param bool      $returnArray    True to return an indexed array instead of object. Default is false. 
      *
-     * @return object|array
+     * @return ApiResponse
+     * @throws \RuntimeException
      * @throws \InvalidArgumentException
      */
-    public function report(string $ip = '', string $categories = '', string $message = '', bool $returnArray = false)
+    public function report(string $ip, string $categories, string $message): ApiResponse
     {
          // ip must be set
         if (empty($ip)){
@@ -140,12 +99,12 @@ class ApiHandler extends ApiBase
 
         // categories must be set
         if (empty($categories)){
-            throw new \InvalidArgumentException('categories list was empty');
+            throw new \InvalidArgumentException('Categories list was empty');
         }
 
         // message must be set
         if (empty($message)){
-            throw new \InvalidArgumentException('report message was empty');
+            throw new \InvalidArgumentException('Report message was empty');
         }
 
         // validates categories, clean message 
@@ -153,7 +112,7 @@ class ApiHandler extends ApiBase
         $msg  = $this->cleanMessage($message);
 
         // AbuseIPDB request
-        $response = $this->apiRequest(
+        return $this->apiRequest(
             'report', [
                 'ip'            => $ip,
                 'categories'    => $cats,
@@ -161,8 +120,6 @@ class ApiHandler extends ApiBase
             ],
             'POST'
         );
-
-        return json_decode($response, $returnArray);
     }
 
     /**
@@ -193,15 +150,13 @@ class ApiHandler extends ApiBase
      *   }
      *  
      * @access public
-     * @param string    $ip             The ip to report
+     * @param string    $filePath       The CSV file path. Could be an absolute or relative path.
-     * @param string    $categories     The report categories
-     * @param string    $message        The report message
-     * @param bool      $returnArray    True to return an indexed array instead of object. Default is false. 
      *
-     * @return object|array
+     * @return ApiResponse
+     * @throws \RuntimeException
      * @throws \InvalidArgumentException
      */
-    public function bulkReport(string $filePath, bool $returnArray = false)
+    public function bulkReport(string $filePath): ApiResponse
     {
         // check file exists
         if (!file_exists($filePath) || !is_file($filePath)){
@@ -213,10 +168,7 @@ class ApiHandler extends ApiBase
             throw new InvalidPermissionException('The file [' . $filePath . '] is not readable.');
         }
 
-        // AbuseIPDB request
+        return $this->apiRequest('bulk-report', [], 'POST', $filePath);
-        $response = $this->apiRequest('bulk-report', [], 'POST', $filePath);
-
-        return json_decode($response, $returnArray);
     }
 
     /**
@@ -231,26 +183,20 @@ class ApiHandler extends ApiBase
      *    }
      * 
      * @access public
-     * @param string    $ip             The ip to check
+     * @param string    $ip             The IP to clear reports
-     * @param bool      $returnArray    True to return an indexed array instead of object. Default is false. 
      * 
-     * @return object|array
+     * @return ApiResponse
+     * @throws \RuntimeException
      * @throws \InvalidArgumentException    When ip value was not set. 
      */
-    public function clear(string $ip = null, bool $returnArray = false)
+    public function clearAddress(string $ip): ApiResponse
     {
         // ip must be set
         if (empty($ip)){
-            throw new \InvalidArgumentException('ip argument must be set (null given)');
+            throw new \InvalidArgumentException('IP argument must be set.');
         }
 
-        // minimal data
+        return $this->apiRequest('clear-address',  ['ipAddress' => $ip ], "DELETE") ;
-        $data = [
-            'ipAddress'     => $ip, 
-        ];
-
-        $response = $this->apiRequest('clear-address', $data, "DELETE") ;
-        return json_decode($response, $returnArray);
     }
 
     /**
@@ -258,29 +204,29 @@ class ApiHandler extends ApiBase
      * 
      * @access public
      * @param string    $ip             The ip to check
-     * @param int       $maxAge         Max age in days
+     * @param int       $maxAgeInDays   Max age in days. Default is 30.
-     * @param bool      $verbose        True to get the full response. Default is false
+     * @param bool      $verbose        True to get the full response (last reports and countryName). Default is false
-     * @param bool      $returnArray    True to return an indexed array instead of object. Default is false. 
      * 
-     * @return object|array
+     * @return ApiResponse
+     * @throws \RuntimeException
      * @throws \InvalidArgumentException    when maxAge is less than 1 or greater than 365, or when ip value was not set. 
      */
-    public function check(string $ip = null, int $maxAge = 30, bool $verbose = false, bool $returnArray = false)
+    public function check(string $ip, int $maxAgeInDays = 30, bool $verbose = false): ApiResponse
     {
         // max age must be less or equal to 365
-        if ($maxAge > 365 || $maxAge < 1){
+        if ($maxAgeInDays > 365 || $maxAgeInDays < 1){
-            throw new \InvalidArgumentException('maxAge must be at least 1 and less than 365 (' . $maxAge . ' was given)');
+            throw new \InvalidArgumentException('maxAgeInDays must be between 1 and 365 (' . $maxAgeInDays . ' was given)');
         }
 
         // ip must be set
         if (empty($ip)){
-            throw new \InvalidArgumentException('ip argument must be set (null given)');
+            throw new \InvalidArgumentException('ip argument must be set (empty value given)');
         }
 
         // minimal data
         $data = [
             'ipAddress'     => $ip, 
-            'maxAgeInDays'  => $maxAge,  
+            'maxAgeInDays'  => $maxAgeInDays,  
         ];
 
         // option
@@ -288,9 +234,7 @@ class ApiHandler extends ApiBase
            $data['verbose'] = true;
         }
 
-        $response = $this->apiRequest('check', $data, 'GET') ;
+        return $this->apiRequest('check', $data, 'GET') ;
-
-        return json_decode($response, $returnArray);
     }
 
     /**
@@ -330,57 +274,56 @@ class ApiHandler extends ApiBase
      * 
      * @access public
      * @param string    $network        The network to check
-     * @param int       $maxAge         Max age in days
+     * @param int       $maxAgeInDays   The Max age in days, must 
-     * @param bool      $returnArray    True to return an indexed array instead of object. Default is false. 
      * 
-     * @return object|array
+     * @return ApiResponse
-     * @throws \InvalidArgumentException    when maxAge is less than 1 or greater than 365, or when network value was not set. 
+     * @throws \RuntimeException
+     * @throws \InvalidArgumentException    when $maxAgeInDays is less than 1 or greater than 365, or when $network value was not set. 
      */
-    public function checkBlock(string $network = null, int $maxAge = 30, bool $returnArray = false)
+    public function checkBlock(string $network, int $maxAgeInDays = 30): ApiResponse
     {
-        // max age must be less or equal to 365
+        // max age must be between 1 and 365
-        if ($maxAge > 365 || $maxAge < 1){
+        if ($maxAgeInDays > 365 || $maxAgeInDays < 1){
-            throw new \InvalidArgumentException('maxAge must be at least 1 and less than 365 (' . $maxAge . ' was given)');
+            throw new \InvalidArgumentException('maxAgeInDays must be between 1 and 365 (' . $maxAgeInDays . ' was given)');
         }
 
         // ip must be set
         if (empty($network)){
-            throw new \InvalidArgumentException('network argument must be set (null given)');
+            throw new \InvalidArgumentException('network argument must be set (empty value given)');
         }
 
         // minimal data
         $data = [
             'network'       => $network, 
-            'maxAgeInDays'  => $maxAge,  
+            'maxAgeInDays'  => $maxAgeInDays,  
         ];
 
-        $response = $this->apiRequest('check-block', $data, 'GET') ;
+        return $this->apiRequest('check-block', $data, 'GET');
-
-        return json_decode($response, $returnArray);
     }
 
     /**
      * Perform a 'blacklist' api request
      * 
      * @access public
-     * @param int       $limit          The blacklist limit. Default is TODO (the api default limit) 
+     * @param int       $limit              The blacklist limit. Default is 10000 (the api default limit) 
-     * @param bool      $plainText      True to get the response in plain text list. Default is false
+     * @param bool      $plainText          True to get the response in plaintext list. Default is false
-     * @param bool      $returnArray    True to return an indexed array instead of object (when $plainText is set to false). Default is false. 
+     * @param int       $confidenceMinimum  The abuse confidence score minimum (subscribers feature). Default is 100.
+     *                                      The confidence minimum must be between 25 and 100.
+     *                                      This parameter is subscriber feature (not honored otherwise).
      * 
-     * @return object|array|string
+     * @return ApiResponse
-     * @throws \InvalidArgumentException    When maxAge is not a numeric value, when maxAge is less than 1 or 
+     * @throws \RuntimeException
-     *                                      greater than 365, or when ip value was not set. 
+     * @throws \InvalidArgumentException    When maxAge is not a numeric value, when $limit is less than 1. 
      */
-    public function getBlacklist(int $limit = 10000, bool $plainText = false, bool $returnArray = false)
+    public function blacklist(int $limit = 10000, bool $plainText = false, int $confidenceMinimum = 100): ApiResponse
     {
-
         if ($limit < 1){
             throw new \InvalidArgumentException('limit must be at least 1 (' . $limit . ' was given)');
         }
 
         // minimal data
         $data = [
-            'confidenceMinimum' => 100, // The abuseConfidenceScore parameter is a subscriber feature. 
+            'confidenceMinimum' => $confidenceMinimum, 
             'limit'             => $limit,
         ];
 
@@ -390,13 +333,7 @@ class ApiHandler extends ApiBase
             $data['plaintext'] = $plainText;
         }
 
-        $response = $this->apiRequest('blacklist', $data, 'GET');
+        return $this->apiRequest('blacklist', $data, 'GET');
-
-        if ($plainText){
-            return $response;
-        } 
-       
-        return json_decode($response, $returnArray);
     }
   
     /**
@@ -406,13 +343,13 @@ class ApiHandler extends ApiBase
      * @param string    $path           The api end path 
      * @param array     $data           The request data 
      * @param string    $method         The request method. Default is 'GET' 
-     * @param bool      $csvFilePath    The file path for csv file. When not empty, $data parameter is ignored and in place,
+     * @param string    $csvFilePath    The file path for csv file. When not empty, $data parameter is ignored and in place,
      *                                  the content of the given file if passed as csv. Default is empty string. 
      * 
-     * @return mixed
+     * @return ApiResponse
      * @throws \RuntimeException
      */
-    protected function apiRequest(string $path, array $data, string $method = 'GET', string $csvFilePath = '') 
+    protected function apiRequest(string $path, array $data, string $method = 'GET', string $csvFilePath = ''): ApiResponse
     {
         // set api url
         $url = $this->aipdbApiEndpoint . $path; 
@@ -438,6 +375,7 @@ class ApiHandler extends ApiBase
         if ($method == 'POST') {
             $this->setCurlOption($ch, CURLOPT_POST, true);
             $this->setCurlOption($ch, CURLOPT_POSTFIELDS, $data);
+        
         } else {
             $this->setCurlOption($ch, CURLOPT_CUSTOMREQUEST, $method);
             $url .= '?' . http_build_query($data);
@@ -454,8 +392,7 @@ class ApiHandler extends ApiBase
         // close connection
         curl_close($ch);
   
-        // return response as is (JSON or plain text)
+        return new ApiResponse($result !== false ? $result : '');
-        return $result;
     }
 
     /** 
@@ -468,7 +405,7 @@ class ApiHandler extends ApiBase
      *  
 	 * @return string
      */
-    protected function cleanMessage(string $message)
+    public function cleanMessage(string $message): string
     {
         // Remove backslashes
         $message = str_replace('\\', '', $message);
@@ -485,38 +422,4 @@ class ApiHandler extends ApiBase
         // Make sure message is less 1024 chars
         return substr($message, 0, 1024);
     }
-
-    /** 
-     * Load and returns decoded Json from given file  
-     *
-     * @access public
-     * @static
-	 * @param string    $filePath       The file's full path
-	 * @param bool      $throwError     Throw error on true or silent process. Default is true
-     *  
-	 * @return object|null 
-     * @throws \Exception
-     * @throws \LogicException
-     */
-    protected static function loadJsonFile(string $filePath, bool $throwError = true)
-    {
-        // check file exists
-        if (!file_exists($filePath) || !is_file($filePath)){
-           if ($throwError) {
-                throw new \Exception('Config file not found');
-           }
-           return null;  
-        }
-
-        // get and parse content
-        $content = utf8_encode(file_get_contents($filePath));
-        $json    = json_decode($content);
-
-        // check for errors
-        if ($json == null && json_last_error() != JSON_ERROR_NONE && $throwError) {
-            throw new \LogicException(sprintf("Failed to parse config file Error: '%s'", json_last_error_msg()));
-        }
-
-        return $json;        
-    }
 }

lib/ApiResponse.php

@@ -0,0 +1,83 @@
+<?php declare(strict_types=1);
+
+/**
+ *     _    _                    ___ ____  ____  ____
+ *    / \  | |__  _   _ ___  ___|_ _|  _ \|  _ \| __ )
+ *   / _ \ | '_ \| | | / __|/ _ \| || |_) | | | |  _ \
+ *  / ___ \| |_) | |_| \__ \  __/| ||  __/| |_| | |_) |
+ * /_/   \_\_.__/ \__,_|___/\___|___|_|   |____/|____/
+ *
+ * This file is part of Kristuff\AbsuseIPDB.
+ *
+ * (c) Kristuff <contact@kristuff.fr>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @version    0.9.8
+ * @copyright  2020-2021 Kristuff
+ */
+
+namespace Kristuff\AbuseIPDB;
+
+/**
+ * Class ApiResponse
+ * 
+ */
+class ApiResponse
+{
+    /**
+     * 
+     * @access protected
+     * @var string 
+     */
+    protected $curlResponse; 
+
+    /**
+     * Constructor
+     * 
+     * @access public
+     * @param string     $plaintext      AbuseIPDB response in plaintext 
+     * 
+     */
+    public function __construct(?string $plaintext = null)
+    {
+        $this->curlResponse = $plaintext;
+    }
+
+    /**
+     * Get response as array. May return null
+     * 
+     * @access public
+     * 
+     * @return array|null
+     */
+    public function getArray(): ?array
+    {
+        return json_decode($this->curlResponse, true);
+    }
+
+    /**
+     * Get response as object. May return null
+     * 
+     * @access public
+     * 
+     * @return object|null
+     */
+    public function getObject(): ?object
+    {
+        return json_decode($this->curlResponse, false);
+    }
+
+    /**
+     * Get response as plaintext. May return null
+     * 
+     * @access public
+     * 
+     * @return string|null
+     */
+    public function getPlaintext(): ?string
+    {
+        return $this->curlResponse;
+    }
+}

lib/CurlTrait.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 /**
  *     _    _                    ___ ____  ____  ____
@@ -14,7 +14,7 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @version    0.9.7
+ * @version    0.9.8
  * @copyright  2020-2021 Kristuff
  */
 
@@ -36,7 +36,8 @@ trait CurlTrait
      * @return void
      * @throws \RuntimeException
      */
-    protected function setCurlOption($ch,int $option,$value){
+    protected function setCurlOption($ch, int $option, $value): void
+    {
         if(!curl_setopt($ch,$option,$value)){
             throw new \RuntimeException('curl_setopt failed! '.curl_error($ch));
         }

lib/InvalidPermissionException.php

@@ -1,4 +1,4 @@
-<?php
+<?php declare(strict_types=1);
 
 /**
  *     _    _                    ___ ____  ____  ____
@@ -14,7 +14,7 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  *
- * @version    0.9.7
+ * @version    0.9.8
  * @copyright  2020-2021 Kristuff
  */