Requests: Add "requests.failed" hook

This allows to inspect or alter the exception that is thrown to
the user in case of transport errors, or in case of response
parsing problems.

Author: pprkut

docs/hooks.md

@@ -31,6 +31,13 @@ Available Hooks
 
     Parameters: `WpOrg\Requests\Response &$return`
 
+* **`requests.failed`**
+
+    Alter/Inspect transport or response parsing exception before it is returned to the user.
+
+    Parameters: `WpOrg\Requests\Exception|WpOrg\Requests\Exception\InvalidArgument &$exception`, `string $url`, `array $headers`, `array|string $data`,
+    `string $type`, `array $options`
+
 * **`curl.before_request`**
 
     Set cURL options before the transport sets any (note that Requests may

src/Requests.php

@@ -466,11 +466,23 @@ public static function request($url, $headers = [], $data = [], $type = self::GE
 			$transport    = self::get_transport($capabilities);
 		}
 
-		$response = $transport->request($url, $headers, $data, $options);
+		try {
+			$response = $transport->request($url, $headers, $data, $options);
+
+			$options['hooks']->dispatch('requests.before_parse', [&$response, $url, $headers, $data, $type, $options]);
 
-		$options['hooks']->dispatch('requests.before_parse', [&$response, $url, $headers, $data, $type, $options]);
+			$parsed_response = self::parse_response($response, $url, $headers, $data, $options);
+		}
+		catch (Exception $e) {
+			$options['hooks']->dispatch('requests.failed', [$e, $url, $headers, $data, $type, $options]);
+			throw $e;
+		}
+		catch (InvalidArgument $e) {
+			$options['hooks']->dispatch('requests.failed', [$e, $url, $headers, $data, $type, $options]);
+			throw $e;
+		}
 
-		return self::parse_response($response, $url, $headers, $data, $options);
+		return $parsed_response;
 	}
 
 	/**