diff --git a/README.md b/README.md index 0407e2f8..363b57b8 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,25 @@ $hubspot = new SevenShores\Hubspot\Factory([ ``` *Note:* The Client class checks for a `HUBSPOT_SECRET` environment variable if you don't include an api key or oauth token during instantiation. +*Note:* You can prevent any error handling provided by this package by passing following options into client creation routine: +(applies also to `Factory::create()` and `Factory::createWithToken()`) + +```php +$hubspot = new SevenShores\Hubspot\Factory([ + 'key' => 'demo', + 'oauth' => false, // default + 'base_url' => 'https://api.hubapi.com' // default +], +[ + 'http_errors' = true // pass any Guzzle related option to any request, e.g. throw no exceptions +], +false // return Guzzle Response object for any ->request(*) call +); +``` + +By setting `http_errors` to true, you will not receive any exceptions at all, but pure responses. +For possible options, see http://docs.guzzlephp.org/en/latest/request-options.html. + #### Get a single contact: ```php diff --git a/src/Factory.php b/src/Factory.php index 97779aa8..71306af2 100644 --- a/src/Factory.php +++ b/src/Factory.php @@ -38,36 +38,42 @@ class Factory /** * C O N S T R U C T O R ( ^_^)y * - * @param array $config An array of configurations. You need at least the 'key'. - * @param Client $client + * @param array $config An array of configurations. You need at least the 'key'. + * @param Client $client + * @param array $clientOptions options to be send with each request + * @param bool $wrapResponse wrap request response in own Response object */ - function __construct($config = [], $client = null) + public function __construct($config = [], $client = null, $clientOptions = [], $wrapResponse = true) { - $this->client = $client ?: new Client($config); + $this->client = $client ?: new Client($config, null, $clientOptions, $wrapResponse); } /** * Create an instance of the service with an API key. * - * @param string $api_key Hubspot API key. - * @param Client $client An Http client. + * @param string $api_key Hubspot API key. + * @param Client $client An Http client. + * @param array $clientOptions options to be send with each request + * @param bool $wrapResponse wrap request response in own Response object * @return static */ - static function create($api_key = null, $client = null) + public static function create($api_key = null, $client = null, $clientOptions = [], $wrapResponse = true) { - return new static(['key' => $api_key], $client); + return new static(['key' => $api_key], $client, $clientOptions, $wrapResponse); } /** * Create an instance of the service with an Oauth token. * - * @param string $token Hubspot oauth access token. - * @param Client $client An Http client. + * @param string $token Hubspot oauth access token. + * @param Client $client An Http client. + * @param array $clientOptions options to be send with each request + * @param bool $wrapResponse wrap request response in own Response object * @return static */ - static function createWithToken($token, $client = null) + public static function createWithToken($token, $client = null, $clientOptions = [], $wrapResponse = true) { - return new static(['key' => $token, 'oauth' => true], $client); + return new static(['key' => $token, 'oauth' => true], $client, $clientOptions, $wrapResponse); } /** diff --git a/src/Http/Client.php b/src/Http/Client.php index 91ac8ee1..7456ed79 100644 --- a/src/Http/Client.php +++ b/src/Http/Client.php @@ -3,6 +3,8 @@ namespace SevenShores\Hubspot\Http; use GuzzleHttp\Client as GuzzleClient; +use GuzzleHttp\Psr7\Response; +use Psr\Http\Message\ResponseInterface; use SevenShores\Hubspot\Exceptions\BadRequest; use SevenShores\Hubspot\Exceptions\InvalidArgument; @@ -10,7 +12,6 @@ class Client { /** @var string */ public $key; - /** @var bool */ public $oauth; @@ -23,18 +24,36 @@ class Client /** @var \GuzzleHttp\Client */ public $client; + /** + * Guzzle allows options into its request method. Prepare for some defaults + * @var array + */ + protected $clientOptions = []; + + /** + * if set to false, no Response object is created, but the one from Guzzle is directly returned + * comes in handy own error handling + * + * @var bool + */ + protected $wrapResponse = true; + /** @var string */ private $user_agent = "SevenShores_Hubspot_PHP/1.0.0-rc.1 (https://github.com/ryanwinchester/hubspot-php)"; /** * Make it, baby. * - * @param array $config Configuration array + * @param array $config Configuration array * @param GuzzleClient $client The Http Client (Defaults to Guzzle) - * @throws \SevenShores\Hubspot\Exceptions\InvalidArgument + * @param array $clientOptions options to be passed to Guzzle upon each request + * @param bool $wrapResponse wrap request response in own Response object */ - function __construct($config = [], $client = null) + public function __construct($config = [], $client = null, $clientOptions = [], $wrapResponse = true) { + $this->clientOptions = $clientOptions; + $this->wrapResponse = $wrapResponse; + $this->key = isset($config["key"]) ? $config["key"] : getenv("HUBSPOT_SECRET"); if (empty($this->key)) { throw new InvalidArgument("You must provide a Hubspot api key or token."); @@ -61,13 +80,14 @@ function __construct($config = [], $client = null) * @param array $options An array of options to send with the request * @param string $query_string A query string to send with the request * @param boolean $requires_auth Whether or not this HubSpot API endpoint requires authentication - * @return \SevenShores\Hubspot\Http\Response + * @return \SevenShores\Hubspot\Http\Response|ResponseInterface * @throws \SevenShores\Hubspot\Exceptions\BadRequest */ - function request($method, $endpoint, $options = [], $query_string = null, $requires_auth = true) + public function request($method, $endpoint, $options = [], $query_string = null, $requires_auth = true) { $url = $this->generateUrl($endpoint, $query_string, $requires_auth); + $options = array_merge($this->clientOptions, $options); $options["headers"]["User-Agent"] = $this->user_agent; if ($this->oauth2) { @@ -75,6 +95,9 @@ function request($method, $endpoint, $options = [], $query_string = null, $requi } try { + if ($this->wrapResponse === false) { + return $this->client->request($method, $url, $options); + } return new Response($this->client->request($method, $url, $options)); } catch (\Exception $e) { throw new BadRequest($e->getMessage(), $e->getCode(), $e);