Skip to content

Commit 55d1bdc

Browse files
avigoldmanavigoldman
committed
merged in 2x
2 parents 1b61a81 + 12f363b commit 55d1bdc

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1866
-3257
lines changed

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
.settings
44
.buildpath
55
test/output/
6-
examples/example-config.json
6+
examples/example-options.json
77
.idea
88
/composer.phar
9+
test.php

‎AUTHORS.md

+2
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,5 @@ php-sparkpost is maintained by Message Systems.
1313
* Chris Wilson, [@yepher](https://github.com/yepher)
1414
* Maxim Dzhuliy, [@max-si-m](https://github.com/max-si-m)
1515
* [@chandon](https://github.com/chandon)
16+
* Avi Goldman, [@avrahamgoldman](https://github.com/avrahamgoldman)
17+
* Vincent Song, [@vwsong](https://github.com/vwsong)

‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Add composer install directory to $PATH `~/.composer/vendor/bin/`
2626

2727
#### Install PHPUnit for Testing
2828
```
29-
composer global require "phpunit/phpunit=4.3.*"
29+
composer global require "phpunit/phpunit=4.8.*"
3030
```
3131

3232
We recommend increasing PHP’s memory limit, by default it uses 128MB. We ran into some issues during local development without doing so. You can do this by editing your php.ini file and modifying `memory_limit`. We set ours to `memory_limit = 1024M`.

‎README.md

+181-86
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,7 @@
77
[![Travis CI](https://travis-ci.org/SparkPost/php-sparkpost.svg?branch=master)](https://travis-ci.org/SparkPost/php-sparkpost)
88
[![Coverage Status](https://coveralls.io/repos/SparkPost/php-sparkpost/badge.svg?branch=master&service=github)](https://coveralls.io/github/SparkPost/php-sparkpost?branch=master) [![Slack Status](http://slack.sparkpost.com/badge.svg)](http://slack.sparkpost.com)
99

10-
The official PHP library for using [the SparkPost REST API](https://developers.sparkpost.com).
11-
12-
**Note: We understand that the ivory-http-adapter we use in this library is deprecated in favor of httplug. We use Ivory internally to make it simple for you to use whatever HTTP library you want. The deprecation won't affect or limit our ongoing support of this PHP library.**
10+
The official PHP library for using [the SparkPost REST API](https://developers.sparkpost.com/api/).
1311

1412
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.
1513

@@ -38,107 +36,204 @@ use SparkPost\SparkPost;
3836

3937
Because of dependency collision, we have opted to use a request adapter rather than
4038
requiring a request library. This means that your application will need to pass in
41-
a request adapter to the constructor of the SparkPost Library. We use the [Ivory HTTP Adapter] (https://github.com/egeloen/ivory-http-adapter) in SparkPost. Please visit their repo
42-
for a list of supported adapters. If you don't currently use a request library, you will
43-
need to require one and create an adapter from it and pass it along. The example below uses the
44-
GuzzleHttp Client Library.
39+
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 adapters. If you don't currently use a request library, you will
40+
need to require one and create an adapter from it and pass it along. The example below uses the GuzzleHttp Client Library.
4541

4642
An Adapter can be setup like so:
4743

4844
```php
45+
<?php
4946
use SparkPost\SparkPost;
5047
use GuzzleHttp\Client;
51-
use Ivory\HttpAdapter\Guzzle6HttpAdapter;
48+
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
5249

53-
$httpAdapter = new Guzzle6HttpAdapter(new Client());
54-
$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR API KEY']);
50+
$httpClient = new GuzzleAdapter(new Client());
51+
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
52+
?>
5553
```
5654

57-
## Getting Started: Your First Mailing
58-
For this example to work as is, [Guzzle 6 will need to be installed](http://docs.guzzlephp.org/en/latest/overview.html#installation). Otherwise another adapter can be used for your specific setup. See "Setting up a Request Adapter" above.
59-
55+
## Initialization
56+
#### new Sparkpost(httpClient, options)
57+
* `httpClient`
58+
* Required: Yes
59+
* HTTP client or adapter supported by HTTPlug
60+
* `options`
61+
* Required: Yes
62+
* Type: `String` or `Array`
63+
* A valid Sparkpost API key or an array of options
64+
* `options.key`
65+
* Required: Yes
66+
* Type: `String`
67+
* A valid Sparkpost API key
68+
* `options.host`
69+
* Required: No
70+
* Type: `String`
71+
* Default: `api.sparkpost.com`
72+
* `options.protocol`
73+
* Required: No
74+
* Type: `String`
75+
* Default: `https`
76+
* `options.port`
77+
* Required: No
78+
* Type: `Number`
79+
* Default: 443
80+
* `options.version`
81+
* Required: No
82+
* Type: `String`
83+
* Default: `v1`
84+
* `options.timeout`
85+
* Required: No
86+
* Type: `Number`
87+
* Default: `10`
88+
89+
90+
## Methods
91+
### request(method, uri [, payload [, headers]])
92+
* `method`
93+
* Required: Yes
94+
* Type: `String`
95+
* HTTP method for request
96+
* `uri`
97+
* Required: Yes
98+
* Type: `String`
99+
* The URI to recieve the request
100+
* `payload`
101+
* Required: No
102+
* Type: `Array`
103+
* 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.
104+
* `headers`
105+
* Required: No
106+
* Type: `Array`
107+
* Custom headers to be sent with the request.
108+
109+
### setHttpClient(httpClient)
110+
* `httpClient`
111+
* Required: Yes
112+
* HTTP client or adapter supported by HTTPlug
113+
114+
### setOptions(options)
115+
* `options`
116+
* Required: Yes
117+
* Type: `Array`
118+
* See initialization
119+
120+
121+
## Endpoints
122+
### transmissions
123+
* **get([transmissionID] [, payload])**
124+
* `transmissionID` - see `uri` request options
125+
* `payload` - see request options
126+
* **post(payload)**
127+
* `payload` - see request options
128+
* `payload.cc`
129+
* Required: No
130+
* Type: `Array`
131+
* Recipients to recieve a carbon copy of the transmission
132+
* `payload.bcc`
133+
* Required: No
134+
* Type: `Array`
135+
* Recipients to descreetly recieve a carbon copy of the transmission
136+
* **delete(transmissionID)**
137+
* `transmissionID` - see `uri` request options
138+
139+
## Examples
140+
141+
### Send An Email Using The Transmissions Endpoint
60142
```php
61-
require 'vendor/autoload.php';
62-
143+
<?php
63144
use SparkPost\SparkPost;
64145
use GuzzleHttp\Client;
65-
use Ivory\HttpAdapter\Guzzle6HttpAdapter;
146+
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
66147

67-
$httpAdapter = new Guzzle6HttpAdapter(new Client());
68-
$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR API KEY']);
148+
$httpClient = new GuzzleAdapter(new Client());
149+
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
69150

70-
try {
71-
// Build your email and send it!
72-
$results = $sparky->transmission->send([
73-
'from'=>[
74-
'name' => 'From Envelope',
75-
'email' => '[email protected]>'
151+
$promise = $sparky->transmissions->post([
152+
'content' => [
153+
'from'=> [
154+
'name' => 'Sparkpost Team',
155+
'email' => '[email protected]'
76156
],
77-
'html'=>'<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
78-
'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!',
79-
'substitutionData'=>['name'=>'YOUR FIRST NAME'],
80157
'subject'=>'First Mailing From PHP',
81-
'recipients'=>[
82-
[
83-
'address'=>[
84-
'name'=>'YOUR FULL NAME',
85-
'email'=>'YOUR EMAIL ADDRESS'
86-
]
87-
]
88-
]
89-
]);
90-
echo 'Woohoo! You just sent your first mailing!';
91-
} catch (\Exception $err) {
92-
echo 'Whoops! Something went wrong';
93-
var_dump($err);
158+
'html'=>'<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
159+
'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!'
160+
],
161+
'substitution_data'=> ['name'=>'YOUR_FIRST_NAME'],
162+
'recipients'=> [
163+
[ 'address' => '<YOUR_EMAIL_ADDRESS>' ]
164+
],
165+
'bcc' => [
166+
['address' => '<ANOTHER_EMAIL_ADDRESS>' ]
167+
]
168+
]);
169+
?>
170+
```
171+
172+
### Send An API Call Using The Base Request Function
173+
We may not wrap every resource available in the SparkPost Client Library, for example the PHP Client Library does not wrap the Metrics resource. To allow you to use the full power of our API we created the `request` function which allows you to access the unwrapped resources.
174+
```php
175+
<?php
176+
use SparkPost\SparkPost;
177+
use GuzzleHttp\Client;
178+
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
179+
180+
$httpClient = new GuzzleAdapter(new Client());
181+
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
182+
183+
$promise = $sparky->request('GET', 'metrics/ip-pools', [
184+
'from' => '2015-12-01T08:00',
185+
'to' => '2014-12-01T09:00',
186+
'timezone' => 'America/New_York',
187+
'limit' => '5'
188+
]);
189+
?>
190+
```
191+
192+
193+
## Handling Responses
194+
The all API calls return a promise. You can wait for the promise to be fulfilled or you can handle it asynchronously.
195+
196+
##### Wait (Synchronous)
197+
```php
198+
<?php
199+
try {
200+
$response = $promise->wait();
201+
echo $response->getStatusCode();
202+
echo $response->getBody();
203+
} catch (Exception $e) {
204+
echo $e->getCode();
205+
echo $e->getMessage();
94206
}
207+
?>
95208
```
96209

97-
## Learn More
98-
* For more detailed examples, check our examples:
99-
* [Transmissions](https://github.com/SparkPost/php-sparkpost/tree/master/examples/transmission)
100-
* Read our REST API documentation - <http://www.sparkpost.com/docs/introduction>
101-
102-
## Field Descriptions
103-
### Transmissions
104-
| Field Name | Required? | Description | Data Type |
105-
| ------------ | ----------- | ------------- | ----------- |
106-
| attachments | no | Field for attaching files - see Attachment Attributes in the [Transmssions API docs](https://developers.sparkpost.com/api/#/reference/transmissions) | Array of Objects |
107-
| campaign | no | Field for assigning a given transmission to a specific campaign, which is a logical container for similar transmissions | String |
108-
| customHeaders | no | Field for specifying additional headers to be applied to a given transmission (other than Subject, From, To, and Reply-To) | Object (Simple) |
109-
| description | no | Field for describing what this transmission is for the user | String |
110-
| from | yes** | Field for setting the from line of a given transmission | Object |
111-
| html | yes** | Field for setting the HTML content of a given transmission | String |
112-
| inlineCss | no | Field for enabling/disabling CSS inlining | Boolean |
113-
| inlineImages | no | Field for providing inline images - see Inline Image Attributes in the [Transmssions API docs](https://developers.sparkpost.com/api/#/reference/transmissions) | Array of Objects |
114-
| metadata | no | Field for adding arbitrary key/value pairs which will be included in open/click tracking | Object (Simple) |
115-
| recipientList | no** | Field for specifying a stored recipient list ID to be used for a given transmission | String |
116-
| recipients | yes** | Field for specifying who a given transmission should be sent to | Array of Objects |
117-
| replyTo | no | Field for specifying the email address that should be used when a recipient hits the reply button | String |
118-
| rfc822 | no** | Field for setting the RFC-822 encoded content of a given transmission | String |
119-
| subject | yes | Field for setting the subject line of a given transmission | String |
120-
| substitutionData | no | Field for adding transmission level substitution data, which can be used in a variety of fields and in content | Object (Complex) |
121-
| template | no** | Field for specifying the Template ID of a stored template to be used when sending a given transmission | String |
122-
| text | yes** | Field for setting the Plain Text content of a given transmission | String |
123-
| trackClicks | no | Field for enabling/disabling transmission level click tracking (default: true) | Boolean |
124-
| trackOpens | no | Field for enabling/disabling transmission level open tracking (default: true) | Boolean |
125-
| transactional | no | Field for marking email as transactional (default: false) | Boolean |
126-
| useDraftTemplate | no | Field for allowing the sending of a transmission using a draft of a stored template (default: false) | Boolean |
127-
128-
** - If using inline content then html or text are required. If using RFC-822 Inline Content, then rfc822 is required. If using a stored recipient list, then recipientList is required. If using a stored template, then template is required but from is not as the values from the template will be used.
129-
130-
## Tips and Tricks
131-
### General
132-
* You _must_ provide at least an API key when instantiating the SparkPost Library - `[ 'key'=>'184ac5480cfdd2bb2859e4476d2e5b1d2bad079bf' ]`
133-
* The library's features are namespaced under the various SparkPost API names.
134-
135-
### Transmissions
136-
* If you specify a stored recipient list and inline recipients in a Transmission, you will receive an error.
137-
* If you specify HTML and/or Plain Text content and then provide RFC-822 encoded content, you will receive an error.
138-
* RFC-822 content is not valid with any other content type.
139-
* If you specify a stored template and also provide inline content via `html` or `text`, you will receive an error.
140-
* By default, open and click tracking are enabled for a transmission.
141-
* By default, a transmission will use the published version of a stored template.
210+
##### Then (Asynchronous)
211+
```php
212+
<?php
213+
$promise->then(
214+
// Success callback
215+
function ($response) {
216+
echo $response->getStatusCode();
217+
echo $response->getBody();
218+
},
219+
// Failure callback
220+
function (Exception $e) {
221+
echo $e->getCode();
222+
echo $e->getMessage();
223+
}
224+
);
225+
?>
226+
```
227+
228+
## Handling Exceptions
229+
The promise will throw an exception if the server returns a status code of `400` or higher.
230+
231+
### Exception
232+
* **getCode()**
233+
* Returns the response status code of `400` or higher
234+
* **getMessage()**
235+
* Returns the body of response as an `Array`
236+
142237

143238
### Contributing
144-
See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md).
239+
See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md).

‎composer.json

+6-6
Original file line numberDiff line numberDiff line change
@@ -9,26 +9,26 @@
99
],
1010
"minimum-stability": "stable",
1111
"scripts": {
12-
"post-install-cmd": "if [ ! -f 'examples/example-config.json' ]; then echo '{\n\t\"api-key\":\"Your API Key\"\n}' >> examples/example-config.json; fi",
13-
"post-update-cmd": "if [ ! -f 'examples/example-config.json' ]; then echo '{\n\t\"api-key\":\"Your API Key\"\n}' >> examples/example-config.json; fi",
12+
"post-install-cmd": "if [ ! -f 'examples/example-options.json' ]; then echo '{\n\t\"key\":\"YOUR_API_KEY\"\n}' >> examples/example-options.json; fi",
13+
"post-update-cmd": "if [ ! -f 'examples/example-options.json' ]; then echo '{\n\t\"key\":\"YOUR_API_KEY\"\n}' >> examples/example-options.json; fi",
1414
"test": "phpunit ./test/unit/",
1515
"fix-style": "php-cs-fixer fix ."
1616
},
1717
"require": {
1818
"php": ">=5.5.0",
19-
"egeloen/http-adapter": "*"
19+
"php-http/client-implementation": "^1.0",
20+
"guzzlehttp/psr7": "1.3.*"
2021
},
2122
"require-dev": {
22-
"phpunit/phpunit": "4.3.*",
2323
"guzzlehttp/guzzle": "6.*",
24+
"php-http/guzzle6-adapter": "*",
25+
"php-http/message": "*",
2426
"mockery/mockery": "^0.9.4",
25-
"satooshi/php-coveralls": "dev-master",
2627
"fabpot/php-cs-fixer": "^1.11"
2728
},
2829
"autoload": {
2930
"psr-4": {
3031
"SparkPost\\": "lib/SparkPost/",
31-
"SparkPost\\SendGridCompatibility\\": "lib/SendGridCompatibility/",
3232
"SparkPost\\Test\\TestUtils\\": "test/unit/TestUtils/"
3333
}
3434
}

0 commit comments

Comments
 (0)