Merge pull request #198 from SparkPost/formfeed

Address #197: No longer need formfeed replacement. README work.

Author: SteveT

Diff for: CHANGELOG.md

@@ -4,6 +4,11 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased][unreleased]
 
+## [2.2.1] - 2021-03-08
+
+- [#198](https://github.com/SparkPost/php-sparkpost/pull/198)
+- [#191](https://github.com/SparkPost/php-sparkpost/pull/191)
+
 ## [2.2.0] - 2019-06-04
 - [#187](https://github.com/SparkPost/php-sparkpost/pull/169) Updated composer.json
 - [#169](https://github.com/SparkPost/php-sparkpost/pull/169) Optional automatic retry on 5xx
@@ -103,7 +108,8 @@ This major release included a complete refactor of the library to be a thin HTTP
 ### Fixed
 - README now has proper code blocks denoting PHP language
 
-[unreleased]: https://github.com/sparkpost/php-sparkpost/compare/2.2.0...HEAD
+[unreleased]: https://github.com/sparkpost/php-sparkpost/compare/2.2.1...HEAD
+[2.2.1]: https://github.com/sparkpost/php-sparkpost/compare/2.2.0...2.2.1
 [2.2.0]: https://github.com/sparkpost/php-sparkpost/compare/2.1.0...2.2.0
 [2.1.0]: https://github.com/sparkpost/php-sparkpost/compare/2.0.3...2.1.0
 [2.0.3]: https://github.com/sparkpost/php-sparkpost/compare/2.0.2...2.0.3

Diff for: README.md

@@ -26,8 +26,8 @@ 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 guzzlehttp/guzzle
-composer require php-http/guzzle6-adapter
+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:
@@ -43,7 +43,29 @@ require 'vendor/autoload.php';
 use SparkPost\SparkPost;
 ```
 
-**Note:** Without composer the costs outweight 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. 
+**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
 
@@ -179,44 +201,54 @@ use GuzzleHttp\Client;
 use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
 
 $httpClient = new GuzzleAdapter(new Client());
-$sparky = new SparkPost($httpClient, ['key'=>'YOUR_API_KEY']);
+// 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]);
 
-$promise = $sparky->transmissions->post([
-    'content' => [
-        'from' => [
-            'name' => 'SparkPost Team',
-            'email' => '[email protected]',
+try {
+    $response = $sparky->transmissions->post([
+        'content' => [
+            'from' => [
+                'name' => 'SparkPost Team',
+                'email' => '[email protected]',
+            ],
+            'subject' => 'First Mailing From PHP',
+            '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!',
         ],
-        'subject' => 'First Mailing From PHP',
-        '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' => [
-                'name' => 'YOUR_NAME',
-                'email' => 'YOUR_EMAIL',
+        'substitution_data' => ['name' => 'YOUR_FIRST_NAME'],
+        'recipients' => [
+            [
+                'address' => [
+                    'name' => 'YOUR_NAME',
+                    'email' => 'YOUR_EMAIL',
+                ],
             ],
         ],
-    ],
-    'cc' => [
-        [
-            'address' => [
-                'name' => 'ANOTHER_NAME',
-                'email' => 'ANOTHER_EMAIL',
+        'cc' => [
+            [
+                'address' => [
+                    'name' => 'ANOTHER_NAME',
+                    'email' => 'ANOTHER_EMAIL',
+                ],
             ],
         ],
-    ],
-    'bcc' => [
-        [
-            'address' => [
-                'name' => 'AND_ANOTHER_NAME',
-                'email' => 'AND_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);
 ?>
 ```
 
@@ -250,8 +282,8 @@ The API calls either return a `SparkPostPromise` or `SparkPostResponse` dependin
 ```php
 $sparky->setOptions(['async' => false]);
 try {
-    $response = $sparky->transmissions->get();
-    
+    $response = $sparky->transmissions->get(); //TODO: Change this. Transmissions no longer supports GET call
+
     echo $response->getStatusCode()."\n";
     print_r($response->getBody())."\n";
 }
@@ -265,7 +297,7 @@ 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();
+$promise = $sparky->transmissions->get(); //TODO: Change this. Transmissions no longer supports GET call
 
 try {
     $response = $promise->wait();
@@ -281,7 +313,7 @@ echo "I will print out after the promise is fulfilled";
 
 ##### Then (Asynchronous)
 ```php
-$promise = $sparky->transmissions->get();
+$promise = $sparky->transmissions->get(); //TODO: Change this. Transmissions no longer supports GET call
 
 $promise->then(
     // Success callback

Diff for: lib/SparkPost/SparkPost.php

@@ -184,12 +184,8 @@ public function buildRequestValues($method, $uri, $payload, $headers)
         $url = $this->getUrl($uri, $params);
         $headers = $this->getHttpHeaders($headers);
 
-        // Sparkpost API will not tolerate form feed in JSON.
-        $jsonReplace = [
-            '\f' => '',
-        ];
-        $body = strtr(json_encode($body), $jsonReplace);
-
+        // old form-feed workaround now removed
+        $body = json_encode($body);
         return [
             'method' => $method,
             'url' => $url,