Extended exception handing.

Updated the readme.

Author: Martin Brecht-Precht

README.md

@@ -224,7 +224,7 @@ use BasicHttpClient\Request\Request;
 
 // Configuring and performing a Request
 $request = new Request();
-$response = $request
+$request
 	->setUserAgent('PHP Basic HTTP Client Test 1.0')
 	->setEndpoint('https://yourapihere-com-98yq3775xff0.runscope.net/')
 	->setPort(443)
@@ -276,7 +276,7 @@ $basicAuthentication = new BasicAuthentication('username', 'password');
 
 // Adding the authentication instance to the Request
 $request = new Request();
-$response = $request->addAuthentication($basicAuthentication);
+$request->addAuthentication($basicAuthentication);
 ```
 
 #### SSL Client Certificate Authentication
@@ -296,14 +296,32 @@ $clientCertificateAuthentication = new ClientCertificateAuthentication(
 
 // Adding the authentication instance to the Request
 $request = new Request();
-$response = $request->addAuthentication($clientCertificateAuthentication);
+$request->addAuthentication($clientCertificateAuthentication);
 ```
 
 ---
 
 ## Reading from the resulting Response instance
 
-TODO
+### Getting the response object
+
+If using the `BasicHttpClient` the response object is returned by the termination methods listed above. If directly using the Request instance, you can get the Response object via a getter.
+
+```{php}
+$response = $request->getResponse();
+
+// Reading the HTTP status code as integer; will return `200`
+echo print_r($response->getStatusCode(), true).PHP_EOL;
+
+// Reading the HTTP status text as string; will return `HTTP/1.1 200 OK`
+echo print_r($response->getStatusText(), true).PHP_EOL;
+
+// Reading the HTTP response headers as array of BasicHttpClient\Response\Header\Header objects
+echo print_r($response->getHeaders(), true).PHP_EOL;
+
+// Reading the HTTP response body as string
+echo print_r($response->getBody(), true).PHP_EOL;
+```
 
 ---
 
@@ -315,7 +333,34 @@ TODO
 
 ## Getting some transactional statistics
 
-TODO
+```
+// Getting the statistics BasicHttpClient\Response\Statistics\Statistics object
+$statistics = $request->getResponse()->getStatistics();
+
+// Reading the redirection URL if the server responds with an redirect HTTP header and followRedirects is set to false
+echo print_r($statistics->getRedirectEndpoint(), true).PHP_EOL;
+
+// Reading the numbers of redirection as integer
+echo print_r($statistics->getRedirectCount(), true).PHP_EOL;
+
+// Getting the time in seconds the redirect utilized as float
+echo print_r($statistics->getRedirectTime(), true).PHP_EOL;
+
+// Getting the time in seconds that was utilized until the connection was established
+echo print_r($statistics->getConnectionEstablishTime(), true).PHP_EOL;
+
+// Getting the time in seconds that was utilized until the DNS hostname lookup was done
+echo print_r($statistics->getHostLookupTime(), true).PHP_EOL;
+
+// Getting the time in seconds that was utilized before the first data was sent
+echo print_r($statistics->getPreTransferTime(), true).PHP_EOL;
+
+// Getting the time in seconds that was utilized before the first data was received
+echo print_r($statistics->getStartTransferTime(), true).PHP_EOL;
+
+// Getting the time in seconds that was utilized to perfom the request an read the response
+echo print_r($statistics->getTotalTime(), true).PHP_EOL;
+```
 
 ---
 
