You just sent your very first mailing!
', 'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!', ], 'substitution_data'=>['name'=>'YOUR FIRST NAME'], 'recipients'=>[ [ 'address'=>[ 'name'=>'YOUR FULL NAME', 'email'=>'YOUR EMAIL ADDRESS' ] ] ] ]); echo 'Woohoo! You just sent your first mailing!'; } catch (\Exception $err) { echo 'Whoops! Something went wrong'; var_dump($err); } ``` #### 1.0 ```php try { // Build your email and send it! $results = $sparky->transmission->send([ 'from'=>[ 'name' => 'From Envelope', 'email' => 'from@sparkpostbox.com>' ], 'html'=>'You just sent your very first mailing!
', 'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!', 'substitutionData'=>['name'=>'YOUR FIRST NAME'], 'subject'=>'First Mailing From PHP', 'recipients'=>[ [ 'address'=>[ 'name'=>'YOUR FULL NAME', 'email'=>'YOUR EMAIL ADDRESS' ] ] ] ]); echo 'Woohoo! You just sent your first mailing!'; } catch (\Exception $err) { echo 'Whoops! Something went wrong'; var_dump($err); } ``` ================================================ FILE: README.md ================================================
[Sign up](https://app.sparkpost.com/join?plan=free-0817?src=Social%20Media&sfdcid=70160000000pqBb&pc=GitHubSignUp&utm_source=github&utm_medium=social-media&utm_campaign=github&utm_content=sign-up) for a SparkPost account and visit our [Developer Hub](https://developers.sparkpost.com) for even more content.
# SparkPost PHP Library
[](https://travis-ci.org/SparkPost/php-sparkpost)
[](https://coveralls.io/github/SparkPost/php-sparkpost?branch=master)
[](https://packagist.org/packages/sparkpost/sparkpost)
[](https://packagist.org/packages/sparkpost/sparkpost)
The official PHP library for using [the SparkPost REST API](https://developers.sparkpost.com/api/).
Before using this library, you must have a valid API Key. To get an API Key, please log in to your SparkPost account and generate one in the Settings page.
## Installation
**Please note: The composer package `sparkpost/php-sparkpost` has been changed to `sparkpost/sparkpost` starting with version 2.0.**
The recommended way to install the SparkPost PHP Library is through composer.
```
# Install Composer
curl -sS https://getcomposer.org/installer | php
```
Sparkpost requires php-http client (see [Setting up a Request Adapter](#setting-up-a-request-adapter)). There are several [providers](https://packagist.org/providers/php-http/client-implementation) available. If you were using guzzle6 your install might look like this.
```
composer require php-http/guzzle6-adapter "^1.1"
composer require guzzlehttp/guzzle "^6.0"
```
Next, run the Composer command to install the SparkPost PHP Library:
```
composer require sparkpost/sparkpost
```
After installing, you need to require Composer's autoloader:
```php
require 'vendor/autoload.php';
use SparkPost\SparkPost;
```
**Note:** Without composer the costs outweigh the benefits of using the PHP client library. A simple function like the one in [issue #164](https://github.com/SparkPost/php-sparkpost/issues/164#issuecomment-289888237) wraps the SparkPost API and makes it easy to use the API without resolving the composer dependencies.
## Running with IDEs
When running with `xdebug` under an IDE such as VS Code, you may see an exception is thrown in file `vendor/php-http/discovery/src/Strategy/PuliBetaStrategy.php`:
```
Exception has occurred.
Http\Discovery\Exception\PuliUnavailableException: Puli Factory is not available
```
[This is usual](http://docs.php-http.org/en/latest/discovery.html#puli-factory-is-not-available). Puli is not required to use the library. You can resume running after the exception.
You can prevent the exception, by setting the discovery strategies, prior to creating the adapter object:
```php
// Prevent annoying "Puli exception" during work with xdebug / IDE
// See https://github.com/getsentry/sentry-php/issues/801
\Http\Discovery\ClassDiscovery::setStrategies([
// \Http\Discovery\Strategy\PuliBetaStrategy::class, // Deliberately disabled
\Http\Discovery\Strategy\CommonClassesStrategy::class,
\Http\Discovery\Strategy\CommonPsr17ClassesStrategy::class,
]);
```
## Setting up a Request Adapter
Because of dependency collision, we have opted to use a request adapter rather than
requiring a request library. This means that your application will need to pass in
a request adapter to the constructor of the SparkPost Library. We use the [HTTPlug](https://github.com/php-http/httplug) in SparkPost. Please visit their repo for a list of supported [clients and adapters](http://docs.php-http.org/en/latest/clients.html). If you don't currently use a request library, you will
need to require one and create a client from it and pass it along. The example below uses the GuzzleHttp Client Library.
A Client can be setup like so:
```php
'YOUR_API_KEY']);
?>
```
## Initialization
#### new Sparkpost(httpClient, options)
* `httpClient`
* Required: Yes
* HTTP client or adapter supported by HTTPlug
* `options`
* Required: Yes
* Type: `String` or `Array`
* A valid Sparkpost API key or an array of options
* `options.key`
* Required: Yes
* Type: `String`
* A valid Sparkpost API key
* `options.host`
* Required: No
* Type: `String`
* Default: `api.sparkpost.com`
* `options.protocol`
* Required: No
* Type: `String`
* Default: `https`
* `options.port`
* Required: No
* Type: `Number`
* Default: 443
* `options.version`
* Required: No
* Type: `String`
* Default: `v1`
* `options.async`
* Required: No
* Type: `Boolean`
* Default: `true`
* `async` defines if the `request` function sends an asynchronous or synchronous request. If your client does not support async requests set this to `false`
* `options.retries`
* Required: No
* Type: `Number`
* Default: `0`
* `retries` controls how many API call attempts the client makes after receiving a 5xx response
* `options.debug`
* Required: No
* Type: `Boolean`
* Default: `false`
* If `debug` is true, then all `SparkPostResponse` and `SparkPostException` instances will return any array of the request values through the function `getRequest`
## Methods
### request(method, uri [, payload [, headers]])
* `method`
* Required: Yes
* Type: `String`
* HTTP method for request
* `uri`
* Required: Yes
* Type: `String`
* The URI to receive the request
* `payload`
* Required: No
* Type: `Array`
* If the method is `GET` the values are encoded into the URL. Otherwise, if the method is `POST`, `PUT`, or `DELETE` the payload is used for the request body.
* `headers`
* Required: No
* Type: `Array`
* Custom headers to be sent with the request.
### syncRequest(method, uri [, payload [, headers]])
Sends a synchronous request to the SparkPost API and returns a `SparkPostResponse`
### asyncRequest(method, uri [, payload [, headers]])
Sends an asynchronous request to the SparkPost API and returns a `SparkPostPromise`
### setHttpClient(httpClient)
* `httpClient`
* Required: Yes
* HTTP client or adapter supported by HTTPlug
### setOptions(options)
* `options`
* Required: Yes
* Type: `Array`
* See constructor
## Endpoints
### transmissions
* **post(payload)**
* `payload` - see request options
* `payload.cc`
* Required: No
* Type: `Array`
* Recipients to receive a carbon copy of the transmission
* `payload.bcc`
* Required: No
* Type: `Array`
* Recipients to discreetly receive a carbon copy of the transmission
## Examples
### Send An Email Using The Transmissions Endpoint
```php
getenv('SPARKPOST_API_KEY'), 'async' => false]);
try {
$response = $sparky->transmissions->post([
'content' => [
'from' => [
'name' => 'SparkPost Team',
'email' => 'from@sparkpostbox.com',
],
'subject' => 'First Mailing From PHP',
'html' => 'You just sent your very first mailing!
', 'text' => 'Congratulations, {{name}}!! You just sent your very first mailing!', ], 'substitution_data' => ['name' => 'YOUR_FIRST_NAME'], 'recipients' => [ [ 'address' => [ 'name' => 'YOUR_NAME', 'email' => 'YOUR_EMAIL', ], ], ], 'cc' => [ [ 'address' => [ 'name' => 'ANOTHER_NAME', 'email' => 'ANOTHER_EMAIL', ], ], ], 'bcc' => [ [ 'address' => [ 'name' => 'AND_ANOTHER_NAME', 'email' => 'AND_ANOTHER_EMAIL', ], ], ], ]); } catch (\Exception $error) { var_dump($error); } print($response->getStatusCode()); $results = $response->getBody()['results']; var_dump($results); ?> ``` More examples [here](./examples/): ### [Transmissions](./examples/transmissions/) - Create with attachment - Create with recipient list - Create with cc and bcc - Create with template - Create - Delete (scheduled transmission by campaign_id *only*) ### [Templates](./examples/templates/) - Create - Get - Get (list) all - Update - Delete ### [Message Events](./examples/message-events/) - get - get (with retry logic) ### Send An API Call Using The Base Request Function We provide a base request function to access any of our API resources. ```php getenv('SPARKPOST_API_KEY'), 'async' => false]); $webhookId = 'afd20f50-865a-11eb-ac38-6d7965d56459'; $response = $sparky->request('DELETE', 'webhooks/' . $webhookId); print($response->getStatusCode()); ?> ``` > Be sure to not have a leading `/` in your resource URI. For complete list of resources, refer to [API documentation](https://developers.sparkpost.com/api/). ## Handling Responses The API calls either return a `SparkPostPromise` or `SparkPostResponse` depending on if `async` is `true` or `false` ### Synchronous ```php $sparky->setOptions(['async' => false]); try { $response = ... // YOUR API CALL GOES HERE echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ``` ### Asynchronous Asynchronous an be handled in two ways: by passing callbacks or waiting for the promise to be fulfilled. Waiting acts like synchronous request. ##### Wait (Synchronous) ```php $promise = ... // YOUR API CALL GOES HERE try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } echo "I will print out after the promise is fulfilled"; ``` ##### Then (Asynchronous) ```php $promise = ... // YOUR API CALL GOES HERE $promise->then( // Success callback function ($response) { echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; }, // Failure callback function (Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ); echo "I will print out before the promise is fulfilled"; // You can combine multiple promises using \GuzzleHttp\Promise\all() and other functions from the library. $promise->wait(); ``` ## Handling Exceptions An exception will be thrown in two cases: there is a problem with the request or the server returns a status code of `400` or higher. ### SparkPostException * **getCode()** * Returns the response status code of `400` or higher * **getMessage()** * Returns the exception message * **getBody()** * If there is a response body it returns it as an `Array`. Otherwise it returns `null`. * **getRequest()** * Returns an array with the request values `method`, `url`, `headers`, `body` when `debug` is `true` ### Contributing See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md). ================================================ FILE: composer.json ================================================ { "name": "sparkpost/sparkpost", "description": "Client library for interfacing with the SparkPost API.", "license": "MIT", "authors": [ { "name": "SparkPost" } ], "minimum-stability": "stable", "scripts": { "test": "XDEBUG_MODE=coverage ./vendor/bin/phpunit", "fix-style": "php-cs-fixer fix ." }, "require": { "php": "^7.1 || ^8.0", "php-http/httplug": "^1.0 || ^2.0", "php-http/message": "^1.0", "php-http/client-implementation": "^1.0", "php-http/discovery": "^1.0" }, "require-dev": { "phpunit/phpunit": "^8.0 || ^9.0", "php-http/guzzle6-adapter": "^1.0", "mockery/mockery": "^1.3", "nyholm/nsa": "^1.0", "php-coveralls/php-coveralls": "^2.4", "friendsofphp/php-cs-fixer": "^2.18" }, "autoload": { "psr-4": { "SparkPost\\": "lib/SparkPost" } }, "autoload-dev": { "psr-4": { "SparkPost\\Test\\": "test/unit" } } } ================================================ FILE: examples/bootstrap.php ================================================ getenv('SPARKPOST_API_KEY'), // fetch API KEY from environment variable "debug" => true ]); $promise = $sparky->request('GET', 'templates'); try { $response = $promise->wait(); var_dump($response); echo "Request:\n"; print_r($response->getRequest()); echo "Response:\n"; echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo "Request:\n"; print_r($e->getRequest()); echo "Exception:\n"; echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/message-events/get_message_events.php ================================================ getenv('SPARKPOST_API_KEY')]); // New endpoint - https://developers.sparkpost.com/api/events/ $promise = $sparky->request('GET', 'events/message', [ 'campaign_ids' => 'CAMPAIGN_ID', ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/message-events/get_message_events_with_retry_logic.php ================================================ getenv('SPARKPOST_API_KEY'), "retries" => 3]); // New endpoint - https://developers.sparkpost.com/api/events/ $promise = $sparky->request('GET', 'events/message', [ 'campaign_ids' => 'CAMPAIGN_ID', ]); /** * If this fails with a 5xx it will have failed 4 times */ try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; if ($e->getCode() >= 500 && $e->getCode() <= 599) { echo "Wow, this failed epically"; } } ================================================ FILE: examples/templates/create_template.php ================================================ getenv('SPARKPOST_API_KEY')]); $template_name = "PHP example template"; $template_id = "PHP-example-template"; // put your own sending domain here $sending_domain = "steve2-test.trymsys.net"; // Valid short template content examples $plain_text = 'Write your text message part here.'; $html = <<Write your HTML message part here
HTML; $amp_html = << Hello World! Let's get started using AMP HTML together! HTML; $promise = $sparky->request('POST', 'templates', [ 'name' => $template_name, 'id' => $template_id, 'content' => [ 'from' => "from@$sending_domain", 'subject' => 'Your Subject', 'text' => $plain_text, 'html' => $html, 'amp_html' => $amp_html, ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/templates/delete_template.php ================================================ getenv('SPARKPOST_API_KEY')]); $template_id = "PHP-example-template"; $promise = $sparky->request('DELETE', "templates/$template_id"); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/templates/get_all_templates.php ================================================ getenv('SPARKPOST_API_KEY')]); $promise = $sparky->request('GET', 'templates'); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/templates/get_template.php ================================================ getenv('SPARKPOST_API_KEY')]); $template_id = "PHP-example-template"; $promise = $sparky->request('GET', "templates/$template_id?draft=true"); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/templates/preview_template.php ================================================ getenv('SPARKPOST_API_KEY')]); $template_id = "PHP-example-template"; $promise = $sparky->request('POST', "templates/$template_id/preview?draft=true", [ 'substitution_data' => [ 'some_key' => 'some_value', ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/templates/update_template.php ================================================ getenv('SPARKPOST_API_KEY')]); $template_id = "PHP-example-template"; $promise = $sparky->request('PUT', "templates/$template_id", [ 'options' => [ 'open_tracking' => true, ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/create_transmission.php ================================================ getenv('SPARKPOST_API_KEY')]); // put your own sending domain and test recipient address here $sending_domain = "steve2-test.trymsys.net"; $your_email = "bob@sink.sparkpostmail.com"; $promise = $sparky->transmissions->post([ 'content' => [ 'from' => [ 'name' => 'SparkPost Team', 'email' => "from@$sending_domain", ], 'subject' => 'First Mailing From PHP', 'html' => 'You just sent your very first mailing!
', 'text' => 'Congratulations, {{name}}! You just sent your very first mailing!', ], 'substitution_data' => ['name' => 'YOUR_FIRST_NAME'], 'recipients' => [ [ 'address' => [ 'name' => 'YOUR_NAME', 'email' => $your_email, ], ], ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/create_transmission_with_attachment.php ================================================ getenv('SPARKPOST_API_KEY')]); $filePath = dirname(__FILE__).'/'; $fileName = 'sparkpost.png'; $fileType = mime_content_type($filePath.$fileName); $fileData = base64_encode(file_get_contents($filePath.$fileName)); // put your own sending domain and test recipient address here $sending_domain = "steve2-test.trymsys.net"; $your_email = "bob@sink.sparkpostmail.com"; $promise = $sparky->transmissions->post([ 'content' => [ 'from' => [ 'name' => 'SparkPost Team', 'email' => "from@$sending_domain", ], 'subject' => 'Mailing With Attachment From PHP', 'html' => 'You just sent an email with an attachment!
', 'text' => 'Congratulations, {{name}}! You just sent an email with an attachment', 'attachments' => [ [ 'name' => $fileName, 'type' => $fileType, 'data' => $fileData, ], ], ], 'substitution_data' => ['name' => 'YOUR_FIRST_NAME'], 'recipients' => [ [ 'address' => [ 'name' => 'YOUR_NAME', 'email' => $your_email, ], ], ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/create_transmission_with_cc_and_bcc.php ================================================ getenv('SPARKPOST_API_KEY')]); // put your own sending domain and test recipient address here $sending_domain = "steve2-test.trymsys.net"; $your_email = "bob@sink.sparkpostmail.com"; $your_cc = "alice@sink.sparkpostmail.com"; $your_bcc = "charles@sink.sparkpostmail.com"; $promise = $sparky->transmissions->post([ 'content' => [ 'from' => [ 'name' => 'SparkPost Team', 'email' => "from@$sending_domain", ], 'subject' => 'Mailing With CC and BCC From PHP', 'html' => 'You just sent your very first mailing with CC and BCC recipients!
', 'text' => 'Congratulations, {{name}}! You just sent your very first mailing with CC and BCC recipients!', ], 'substitution_data' => ['name' => 'YOUR_FIRST_NAME'], 'recipients' => [ [ 'address' => [ 'name' => 'YOUR_NAME', 'email' => $your_email, ], ], ], 'cc' => [ [ 'address' => [ 'name' => 'ANOTHER_NAME', 'email' => $your_cc, ], ], ], 'bcc' => [ [ 'address' => [ 'name' => 'AND_ANOTHER_NAME', 'email' => $your_bcc, ], ], ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/create_transmission_with_recipient_list.php ================================================ getenv('SPARKPOST_API_KEY')]); // put your own sending domain and test recipient address here $sending_domain = "steve2-test.trymsys.net"; // The ID of a list in your SparkPost account $my_list = "mylist1"; $promise = $sparky->transmissions->post([ 'content' => [ 'from' => [ 'name' => 'SparkPost Team', 'email' => "from@$sending_domain", ], 'subject' => 'Mailing With Recipient List From PHP', 'html' => 'You just sent an email to everyone on your recipient list!
', 'text' => 'Congratulations, {{name}}! You just sent an email to everyone on your recipient list!', ], 'substitution_data' => ['name' => 'YOUR_FIRST_NAME'], 'recipients' => ['list_id' => $my_list], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/create_transmission_with_template.php ================================================ getenv('SPARKPOST_API_KEY')]); // put your own sending domain and test recipient address here $sending_domain = "steve2-test.trymsys.net"; $your_email = "bob@sink.sparkpostmail.com"; $template_id = "PHP-example-template"; $promise = $sparky->transmissions->post([ 'content' => ['template_id' => $template_id], 'substitution_data' => ['name' => 'YOUR_FIRST_NAME'], 'recipients' => [ [ 'address' => [ 'name' => 'YOUR_NAME', 'email' => $your_email, ], ], ], ]); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/delete_transmission.php ================================================ getenv('SPARKPOST_API_KEY')]); // Delete *scheduled* transmissions (only) by *campaign ID* (only) // See https://developers.sparkpost.com/api/transmissions/#transmissions-delete-delete-a-scheduled-transmission $promise = $sparky->transmissions->delete('?campaign_id=white_christmas'); try { $response = $promise->wait(); echo $response->getStatusCode()."\n"; print_r($response->getBody())."\n"; } catch (\Exception $e) { echo $e->getCode()."\n"; echo $e->getMessage()."\n"; } ================================================ FILE: examples/transmissions/get_all_transmissions.php ================================================ sparkpost = $sparkpost; $this->endpoint = $endpoint; } /** * Sends get request to API at the set endpoint. * * @see SparkPost->request() */ public function get($uri = '', $payload = [], $headers = []) { return $this->request('GET', $uri, $payload, $headers); } /** * Sends put request to API at the set endpoint. * * @see SparkPost->request() */ public function put($uri = '', $payload = [], $headers = []) { return $this->request('PUT', $uri, $payload, $headers); } /** * Sends post request to API at the set endpoint. * * @see SparkPost->request() */ public function post($payload = [], $headers = []) { return $this->request('POST', '', $payload, $headers); } /** * Sends delete request to API at the set endpoint. * * @see SparkPost->request() */ public function delete($uri = '', $payload = [], $headers = []) { return $this->request('DELETE', $uri, $payload, $headers); } /** * Sends requests to SparkPost object to the resource endpoint. * * @see SparkPost->request() * * @return SparkPostPromise or SparkPostResponse depending on sync or async request */ public function request($method = 'GET', $uri = '', $payload = [], $headers = []) { if (is_array($uri)) { $headers = $payload; $payload = $uri; $uri = ''; } $uri = $this->endpoint.'/'.$uri; return $this->sparkpost->request($method, $uri, $payload, $headers); } } ================================================ FILE: lib/SparkPost/SparkPost.php ================================================ 'api.sparkpost.com', 'protocol' => 'https', 'port' => 443, 'key' => '', 'version' => 'v1', 'async' => true, 'debug' => false, 'retries' => 0 ]; /** * @var Transmission Instance of Transmission class */ public $transmissions; /** * Sets up the SparkPost instance. * * @param HttpClient $httpClient - An httplug client or adapter * @param array $options - An array to overide default options or a string to be used as an API key */ public function __construct($httpClient, array $options) { $this->setOptions($options); $this->setHttpClient($httpClient); $this->setupEndpoints(); } /** * Sends either sync or async request based on async option. * * @param string $method * @param string $uri * @param array $payload - either used as the request body or url query params * @param array $headers * * @return SparkPostPromise|SparkPostResponse Promise or Response depending on sync or async request */ public function request($method = 'GET', $uri = '', $payload = [], $headers = []) { if ($this->options['async'] === true) { return $this->asyncRequest($method, $uri, $payload, $headers); } else { return $this->syncRequest($method, $uri, $payload, $headers); } } /** * Sends sync request to SparkPost API. * * @param string $method * @param string $uri * @param array $payload * @param array $headers * * @return SparkPostResponse * * @throws SparkPostException */ public function syncRequest($method = 'GET', $uri = '', $payload = [], $headers = []) { $requestValues = $this->buildRequestValues($method, $uri, $payload, $headers); $request = call_user_func_array(array($this, 'buildRequestInstance'), $requestValues); $retries = $this->options['retries']; try { if ($retries > 0) { $resp = $this->syncReqWithRetry($request, $retries); } else { $resp = $this->httpClient->sendRequest($request); } return new SparkPostResponse($resp, $this->ifDebug($requestValues)); } catch (\Exception $exception) { throw new SparkPostException($exception, $this->ifDebug($requestValues)); } } private function syncReqWithRetry($request, $retries) { $resp = $this->httpClient->sendRequest($request); $status = $resp->getStatusCode(); if ($status >= 500 && $status <= 599 && $retries > 0) { return $this->syncReqWithRetry($request, $retries-1); } return $resp; } /** * Sends async request to SparkPost API. * * @param string $method * @param string $uri * @param array $payload * @param array $headers * * @return SparkPostPromise */ public function asyncRequest($method = 'GET', $uri = '', $payload = [], $headers = []) { if ($this->httpClient instanceof HttpAsyncClient) { $requestValues = $this->buildRequestValues($method, $uri, $payload, $headers); $request = call_user_func_array(array($this, 'buildRequestInstance'), $requestValues); $retries = $this->options['retries']; if ($retries > 0) { return new SparkPostPromise($this->asyncReqWithRetry($request, $retries), $this->ifDebug($requestValues)); } else { return new SparkPostPromise($this->httpClient->sendAsyncRequest($request), $this->ifDebug($requestValues)); } } else { throw new \Exception('Your http client does not support asynchronous requests. Please use a different client or use synchronous requests.'); } } private function asyncReqWithRetry($request, $retries) { return $this->httpClient->sendAsyncRequest($request)->then(function($response) use ($request, $retries) { $status = $response->getStatusCode(); if ($status >= 500 && $status <= 599 && $retries > 0) { return $this->asyncReqWithRetry($request, $retries-1); } return $response; }); } /** * Builds request values from given params. * * @param string $method * @param string $uri * @param array $payload * @param array $headers * * @return array $requestValues */ public function buildRequestValues($method, $uri, $payload, $headers) { $method = trim(strtoupper($method)); if ($method === 'GET') { $params = $payload; $body = []; } else { $params = []; $body = $payload; } $url = $this->getUrl($uri, $params); $headers = $this->getHttpHeaders($headers); // old form-feed workaround now removed $body = json_encode($body); return [ 'method' => $method, 'url' => $url, 'headers' => $headers, 'body' => $body, ]; } /** * Build RequestInterface from given params. * * @param array $requestValues * * @return RequestInterface */ public function buildRequestInstance($method, $url, $headers, $body) { return $this->getMessageFactory()->createRequest($method, $url, $headers, $body); } /** * Build RequestInterface from given params. * * @param array $requestValues * * @return RequestInterface */ public function buildRequest($method, $uri, $payload, $headers) { $requestValues = $this->buildRequestValues($method, $uri, $payload, $headers); return call_user_func_array(array($this, 'buildRequestInstance'), $requestValues); } /** * Returns an array for the request headers. * * @param array $headers - any custom headers for the request * * @return array $headers - headers for the request */ public function getHttpHeaders($headers = []) { $constantHeaders = [ 'Authorization' => $this->options['key'], 'Content-Type' => 'application/json', 'User-Agent' => 'php-sparkpost/'.$this->version, ]; foreach ($constantHeaders as $key => $value) { $headers[$key] = $value; } return $headers; } /** * Builds the request url from the options and given params. * * @param string $path - the path in the url to hit * @param array $params - query parameters to be encoded into the url * * @return string $url - the url to send the desired request to */ public function getUrl($path, $params = []) { $options = $this->options; $paramsArray = []; foreach ($params as $key => $value) { if (is_array($value)) { $value = implode(',', $value); } array_push($paramsArray, $key.'='.$value); } $paramsString = implode('&', $paramsArray); return $options['protocol'].'://'.$options['host'].($options['port'] ? ':'.$options['port'] : '').'/api/'.$options['version'].'/'.$path.($paramsString ? '?'.$paramsString : ''); } /** * Sets $httpClient to be used for request. * * @param HttpClient|HttpAsyncClient $httpClient - the client to be used for request * * @return SparkPost */ public function setHttpClient($httpClient) { if (!($httpClient instanceof HttpAsyncClient || $httpClient instanceof HttpClient)) { throw new \LogicException(sprintf('Parameter to SparkPost::setHttpClient must be instance of "%s" or "%s"', HttpClient::class, HttpAsyncClient::class)); } $this->httpClient = $httpClient; return $this; } /** * Sets the options from the param and defaults for the SparkPost object. * * @param array $options - either an string API key or an array of options * * @return SparkPost */ public function setOptions($options) { // if the options map is a string we should assume that its an api key if (is_string($options)) { $options = ['key' => $options]; } // Validate API key because its required if (!isset($this->options['key']) && (!isset($options['key']) || !preg_match('/\S/', $options['key']))) { throw new \Exception('You must provide an API key'); } $this->options = isset($this->options) ? $this->options : self::$defaultOptions; // set options, overriding defaults foreach ($options as $option => $value) { if (key_exists($option, $this->options)) { $this->options[$option] = $value; } } return $this; } /** * Returns the given value if debugging, an empty instance otherwise. * * @param any $param * * @return any $param */ private function ifDebug($param) { return $this->options['debug'] ? $param : null; } /** * Sets up any endpoints to custom classes e.g. $this->transmissions. */ private function setupEndpoints() { $this->transmissions = new Transmission($this); } /** * @return RequestFactory */ private function getMessageFactory() { if (!$this->messageFactory) { $this->messageFactory = MessageFactoryDiscovery::find(); } return $this->messageFactory; } /** * @param RequestFactory $messageFactory * * @return SparkPost */ public function setMessageFactory(RequestFactory $messageFactory) { $this->messageFactory = $messageFactory; return $this; } } ================================================ FILE: lib/SparkPost/SparkPostException.php ================================================ request = $request; $message = $exception->getMessage(); $code = $exception->getCode(); if ($exception instanceof HttpException) { $message = $exception->getResponse()->getBody()->__toString(); $this->body = json_decode($message, true); $code = $exception->getResponse()->getStatusCode(); } parent::__construct($message, $code, $exception->getPrevious()); } /** * Returns the request values sent. * * @return array $request */ public function getRequest() { return $this->request; } /** * Returns the body. * * @return array $body - the json decoded body from the http response */ public function getBody() { return $this->body; } } ================================================ FILE: lib/SparkPost/SparkPostPromise.php ================================================ promise = $promise; $this->request = $request; } /** * Hand off the response functions to the original promise and return a custom response or exception. * * @param callable $onFulfilled - function to be called if the promise is fulfilled * @param callable $onRejected - function to be called if the promise is rejected */ public function then(callable $onFulfilled = null, callable $onRejected = null) { $request = $this->request; return $this->promise->then(function ($response) use ($onFulfilled, $request) { if (isset($onFulfilled)) { $onFulfilled(new SparkPostResponse($response, $request)); } }, function ($exception) use ($onRejected, $request) { if (isset($onRejected)) { $onRejected(new SparkPostException($exception, $request)); } }); } /** * Hand back the state. * * @return $state - returns the state of the promise */ public function getState() { return $this->promise->getState(); } /** * Wraps the wait function and returns a custom response or throws a custom exception. * * @param bool $unwrap * * @return SparkPostResponse * * @throws SparkPostException */ public function wait($unwrap = true) { try { $response = $this->promise->wait($unwrap); return $response ? new SparkPostResponse($response, $this->request) : $response; } catch (\Exception $exception) { throw new SparkPostException($exception, $this->request); } } } ================================================ FILE: lib/SparkPost/SparkPostResponse.php ================================================ response = $response; $this->request = $request; } /** * Returns the request values sent. * * @return array $request */ public function getRequest() { return $this->request; } /** * Returns the body. * * @return array $body - the json decoded body from the http response */ public function getBody() { $body = $this->response->getBody(); $body_string = $body->__toString(); $json = json_decode($body_string, true); return $json; } /** * pass these down to the response given in the constructor. */ public function getProtocolVersion() { return $this->response->getProtocolVersion(); } public function withProtocolVersion($version) { return $this->response->withProtocolVersion($version); } public function getHeaders() { return $this->response->getHeaders(); } public function hasHeader($name) { return $this->response->hasHeader($name); } public function getHeader($name) { return $this->response->getHeader($name); } public function getHeaderLine($name) { return $this->response->getHeaderLine($name); } public function withHeader($name, $value) { return $this->response->withHeader($name, $value); } public function withAddedHeader($name, $value) { return $this->response->withAddedHeader($name, $value); } public function withoutHeader($name) { return $this->response->withoutHeader($name); } public function withBody(StreamInterface $body) { return $this->response->withBody($body); } public function getStatusCode() { return $this->response->getStatusCode(); } public function withStatus($code, $reasonPhrase = '') { return $this->response->withStatus($code, $reasonPhrase); } public function getReasonPhrase() { return $this->response->getReasonPhrase(); } } ================================================ FILE: lib/SparkPost/Transmission.php ================================================ formatPayload($payload); } return parent::post($payload, $headers); } /** * Runs the given payload through the formatting functions. * * @param array $payload - the request body * * @return array - the modified request body */ public function formatPayload($payload) { $payload = $this->formatBlindCarbonCopy($payload); //Fixes BCCs into payload $payload = $this->formatCarbonCopy($payload); //Fixes CCs into payload $payload = $this->formatShorthandRecipients($payload); //Fixes shorthand recipients format return $payload; } /** * Formats bcc list into recipients list. * * @param array $payload - the request body * * @return array - the modified request body */ private function formatBlindCarbonCopy($payload) { //If there's a list of BCC recipients, move them into the correct format if (isset($payload['bcc'])) { $payload = $this->addListToRecipients($payload, 'bcc'); } return $payload; } /** * Formats cc list into recipients list and adds the CC header to the content. * * @param array $payload - the request body * * @return array - the modified request body */ private function formatCarbonCopy($payload) { if (isset($payload['cc'])) { $ccAddresses = []; for ($i = 0; $i < count($payload['cc']); ++$i) { array_push($ccAddresses, $this->toAddressString($payload['cc'][$i]['address'])); } // set up the content headers as either what it was before or an empty array $payload['content']['headers'] = isset($payload['content']['headers']) ? $payload['content']['headers'] : []; // add cc header $payload['content']['headers']['CC'] = implode(',', $ccAddresses); $payload = $this->addListToRecipients($payload, 'cc'); } return $payload; } /** * Formats all recipients into the long form of [ "name" => "John", "email" => "john@exmmple.com" ]. * * @param array $payload - the request body * * @return array - the modified request body */ private function formatShorthandRecipients($payload) { if (isset($payload['content']['from'])) { $payload['content']['from'] = $this->toAddressObject($payload['content']['from']); } for ($i = 0; $i < count($payload['recipients']); ++$i) { $payload['recipients'][$i]['address'] = $this->toAddressObject($payload['recipients'][$i]['address']); } return $payload; } /** * Loops through the given listName in the payload and adds all the recipients to the recipients list after removing their names. * * @param array $payload - the request body * @param array $listName - the name of the array in the payload to be moved to the recipients list * * @return array - the modified request body */ private function addListToRecipients($payload, $listName) { $originalAddress = $this->toAddressString($payload['recipients'][0]['address']); foreach ($payload[$listName] as $recipient) { $recipient['address'] = $this->toAddressObject($recipient['address']); $recipient['address']['header_to'] = $originalAddress; // remove name from address - name is only put in the header for cc and not at all for bcc if (isset($recipient['address']['name'])) { unset($recipient['address']['name']); } array_push($payload['recipients'], $recipient); } //Delete the original object from the payload. unset($payload[$listName]); return $payload; } /** * Takes the shorthand form of an email address and converts it to the long form. * * @param $address - the shorthand form of an email address "Name