Merge pull request #201 from SparkPost/update-examples

Update examples

Author: SteveT

.gitignore

@@ -7,3 +7,9 @@ test/output/
 /composer.phar
 composer.lock
 test.php
+.php-version
+.gitignore
+.phpunit.result.cache
+.DS_Store
+.gitignore
+.vscode/launch.json

CHANGELOG.md

@@ -4,13 +4,16 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
 
-## [2.2.1] - 2021-03-08
+## [2.3.0] - 2021-03-16
+- [#201](https://github.com/SparkPost/php-sparkpost/pull/201) Update examples, README
+- [#200](https://github.com/SparkPost/php-sparkpost/pull/200) PHP 8 support
 
-- [#198](https://github.com/SparkPost/php-sparkpost/pull/198)
-- [#191](https://github.com/SparkPost/php-sparkpost/pull/191)
+## [2.2.1] - 2021-03-08
+- [#198](https://github.com/SparkPost/php-sparkpost/pull/198) Address #197: No longer need formfeed replacement. README work.
+- [#191](https://github.com/SparkPost/php-sparkpost/pull/191) Updating License
 
 ## [2.2.0] - 2019-06-04
-- [#187](https://github.com/SparkPost/php-sparkpost/pull/169) Updated composer.json
+- [#187](https://github.com/SparkPost/php-sparkpost/pull/187) Updated composer.json
 - [#169](https://github.com/SparkPost/php-sparkpost/pull/169) Optional automatic retry on 5xx
 - [#166](https://github.com/SparkPost/php-sparkpost/pull/166/files) Quick fix for using the API without composer
 - [#149](https://github.com/SparkPost/php-sparkpost/pull/149) Setters should return current object

CONTRIBUTING.md

@@ -24,11 +24,41 @@ curl -sS https://getcomposer.org/installer | php
 
 Add composer install directory to $PATH `~/.composer/vendor/bin/`
 
-#### Install PHPUnit for Testing
-```
-composer global require "phpunit/phpunit=4.8.*"
+### phpenv
+
+[phpenv](https://github.com/phpenv/phpenv-installer) is useful for testing locally across different PHP versions.
+
+### Developing your app against a local version of the SparkPost library
+
+If you're working on the library and your app together, you can tell Composer to get `php-sparkpost` from a local path. With a directory structure such as:
+
+home
+ - php-sparkpost
+ - my-app
+    - composer.json
+    - .. etc
+
+Use the following for `my-app/composer.json`:
+```json
+{
+    "name": "sparkpost/php_simple_email_send",
+    "description": "a small test program to send an email",
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../php-sparkpost"
+        }
+    ],
+    "require": {
+        "php-http/guzzle6-adapter": "^1.1",
+        "guzzlehttp/guzzle": "^6.0",
+        "sparkpost/sparkpost": "dev-master"
+    }
+}
 ```
 
+
+### Memory
 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`.
 
 #### Install XDebug for code coverage generation
@@ -68,6 +98,7 @@ Once you are setup for local development:
 
 ## Releasing
 
-* Update version information in composer.json during development.
-* Once its been merged down, create a release tag in git.
+* Update version in the [library](https://github.com/SparkPost/php-sparkpost/blob/eeb6ba971584fcc4c12fd69247c6b24df7827af5/lib/SparkPost/SparkPost.php#L16) during development. This is used in the `user_agent` of your requests.
+
+* Once it's been merged down, create a release tag in git.
 * Composer will automatically pickup the new tag and present it as a release.

README.md

@@ -143,7 +143,7 @@ $sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
 * `uri`
     * Required: Yes
     * Type: `String`
-    * The URI to recieve the request
+    * The URI to receive the request
 * `payload`
     * Required: No
     * Type: `Array`
@@ -170,24 +170,18 @@ Sends an asynchronous request to the SparkPost API and returns a `SparkPostPromi
     *  Type: `Array`
     * See constructor
 
-
 ## 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
+        * Recipients to receive 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
+        * Recipients to discreetly receive a carbon copy of the transmission
 
 ## Examples
 
@@ -202,9 +196,8 @@ use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
 
 $httpClient = new GuzzleAdapter(new Client());
 // Good practice to not have API key literals in code - set an environment variable instead
-$sparky = new SparkPost($httpClient, ['key' => getenv('SPARKPOST_API_KEY')]);
 // For simple example, use synchronous model
-$sparky->setOptions(['async' => false]);
+$sparky = new SparkPost($httpClient, ['key' => getenv('SPARKPOST_API_KEY'), 'async' => false]);
 
 try {
     $response = $sparky->transmissions->post([
@@ -252,7 +245,28 @@ 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
 <?php
@@ -263,17 +277,19 @@ use GuzzleHttp\Client;
 use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
 
 $httpClient = new GuzzleAdapter(new Client());
-$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
+$sparky = new SparkPost($httpClient, [
+    'key' => getenv('SPARKPOST_API_KEY'),
+    'async' => false]);
 
-$promise = $sparky->request('GET', 'metrics/ip-pools', [
-    'from' => '2014-12-01T09:00',
-    'to' => '2015-12-01T08:00',
-    'timezone' => 'America/New_York',
-    'limit' => '5',
-]);
+$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`
@@ -282,7 +298,7 @@ The API calls either return a `SparkPostPromise` or `SparkPostResponse` dependin
 ```php
 $sparky->setOptions(['async' => false]);
 try {
-    $response = $sparky->transmissions->get(); //TODO: Change this. Transmissions no longer supports GET call
+    $response = ... // YOUR API CALL GOES HERE
 
     echo $response->getStatusCode()."\n";
     print_r($response->getBody())."\n";
@@ -297,7 +313,8 @@ catch (\Exception $e) {
 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 = $sparky->transmissions->get(); //TODO: Change this. Transmissions no longer supports GET call
+
+$promise = ... // YOUR API CALL GOES HERE
 
 try {
     $response = $promise->wait();
@@ -313,7 +330,7 @@ echo "I will print out after the promise is fulfilled";
 
 ##### Then (Asynchronous)
 ```php
-$promise = $sparky->transmissions->get(); //TODO: Change this. Transmissions no longer supports GET call
+$promise = ... // YOUR API CALL GOES HERE
 
 $promise->then(
     // Success callback

examples/debug/index.php

@@ -14,8 +14,8 @@
  * configure options in example-options.json
  */
 $sparky = new SparkPost($httpClient, [
-    "key" => "YOUR_API_KEY",
-    // This will expose your API KEY - do not use this in production.
+    "key" => getenv('SPARKPOST_API_KEY'),
+    // fetch API KEY from environment variable
     "debug" => true
 ]);
 

examples/message-events/get_message_events.php

@@ -10,9 +10,11 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY",]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY')]);
 
-$promise = $sparky->request('GET', 'message-events', [
+// New endpoint - https://developers.sparkpost.com/api/events/
+$promise = $sparky->request('GET', 'events/message', [
     'campaign_ids' => 'CAMPAIGN_ID',
 ]);
 

examples/message-events/get_message_events_with_retry_logic.php

@@ -10,9 +10,11 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY", "retries" => 3]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY'), "retries" => 3]);
 
-$promise = $sparky->request('GET', 'message-events', [
+// New endpoint - https://developers.sparkpost.com/api/events/
+$promise = $sparky->request('GET', 'events/message', [
     'campaign_ids' => 'CAMPAIGN_ID',
 ]);
 

examples/templates/create_template.php

@@ -10,14 +10,50 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY"]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => 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 = <<<HTML
+<!DOCTYPE html>
+<html lang="en">
+<body>
+  <p><strong>Write your HTML message part here</strong></p>
+</body>
+</html>
+HTML;
+
+$amp_html = <<<HTML
+<!doctype html>
+<html ⚡4email>
+<head>
+  <meta charset="utf-8">
+  <style amp4email-boilerplate>body{visibility:hidden}</style>
+  <script async src="https://cdn.ampproject.org/v0.js"></script>
+</head>
+<body>
+Hello World! Let's get started using AMP HTML together!
+</body>
+</html>
+HTML;
 
 $promise = $sparky->request('POST', 'templates', [
-  'name' => 'PHP example template',
+  'name' => $template_name,
+  'id' => $template_id,
   'content' => [
-    'from' => 'from@YOUR_DOMAIN',
+    'from' => "from@$sending_domain",
     'subject' => 'Your Subject',
-    'html' => '<b>Write your message here.</b>',
+    'text' => $plain_text,
+    'html' => $html,
+    'amp_html' => $amp_html,
   ],
 ]);
 

examples/templates/delete_template.php

@@ -10,9 +10,12 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY"]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY')]);
 
-$promise = $sparky->request('DELETE', 'templates/TEMPLATE_ID');
+$template_id = "PHP-example-template";
+
+$promise = $sparky->request('DELETE', "templates/$template_id");
 
 try {
     $response = $promise->wait();

examples/templates/get_all_templates.php

@@ -10,7 +10,8 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY"]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY')]);
 
 $promise = $sparky->request('GET', 'templates');
 

examples/templates/get_template.php

@@ -10,9 +10,12 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY"]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY')]);
 
-$promise = $sparky->request('GET', 'templates/TEMPLATE_ID?draft=true');
+$template_id = "PHP-example-template";
+
+$promise = $sparky->request('GET', "templates/$template_id?draft=true");
 
 try {
     $response = $promise->wait();

examples/templates/preview_template.php

@@ -10,9 +10,12 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY"]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY')]);
 
-$promise = $sparky->request('POST', 'templates/TEMPLATE_ID/preview?draft=true', [
+$template_id = "PHP-example-template";
+
+$promise = $sparky->request('POST', "templates/$template_id/preview?draft=true", [
     'substitution_data' => [
         'some_key' => 'some_value',
     ],

examples/templates/update_template.php

@@ -10,9 +10,12 @@
 
 $httpClient = new GuzzleAdapter(new Client());
 
-$sparky = new SparkPost($httpClient, ["key" => "YOUR_API_KEY"]);
+// In these examples, fetch API key from environment variable
+$sparky = new SparkPost($httpClient, ["key" => getenv('SPARKPOST_API_KEY')]);
 
-$promise = $sparky->request('PUT', 'templates/TEMPLATE_ID', [
+$template_id = "PHP-example-template";
+
+$promise = $sparky->request('PUT', "templates/$template_id", [
     'options' => [
         'open_tracking' => true,
     ],