Skip to content

Commit

Permalink
merged in 2x
Browse files Browse the repository at this point in the history
  • Loading branch information
@avigoldman
avigoldman committed Jun 24, 2016
2 parents 1b61a81 + 12f363b commit 55d1bdc
Show file tree
Hide file tree
Showing 42 changed files with 1,866 additions and 3,257 deletions.
3 changes: 2 additions & 1 deletion .gitignore
View file
Expand Up @@ -3,6 +3,7 @@
.settings
.buildpath
test/output/
examples/example-config.json
examples/example-options.json
.idea
/composer.phar
test.php
2 changes: 2 additions & 0 deletions AUTHORS.md
View file
Expand Up @@ -13,3 +13,5 @@ php-sparkpost is maintained by Message Systems.
* Chris Wilson, [@yepher](https://github.com/yepher)
* Maxim Dzhuliy, [@max-si-m](https://github.com/max-si-m)
* [@chandon](https://github.com/chandon)
* Avi Goldman, [@avrahamgoldman](https://github.com/avrahamgoldman)
* Vincent Song, [@vwsong](https://github.com/vwsong)
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Expand Up @@ -26,7 +26,7 @@ Add composer install directory to $PATH `~/.composer/vendor/bin/`

#### Install PHPUnit for Testing
```
composer global require "phpunit/phpunit=4.3.*"
composer global require "phpunit/phpunit=4.8.*"
```

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`.
Expand Down
267 changes: 181 additions & 86 deletions README.md
View file
Expand Up @@ -7,9 +7,7 @@
[![Travis CI](https://travis-ci.org/SparkPost/php-sparkpost.svg?branch=master)](https://travis-ci.org/SparkPost/php-sparkpost)
[![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)

The official PHP library for using [the SparkPost REST API](https://developers.sparkpost.com).

**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.**
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.

Expand Down Expand Up @@ -38,107 +36,204 @@ use SparkPost\SparkPost;

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 [Ivory HTTP Adapter] (https://github.com/egeloen/ivory-http-adapter) in SparkPost. Please visit their repo
for a list of supported adapters. If you don't currently use a request library, you will
need to require one and create an adapter from it and pass it along. The example below uses the
GuzzleHttp Client Library.
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
need to require one and create an adapter from it and pass it along. The example below uses the GuzzleHttp Client Library.

An Adapter can be setup like so:

```php
<?php
use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Ivory\HttpAdapter\Guzzle6HttpAdapter;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpAdapter = new Guzzle6HttpAdapter(new Client());
$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR API KEY']);
$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
?>
```

## Getting Started: Your First Mailing
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.

## 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.timeout`
* Required: No
* Type: `Number`
* Default: `10`


## Methods
### request(method, uri [, payload [, headers]])
* `method`
* Required: Yes
* Type: `String`
* HTTP method for request
* `uri`
* Required: Yes
* Type: `String`
* The URI to recieve 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.

### setHttpClient(httpClient)
* `httpClient`
* Required: Yes
* HTTP client or adapter supported by HTTPlug

### setOptions(options)
* `options`
* Required: Yes
* Type: `Array`
* See initialization


## Endpoints
### transmissions
* **get([transmissionID] [, payload])**
* `transmissionID` - see `uri` request options
* `payload` - see request options
* **post(payload)**
* `payload` - see request options
* `payload.cc`
* Required: No
* Type: `Array`
* Recipients to recieve a carbon copy of the transmission
* `payload.bcc`
* Required: No
* Type: `Array`
* Recipients to descreetly recieve a carbon copy of the transmission
* **delete(transmissionID)**
* `transmissionID` - see `uri` request options

## Examples

### Send An Email Using The Transmissions Endpoint
```php
require 'vendor/autoload.php';

<?php
use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Ivory\HttpAdapter\Guzzle6HttpAdapter;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

$httpAdapter = new Guzzle6HttpAdapter(new Client());
$sparky = new SparkPost($httpAdapter, ['key'=>'YOUR API KEY']);
$httpClient = new GuzzleAdapter(new Client());
$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);

try {
// Build your email and send it!
$results = $sparky->transmission->send([
'from'=>[
'name' => 'From Envelope',
'email' => 'from@sparkpostbox.com>'
$promise = $sparky->transmissions->post([
'content' => [
'from'=> [
'name' => 'Sparkpost Team',
'email' => 'from@sparkpostbox.com'
],
'html'=>'<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
'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);
'html'=>'<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!'
],
'substitution_data'=> ['name'=>'YOUR_FIRST_NAME'],
'recipients'=> [
[ 'address' => '<YOUR_EMAIL_ADDRESS>' ]
],
'bcc' => [
['address' => '<ANOTHER_EMAIL_ADDRESS>' ]
]
]);
?>
```

### Send An API Call Using The Base Request Function
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.
```php
<?php
use SparkPost\SparkPost;
use GuzzleHttp\Client;
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;

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

$promise = $sparky->request('GET', 'metrics/ip-pools', [
'from' => '2015-12-01T08:00',
'to' => '2014-12-01T09:00',
'timezone' => 'America/New_York',
'limit' => '5'
]);
?>
```


## Handling Responses
The all API calls return a promise. You can wait for the promise to be fulfilled or you can handle it asynchronously.

##### Wait (Synchronous)
```php
<?php
try {
$response = $promise->wait();
echo $response->getStatusCode();
echo $response->getBody();
} catch (Exception $e) {
echo $e->getCode();
echo $e->getMessage();
}
?>
```

## Learn More
* For more detailed examples, check our examples:
* [Transmissions](https://github.com/SparkPost/php-sparkpost/tree/master/examples/transmission)
* Read our REST API documentation - <http://www.sparkpost.com/docs/introduction>

## Field Descriptions
### Transmissions
| Field Name | Required? | Description | Data Type |
| ------------ | ----------- | ------------- | ----------- |
| attachments | no | Field for attaching files - see Attachment Attributes in the [Transmssions API docs](https://developers.sparkpost.com/api/#/reference/transmissions) | Array of Objects |
| campaign | no | Field for assigning a given transmission to a specific campaign, which is a logical container for similar transmissions | String |
| customHeaders | no | Field for specifying additional headers to be applied to a given transmission (other than Subject, From, To, and Reply-To) | Object (Simple) |
| description | no | Field for describing what this transmission is for the user | String |
| from | yes** | Field for setting the from line of a given transmission | Object |
| html | yes** | Field for setting the HTML content of a given transmission | String |
| inlineCss | no | Field for enabling/disabling CSS inlining | Boolean |
| 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 |
| metadata | no | Field for adding arbitrary key/value pairs which will be included in open/click tracking | Object (Simple) |
| recipientList | no** | Field for specifying a stored recipient list ID to be used for a given transmission | String |
| recipients | yes** | Field for specifying who a given transmission should be sent to | Array of Objects |
| replyTo | no | Field for specifying the email address that should be used when a recipient hits the reply button | String |
| rfc822 | no** | Field for setting the RFC-822 encoded content of a given transmission | String |
| subject | yes | Field for setting the subject line of a given transmission | String |
| substitutionData | no | Field for adding transmission level substitution data, which can be used in a variety of fields and in content | Object (Complex) |
| template | no** | Field for specifying the Template ID of a stored template to be used when sending a given transmission | String |
| text | yes** | Field for setting the Plain Text content of a given transmission | String |
| trackClicks | no | Field for enabling/disabling transmission level click tracking (default: true) | Boolean |
| trackOpens | no | Field for enabling/disabling transmission level open tracking (default: true) | Boolean |
| transactional | no | Field for marking email as transactional (default: false) | Boolean |
| useDraftTemplate | no | Field for allowing the sending of a transmission using a draft of a stored template (default: false) | Boolean |

** - 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.

## Tips and Tricks
### General
* You _must_ provide at least an API key when instantiating the SparkPost Library - `[ 'key'=>'184ac5480cfdd2bb2859e4476d2e5b1d2bad079bf' ]`
* The library's features are namespaced under the various SparkPost API names.

### Transmissions
* If you specify a stored recipient list and inline recipients in a Transmission, you will receive an error.
* If you specify HTML and/or Plain Text content and then provide RFC-822 encoded content, you will receive an error.
* RFC-822 content is not valid with any other content type.
* If you specify a stored template and also provide inline content via `html` or `text`, you will receive an error.
* By default, open and click tracking are enabled for a transmission.
* By default, a transmission will use the published version of a stored template.
##### Then (Asynchronous)
```php
<?php
$promise->then(
// Success callback
function ($response) {
echo $response->getStatusCode();
echo $response->getBody();
},
// Failure callback
function (Exception $e) {
echo $e->getCode();
echo $e->getMessage();
}
);
?>
```

## Handling Exceptions
The promise will throw an exception if the server returns a status code of `400` or higher.

### Exception
* **getCode()**
* Returns the response status code of `400` or higher
* **getMessage()**
* Returns the body of response as an `Array`


### Contributing
See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md).
See [contributing](https://github.com/SparkPost/php-sparkpost/blob/master/CONTRIBUTING.md).
12 changes: 6 additions & 6 deletions composer.json
View file
Expand Up @@ -9,26 +9,26 @@
],
"minimum-stability": "stable",
"scripts": {
"post-install-cmd": "if [ ! -f 'examples/example-config.json' ]; then echo '{\n\t\"api-key\":\"Your API Key\"\n}' >> examples/example-config.json; fi",
"post-update-cmd": "if [ ! -f 'examples/example-config.json' ]; then echo '{\n\t\"api-key\":\"Your API Key\"\n}' >> examples/example-config.json; fi",
"post-install-cmd": "if [ ! -f 'examples/example-options.json' ]; then echo '{\n\t\"key\":\"YOUR_API_KEY\"\n}' >> examples/example-options.json; fi",
"post-update-cmd": "if [ ! -f 'examples/example-options.json' ]; then echo '{\n\t\"key\":\"YOUR_API_KEY\"\n}' >> examples/example-options.json; fi",
"test": "phpunit ./test/unit/",
"fix-style": "php-cs-fixer fix ."
},
"require": {
"php": ">=5.5.0",
"egeloen/http-adapter": "*"
"php-http/client-implementation": "^1.0",
"guzzlehttp/psr7": "1.3.*"
},
"require-dev": {
"phpunit/phpunit": "4.3.*",
"guzzlehttp/guzzle": "6.*",
"php-http/guzzle6-adapter": "*",
"php-http/message": "*",
"mockery/mockery": "^0.9.4",
"satooshi/php-coveralls": "dev-master",
"fabpot/php-cs-fixer": "^1.11"
},
"autoload": {
"psr-4": {
"SparkPost\\": "lib/SparkPost/",
"SparkPost\\SendGridCompatibility\\": "lib/SendGridCompatibility/",
"SparkPost\\Test\\TestUtils\\": "test/unit/TestUtils/"
}
}
Expand Down

0 comments on commit 55d1bdc

Please sign in to comment.