Skip to content

Commit a403fab

Browse files
avigoldmanavigoldman
committed
Merge branch '2.x'
2 parents 55d1bdc + f94881b commit a403fab

File tree

3 files changed

+107
-45
lines changed

3 files changed

+107
-45
lines changed

‎README.md

+102-43
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ The official PHP library for using [the SparkPost REST API](https://developers.s
1212
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.
1313

1414
## Installation
15+
**Please note: The composer package `sparkpost/php-sparkpost` has been changed to `sparkpost/sparkpost` starting with version 2.0.**
16+
1517
The recommended way to install the SparkPost PHP Library is through composer.
1618

1719
```
@@ -22,7 +24,7 @@ curl -sS https://getcomposer.org/installer | php
2224
Next, run the Composer command to install the SparkPost PHP Library:
2325

2426
```
25-
composer require sparkpost/php-sparkpost
27+
composer require sparkpost/sparkpost
2628
```
2729

2830
After installing, you need to require Composer's autoloader:
@@ -36,13 +38,15 @@ use SparkPost\SparkPost;
3638

3739
Because of dependency collision, we have opted to use a request adapter rather than
3840
requiring a request library. This means that your application will need to pass in
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.
41+
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
42+
need to require one and create a client from it and pass it along. The example below uses the GuzzleHttp Client Library.
4143

42-
An Adapter can be setup like so:
44+
An Client can be setup like so:
4345

4446
```php
4547
<?php
48+
require 'vendor/autoload.php';
49+
4650
use SparkPost\SparkPost;
4751
use GuzzleHttp\Client;
4852
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
@@ -81,10 +85,11 @@ $sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
8185
* Required: No
8286
* Type: `String`
8387
* Default: `v1`
84-
* `options.timeout`
88+
* `options.async`
8589
* Required: No
86-
* Type: `Number`
87-
* Default: `10`
90+
* Type: `Boolean`
91+
* Default: `true`
92+
* `async` defines if the `request` function sends an asynchronous or synchronous request. If your client does not support async requests set this to `false`
8893

8994

9095
## Methods
@@ -106,6 +111,12 @@ $sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
106111
* Type: `Array`
107112
* Custom headers to be sent with the request.
108113

114+
### syncRequest(method, uri [, payload [, headers]])
115+
Sends a synchronous request to the SparkPost API and returns a `SparkPostResponse`
116+
117+
### asyncRequest(method, uri [, payload [, headers]])
118+
Sends an asynchronous request to the SparkPost API and returns a `SparkPostPromise`
119+
109120
### setHttpClient(httpClient)
110121
* `httpClient`
111122
* Required: Yes
@@ -115,7 +126,7 @@ $sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
115126
* `options`
116127
* Required: Yes
117128
* Type: `Array`
118-
* See initialization
129+
* See constructor
119130

120131

121132
## Endpoints
@@ -141,38 +152,60 @@ $sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
141152
### Send An Email Using The Transmissions Endpoint
142153
```php
143154
<?php
155+
require 'vendor/autoload.php';
156+
144157
use SparkPost\SparkPost;
145158
use GuzzleHttp\Client;
146159
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
147160

148161
$httpClient = new GuzzleAdapter(new Client());
149162
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
150163

164+
$sparky = new SparkPost($httpClient, $options);
151165
$promise = $sparky->transmissions->post([
152166
'content' => [
153-
'from'=> [
154-
'name' => 'Sparkpost Team',
155-
'email' => '[email protected]'
167+
'from' => [
168+
'name' => 'SparkPost Team',
169+
'email' => '[email protected]',
156170
],
157-
'subject'=>'First Mailing From PHP',
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!'
171+
'subject' => 'First Mailing From PHP',
172+
'html' => '<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
173+
'text' => 'Congratulations, {{name}}!! You just sent your very first mailing!',
160174
],
161-
'substitution_data'=> ['name'=>'YOUR_FIRST_NAME'],
162-
'recipients'=> [
163-
[ 'address' => '<YOUR_EMAIL_ADDRESS>' ]
175+
'substitution_data' => ['name' => 'YOUR_FIRST_NAME'],
176+
'recipients' => [
177+
[
178+
'address' => [
179+
'name' => 'YOUR_NAME',
180+
'email' => 'YOUR_EMAIL',
181+
],
182+
],
183+
],
184+
'cc' => [
185+
[
186+
'address' => [
187+
'name' => 'ANOTHER_NAME',
188+
'email' => 'ANOTHER_EMAIL',
189+
],
190+
],
191+
],
192+
'bcc' => [
193+
[
194+
'address' => [
195+
'name' => 'AND_ANOTHER_NAME',
196+
'email' => 'AND_ANOTHER_EMAIL',
197+
],
198+
],
164199
],
165-
'bcc' => [
166-
['address' => '<ANOTHER_EMAIL_ADDRESS>' ]
167-
]
168200
]);
169-
?>
170201
```
171202

172203
### 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.
204+
We provide a base request function to access any of our API resources.
174205
```php
175206
<?php
207+
require 'vendor/autoload.php';
208+
176209
use SparkPost\SparkPost;
177210
use GuzzleHttp\Client;
178211
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
@@ -181,58 +214,84 @@ $httpClient = new GuzzleAdapter(new Client());
181214
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
182215

183216
$promise = $sparky->request('GET', 'metrics/ip-pools', [
184-
'from' => '2015-12-01T08:00',
185-
'to' => '2014-12-01T09:00',
217+
'from' => '2014-12-01T09:00',
218+
'to' => '2015-12-01T08:00',
186219
'timezone' => 'America/New_York',
187-
'limit' => '5'
220+
'limit' => '5',
188221
]);
189-
?>
190222
```
191223

192224

193225
## 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.
226+
The API calls either return a `SparkPostPromise` or `SparkPostResponse` depending on if `async` is `true` or `false`
195227

228+
### Synchronous
229+
```php
230+
$sparky->setOptions(['async' => false]);
231+
try {
232+
$response = $sparky->transmissions->get();
233+
234+
echo $response->getStatusCode()."\n";
235+
print_r($response->getBody())."\n";
236+
}
237+
catch (\Exception $e) {
238+
echo $e->getCode()."\n";
239+
echo $e->getMessage()."\n";
240+
}
241+
```
242+
243+
### Asynchronous
244+
Asynchronous an be handled in two ways: by passing callbacks or waiting for the promise to be fulfilled. Waiting acts like synchronous request.
196245
##### Wait (Synchronous)
197246
```php
198-
<?php
247+
$promise = $sparky->transmissions->get();
248+
199249
try {
200250
$response = $promise->wait();
201-
echo $response->getStatusCode();
202-
echo $response->getBody();
203-
} catch (Exception $e) {
204-
echo $e->getCode();
205-
echo $e->getMessage();
251+
echo $response->getStatusCode()."\n";
252+
print_r($response->getBody())."\n";
253+
} catch (\Exception $e) {
254+
echo $e->getCode()."\n";
255+
echo $e->getMessage()."\n";
206256
}
207-
?>
257+
258+
echo "I will print out after the promise is fulfilled";
208259
```
209260

210261
##### Then (Asynchronous)
211262
```php
212-
<?php
263+
$promise = $sparky->transmissions->get();
264+
213265
$promise->then(
214266
// Success callback
215267
function ($response) {
216-
echo $response->getStatusCode();
217-
echo $response->getBody();
268+
echo $response->getStatusCode()."\n";
269+
print_r($response->getBody())."\n";
218270
},
219271
// Failure callback
220272
function (Exception $e) {
221-
echo $e->getCode();
222-
echo $e->getMessage();
273+
echo $e->getCode()."\n";
274+
echo $e->getMessage()."\n";
223275
}
224276
);
225-
?>
277+
278+
echo "I will print out before the promise is fulfilled";
226279
```
227280

228281
## Handling Exceptions
229-
The promise will throw an exception if the server returns a status code of `400` or higher.
282+
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.
230283

231-
### Exception
284+
### SparkPostException
232285
* **getCode()**
233286
* Returns the response status code of `400` or higher
234287
* **getMessage()**
235-
* Returns the body of response as an `Array`
288+
* Returns the exception message
289+
* **getBody()**
290+
* If there is a response body it returns it as an `Array`. Otherwise it returns `null`.
291+
292+
293+
### Contributing
294+
See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md).rray`
236295

237296

238297
### Contributing

‎composer.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
{
2-
"name": "sparkpost/php-sparkpost",
1+
{
2+
"name": "sparkpost/sparkpost",
33
"description": "Client library for interfacing with the SparkPost API.",
44
"license": "Apache 2.0",
55
"authors": [

‎examples/example-options.json

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"key":"YOUR_API_KEY"
3+
}

0 commit comments

Comments
 (0)