@@ -333,6 +378,17 @@ Take a look at the [PHP JSON HTTP Client](https://github.com/markenwerk/php-json
 PHP Basic HTTP Client provides different exceptions – also provided by the PHP Common Exceptions project – for proper handling.  
 You can find more information about [PHP Common Exceptions at Github](https://github.com/markenwerk/php-common-exceptions).
 
+### Exceptions to be expected
+
+In general you should expect that any setter method could thrown an `\InvalidArgumentException`. The following exceptions could get thrown while using PHP Basic HTTP Client.
+
+- `CommonException\IoException\FileReadableException` on configuring a `ClientCertificateAuthentication`instance
+- `BasicHttpClient\Exception\HttpRequestAuthenticationException` on performing a request
+- `BasicHttpClient\Exception\HttpRequestException` on performing a request
+- `CommonException\NetworkException\ConnectionTimeoutException` on performing a request
+- `CommonException\NetworkException\CurlException` on performing a request
+
+
 ## Contribution
 
 Contributing to our projects is always very appreciated.  

detaild.php

@@ -3,7 +3,6 @@
 namespace Project;
 
 use BasicHttpClient\Request\Authentication\BasicAuthentication;
-use BasicHttpClient\Request\Authentication\ClientCertificateAuthentication;
 use BasicHttpClient\Request\Message\Body\Body;
 use BasicHttpClient\Request\Message\Cookie\Cookie;
 use BasicHttpClient\Request\Message\Header\Header;
@@ -45,34 +44,41 @@
 	->addCookie(new Cookie('PHPSESSID', '<MY_SESSION_ID>'))
 	->setBody($messageBody);
 
-$header1 = $message->getHeaderByName('Content-Type');
-$header2 = $message->getHeaderByName('content-type');
-$header3 = $message->getHeaderByName('CONTENT-Type');
-
 $message->addHeader(new Header('Custom-Header', array('CustomHeaderValue')));
 $message->addAdditionalHeader(new Header('Custom-Header', array('AnotherCustomHeaderValue')));
 
 $request = new Request();
-$response = $request
+$request
 	->setUserAgent('PHP Basic HTTP Client Test 1.0')
 	->setEndpoint('https://yourapihere-com-98yq3775xff0.runscope.net/')
 	->setPort(443)
 	->addAuthentication(new BasicAuthentication('username', 'password'))
 	->setQueryParameters(
 		array(
 			'paramName1' => 'paramValue1',
-			'paramName2' => 'paramValue2'
+			'paramName2' => 'paramValue2',
+			'paramName3' => true,
+			'paramName4' => 42,
 		)
 	)
 	->setMethod(Request::REQUEST_METHOD_POST)
 	->setTransport($transport)
 	->setMessage($message)
 	->perform();
 
-$auth = new ClientCertificateAuthentication(
-	'/var/www/project/clientCert/ca.crt',
-	'/var/www/project/clientCert/client.crt',
-	'clientCertPassword'
-);
+$response = $request->getResponse();
+echo print_r($response->getStatusCode(), true).PHP_EOL;
+echo print_r($response->getStatusText(), true).PHP_EOL;
+echo print_r($response->getHeaders(), true).PHP_EOL;
+echo print_r($response->getBody(), true).PHP_EOL;
+
+$statistics = $response->getStatistics();
+echo print_r($statistics->getRedirectEndpoint(), true).PHP_EOL;
+echo print_r($statistics->getRedirectCount(), true).PHP_EOL;
+echo print_r($statistics->getRedirectTime(), true).PHP_EOL;
 
-print_r($request->getEffectiveRawHeader());
+echo print_r($statistics->getConnectionEstablishTime(), true).PHP_EOL;
+echo print_r($statistics->getHostLookupTime(), true).PHP_EOL;
+echo print_r($statistics->getPreTransferTime(), true).PHP_EOL;
+echo print_r($statistics->getStartTransferTime(), true).PHP_EOL;
+echo print_r($statistics->getTotalTime(), true).PHP_EOL;

src/BasicHttpClient.php

@@ -31,6 +31,10 @@ class BasicHttpClient implements HttpClientInterface
 	 */
 	public function __construct($endpoint)
 	{
+		if (!is_string($endpoint)) {
+			$argumentType = (is_object($endpoint)) ? get_class($endpoint) : gettype($endpoint);
+			throw new \InvalidArgumentException('Expected the endpoint as string. Got ' . $argumentType);
+		}
 		$urlUtil = new UrlUtil();
 		$transport = new HttpTransport();
 		if ($urlUtil->getScheme($endpoint) == 'HTTPS') {
@@ -52,7 +56,7 @@ public function getRequest()
 	}
 
 	/**
-	 * @param string[] $queryParameters
+	 * @param mixed[] $queryParameters
 	 * @return ResponseInterface
 	 * @throws \CommonException\NetworkException\Base\NetworkException
 	 * @throws \CommonException\NetworkException\ConnectionTimeoutException
@@ -67,7 +71,7 @@ public function get(array $queryParameters = null)
 	}
 
 	/**
-	 * @param string[] $queryParameters
+	 * @param mixed[] $queryParameters
 	 * @return ResponseInterface
 	 * @throws \CommonException\NetworkException\Base\NetworkException
 	 * @throws \CommonException\NetworkException\ConnectionTimeoutException
@@ -139,7 +143,7 @@ public function patch(array $patchData = null)
 	}
 
 	/**
-	 * @param string[] $queryParameters
+	 * @param mixed[] $queryParameters
 	 * @return ResponseInterface
 	 * @throws \CommonException\NetworkException\Base\NetworkException
 	 * @throws \CommonException\NetworkException\ConnectionTimeoutException

src/Exception/HttpRequestAuthenticationException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace BasicHttpClient\Exception;
+
+/**
+ * Class HttpRequestAuthenticationException
+ *
+ * @package BasicHttpClient\Exception
+ */
+class HttpRequestAuthenticationException extends \Exception
+{
+
+}

src/Exception/HttpRequestException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace BasicHttpClient\Exception;
+
+/**
+ * Class HttpRequestException
+ *
+ * @package BasicHttpClient\Exception
+ */
+class HttpRequestException extends \Exception
+{
+
+}

src/HttpClientInterface.php

@@ -19,13 +19,13 @@ interface HttpClientInterface
 	public function getRequest();
 
 	/**
-	 * @param string[] $queryParameters
+	 * @param mixed[] $queryParameters
 	 * @return ResponseInterface
 	 */
 	public function get(array $queryParameters = null);
 
 	/**
-	 * @param string[] $queryParameters
+	 * @param mixed[] $queryParameters
 	 * @return ResponseInterface
 	 */
 	public function head(array $queryParameters = null);
@@ -49,7 +49,7 @@ public function put(array $putData = null);
 	public function patch(array $patchData = null);
 
 	/**
-	 * @param string[] $queryParameters
+	 * @param mixed[] $queryParameters
 	 * @return ResponseInterface
 	 */
 	public function delete(array $queryParameters = null);

src/Request/AbstractRequest.php

@@ -2,6 +2,7 @@
 
 namespace BasicHttpClient\Request;
 
+use BasicHttpClient\Exception\HttpRequestException;
 use BasicHttpClient\Request\Authentication\AuthenticationInterface;
 use BasicHttpClient\Request\Message\MessageInterface;
 use BasicHttpClient\Request\Message\Header\Header;
@@ -12,12 +13,11 @@
 use BasicHttpClient\Util\UrlUtil;
 use CommonException\NetworkException\Base\NetworkException;
 use CommonException\NetworkException\ConnectionTimeoutException;
+use CommonException\NetworkException\CurlException;
 
 /**
  * Class Request
  *
- * TODO: Add query params to be concatenated to the endpoints URL for performing GET, HEAD and DELETE requests.
- *
  * @package BasicHttpClient\Request
  */
 abstract class AbstractRequest implements RequestInterface
@@ -216,10 +216,14 @@ public function addQueryParameter($parameterName, $parameterValue)
 	 */
 	public function setQueryParameters($queryParameters)
 	{
-		foreach ($queryParameters as $parameterName => $parameterValue) {
-			if (!is_string($parameterName) || !is_string($parameterValue)) {
-				throw new \InvalidArgumentException('Query parameters have to be an associative array.');
+		foreach ($queryParameters as &$queryParameter) {
+			if (!is_scalar($queryParameter)) {
+				$argumentType = (is_object($queryParameter)) ? get_class($queryParameter) : gettype($queryParameter);
+				throw new \InvalidArgumentException(
+					'Expected the query parameters as array of scalar values. Got ' . $argumentType
+				);
 			}
+			$queryParameter = (string)$queryParameter;
 		}
 		$this->queryParameters = $queryParameters;
 		return $this;
@@ -351,6 +355,10 @@ public function countAuthentications()
 	 */
 	public function configureCurl($curl)
 	{
+		if (!is_resource($curl)) {
+			$argumentType = (is_object($curl)) ? get_class($curl) : gettype($curl);
+			throw new \InvalidArgumentException('curl argument invalid. Expected a valid resource. Got ' . $argumentType);
+		}
 		curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
 		curl_setopt($curl, CURLOPT_HEADER, true);
 		curl_setopt($curl, CURLINFO_HEADER_OUT, true);
@@ -386,7 +394,9 @@ public function perform()
 		$this->getTransport()->configureCurl($curl);
 		$this->getMessage()->configureCurl($curl);
 		for ($i = 0; $i < count($this->authentications); $i++) {
-			$this->authentications[$i]->configureCurl($curl);
+			$this->authentications[$i]
+				->validate($this)
+				->configureCurl($curl);
 		}
 		// Execute request
 		$responseBody = curl_exec($curl);
@@ -404,7 +414,7 @@ public function perform()
 				throw new ConnectionTimeoutException('The request timed out with message: ' . $curlErrorMessage);
 				break;
 			default:
-				throw new NetworkException('The request failed with message: ' . $curlErrorMessage);
+				throw new CurlException('The request failed with message: ' . $curlErrorMessage);
 				break;
 		}
 	}
@@ -475,7 +485,7 @@ protected function prePerform()
 	{
 		$urlUtil = new UrlUtil();
 		if ($urlUtil->getScheme($this->getEndpoint()) == 'HTTPS' && !$this->getTransport() instanceof HttpsTransport) {
-			throw new \Exception('Transport misconfiguration. Use HttpsTransport for HTTPS requests.');
+			throw new HttpRequestException('Transport misconfiguration. Use HttpsTransport for HTTPS requests.');
 		}
 	}
 

src/Request/Authentication/AuthenticationInterface.php

@@ -3,6 +3,7 @@
 namespace BasicHttpClient\Request\Authentication;
 
 use BasicHttpClient\Request\Base\CurlConfiguratorInterface;
+use BasicHttpClient\Request\RequestInterface;
 
 /**
  * Interface AuthenticationInterface
@@ -12,4 +13,10 @@
 interface AuthenticationInterface extends CurlConfiguratorInterface
 {
 
+	/**
+	 * @param RequestInterface $request
+	 * @return $this
+	 */
+	public function validate(RequestInterface $request);
+
 }

src/Request/Authentication/BasicAuthentication.php

@@ -2,6 +2,8 @@
 
 namespace BasicHttpClient\Request\Authentication;
 
+use BasicHttpClient\Request\RequestInterface;
+
 /**
  * Class BasicAuthentication
  *
@@ -69,12 +71,25 @@ public function setPassword($password)
 		return $this;
 	}
 
+	/**
+	 * @param RequestInterface $request
+	 * @return $this
+	 */
+	public function validate(RequestInterface $request)
+	{
+		return $this;
+	}
+
 	/**
 	 * @param resource $curl
 	 * @return $this
 	 */
 	public function configureCurl($curl)
 	{
+		if (!is_resource($curl)) {
+			$argumentType = (is_object($curl)) ? get_class($curl) : gettype($curl);
+			throw new \InvalidArgumentException('curl argument invalid. Expected a valid resource. Got ' . $argumentType);
+		}
 		curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
 		curl_setopt($curl, CURLOPT_USERPWD, $this->username . ':' . $this->password);
 		return $this;