Added documentation and new checks and info ressources

Author: alange-xqueue

src/XQueue/AddressCheck/API/AbstractAddressCheckService.php

@@ -5,23 +5,68 @@
 use XQueue\AddressCheck\API\AddressCheckResult;
 use XQueue\AddressCheck\API\AddressCheckException;
 
+/**
+ * An abstract API service class
+ * 
+ * Defines all request methods to be used by the services and performs the request
+ */
 abstract class AbstractAddressCheckService
 {
+    /**
+     * @var string The base URI of the API service
+     */
     private $baseUri = 'https://adc.maileon.com/svc/2.0';
 
+    /**
+     * @var string The user name for authentification
+     */
     private $username;
+
+    /**
+     * @var string The password for authentification
+     */
     private $password;
 
+    /**
+     * @var string The MimeType to define the result format
+     */
     private $mimeType = 'application/json';
 
+    /**
+     * @var string A language tag according to RFC 5646
+     */
+    private $acceptLanguage;
+
+    /**
+     * @var bool Wether or not to activate debugging
+     */
     private $debug = false;
+
+    /**
+     * @var resource CURL's STDERR verbose output
+     */
     private $verboseOut;
 
+    /**
+     * @var string The host name of the used proxy
+     */
     private $proxyHost;
+
+    /**
+     * @var int The port number of the used proxy
+     */
     private $proxyPort = 80;
 
-    private $timeout;
+    /**
+     * @var int The connection's timeout limit
+     */
+    private $timeout = 10;
 
+    /**
+     * Creates a new service
+     * 
+     * @param array $config The configuration list
+     */
     public function __construct(array $config = array())
     {
         if( array_key_exists('BASE_URI', $config) ) {
@@ -57,57 +102,126 @@ public function __construct(array $config = array())
         }
     }
 
+    /**
+     * Set the base URI
+     * 
+     * @param string $baseUri Base URI to the API service
+     */
     public function setBaseUri($baseUri)
     {
         $this->baseUri = $baseUri;
     }
 
+    /**
+     * Set the user name
+     * 
+     * @param string $username The username for authentification
+     */
     public function setUsername($username)
     {
         $this->username = $username;
     }
 
+    /**
+     * Set the password
+     * 
+     * @param string $password The password for authentification
+     */
     public function setPassword($password)
     {
         $this->password = $password;
     }
 
+    /**
+     * Set the MimeType
+     * 
+     * @param string $mimeType The MimeType to send and receive body data in
+     */
     public function setMimeType($mimeType)
     {
         $this->mimeType = $mimeType;
     }
 
+    /**
+     * Set a language tag
+     * 
+     * @param string $acceptLanguage A language tag according to RFC 5646
+     */
+    protected function setAcceptLanguage($acceptLanguage)
+    {
+        $this->acceptLanguage = $acceptLanguage;
+    }
+
+    /**
+     * Set the connection's timeout
+     * 
+     * @param int $timeout The connections's timeout limit
+     */
     public function setTimeout($timeout)
     {
         $this->timeout = $timeout;
     }
 
+    /**
+     * Set the proxy host
+     * 
+     * @param string $proxyHost The host name of the used proxy
+     */
     public function setProxyHost($proxyHost)
     {
         $this->proxyHost = $proxyHost;
     }
 
+    /**
+     * Set the proxy port
+     * 
+     * @param int $proxyPort The port of the used proxy
+     */
     public function setProxyPort($proxyPort)
     {
         $this->proxyPort = $proxyPort;
     }
 
+    /**
+     * Activates or deactivates debugging
+     * 
+     * @param bool $debug Activates or deactivates debugging
+     */
     public function setDebug($debug)
     {
         $this->debug = $debug;
     }
 
+    /**
+     * Returns wether debugging is active
+     * 
+     * @return bool True if debug is active or false if debug is inactive
+     */
     public function isDebug()
     {
         return $this->debug;
     }
 
+    /**
+     * Sends a GET request
+     * 
+     * @param string $resourcePath The path of the resouce
+     * @param array $queryParameters A list of all URL parameters
+     * @return AddressCheckResult The result of the API call
+     */
     public function get($resourcePath, $queryParameters = array())
     {
         $curlSession = $this->prepareSession($resourcePath, $queryParameters);
         return $this->performRequest($curlSession);
     }
 
+    /**
+     * Prepares a CURL request
+     * 
+     * @param string $resourcePath The path of the resource
+     * @param array $queryParameters A list of all URL parameters
+     * @return \CurlHandle|false Returns the CURL handle on success or false on error
+     */
     private function prepareSession($resourcePath, $queryParameters)
     {
         $requestUrl = $this->constructRequestUrl($resourcePath, $queryParameters);
@@ -141,6 +255,13 @@ private function prepareSession($resourcePath, $queryParameters)
         return $curlSession;
     }
 
+    /**
+     * Constructs the complete URL to the API service
+     * 
+     * @param string $resourcePath The path of the resource
+     * @param array $queryParameters A list of all URL parameters
+     * @return string The complete URL
+     */
     private function constructRequestUrl($resourcePath, $queryParameters)
     {
         $requestUrl = $this->baseUri . "/" . $resourcePath;
@@ -164,22 +285,41 @@ private function constructRequestUrl($resourcePath, $queryParameters)
         return $requestUrl;
     }
 
+    /**
+     * Creates the headers for the request
+     * 
+     * @throws AddressCheckException if user name and password aren't set
+     * @return array A list of all headers
+     */
     private function constructHeaders()
     {
         if( empty($this->username) || empty($this->password) ) {
             throw new AddressCheckException("Authorization not set");
         }
 
-        $headers = array(
-            "Content-type: " . $this->mimeType,
-            "Accept: " . $this->mimeType,
-            "Authorization: Basic " . base64_encode($this->username.":".$this->password),
-            "Expect:"
-        );
+        $headers = [
+            "Authorization: Basic " . base64_encode($this->username.":".$this->password)
+        ];
+        
+        if( !empty($this->mimeType) ) {
+            $headers[] = "Content-type: " . $this->mimeType;
+            $headers[] = "Accept: " . $this->mimeType;
+        }
+
+        if( !empty($this->acceptLanguage) ) {
+            $headers[] = "Accept-Language: " . $this->acceptLanguage;
+        }
 
         return $headers;
     }
 
+    /**
+     * Executes the CURL request
+     * 
+     * @param \CurlHandle $curlSession The CURL handle to be executed
+     * @throws AddressCheckException if an error occured
+     * @return AddressCheckResult The request's result as an object
+     */
     private function performRequest($curlSession)
     {
         $response = curl_exec($curlSession);
@@ -207,6 +347,13 @@ private function performRequest($curlSession)
         }
     }
 
+    /**
+     * Prints debug information for the running CURL request
+     * 
+     * @param \CurlHandle $curlSession The CURL request
+     * @param AddressCheckResult $result The result of the CURL request
+     * @param AddressCheckException $exception A thrown exception
+     */
     private function printDebugInformation($curlSession, $result = null, $exception = null)
     {
         rewind($this->verboseOut);