Merge pull request #12 from GetResponse/release-2.0.0

SDK release 2.0.0

CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.0.0 - 2020-03-02
+
+* Add operations for:
+  * Click Tracks
+  * File Library
+  * Newsletter Activities
+  * Transactional Emails
+* Remove unused classes and methods
+* Code clean-up
+
+Read more in [Upgrade Guide](UPGRADING.md)
+
 ## 1.2.1 - 2019-06-07
 
 * Improve documentation

README.md

@@ -1,17 +1,17 @@
 # GetResponse APIv3 PHP SDK
 
+This document covers the basics of using SDK for PHP. For detailed documentation, please refer to the resources in [docs](docs) directory:
 
-This document covers the basics of using SDK for PHP. For detailed documentation, please refer to the resources in ./lib directory:
-
-* [Client](./docs/lib/client.md) - methods and factories to create API Client
-* [Client Debugging](./docs/lib/client_debugging.md) - how to get detailed information from API Client for development purposes
-* [Collect list](./docs/lib/collect_list_of_resources.md) - getting lists of resources, with defining queries and sort fields
-* [Resource details](./docs/lib/get_resource_details.md) - getting single resource with details
-* [Create resources](./docs/lib/create_resource.md) - defining data models and creating resources
-* [Delete resources](./docs/lib/delete_resource.md) - deleting resources
-* [Updating resources](./docs/lib/update_resource.md) - updating resources
-
+* [Client](docs/lib/client.md) - basic API client usage
+* [Client Debugging](docs/lib/client_debugging.md) - how to log API communication, and debug the integration
+* [Getting lists of resources](docs/lib/get_list_of_resources.md)
+* [Getting resource details](docs/lib/get_resource_details.md)
+* [Create resources](docs/lib/create_resource.md) - building data models and creating resources
+* [Deleting resources](docs/lib/delete_resource.md)
+* [Updating resources](docs/lib/update_resource.md)
+* [Upgrade guide](UPGRADING.md) - upgrading from 1.x version to 2.x
 
+Read more about the API in [GetResponse API Docs](https://apidocs.getresponse.com/v3) and [GetResponse API Reference](https://apireference.getresponse.com/).
 
 ## Requirements
 
@@ -23,36 +23,36 @@ This document covers the basics of using SDK for PHP. For detailed documentation
 
 ## SDK installation
 
-### By git
-
-We recommend the `composer` installation. However, you can get SDK PHP by cloning the git project:
+### Using Composer
 
 ```
-
-git clone https://github.com/GetResponse/sdk-php.git
-
+composer require getresponse/sdk-php
 ```
 
-### Installing Composer
+See [https://getcomposer.org](https://getcomposer.org) for details.
 
-Copy composer.json from the `examples` directory into your project directory and run the `composer install` command in this directory.
+### Using git
+
+We recommend the `composer` installation. However, you can get SDK PHP by cloning the git project:
 
-You can also integrate with an existing one by running
 ```
-composer require getresponse/sdk-php
+
+git clone https://github.com/GetResponse/sdk-php.git
+
 ```
 
-See [https://getcomposer.org](https://getcomposer.org) for in-depth tutorials.
+The releases are available on GitHub: [https://github.com/GetResponse/sdk-php/releases](https://github.com/GetResponse/sdk-php/releases)
 
 ## Creating client
 
 To create a GetResponse client object, use:
 
 ```php
+<?php
 
 use Getresponse\Sdk\GetresponseClientFactory;
 
-$client = GetresponseClientFactory::createWithApiKey('1234567e590706d0a3e7e5a30053e456');
+$client = GetresponseClientFactory::createWithApiKey('my_api_key');
 
 ```
 
@@ -65,17 +65,21 @@ Please see the `GetResponseClientFactory` class from `PHP SDK` for other factori
 For the Enterprise environment please use one of the Enterprise factories, e.g.:
 
 ```php
+<?php
+
 use Getresponse\Sdk\GetresponseClientFactory;
 
-$client = GetresponseClientFactory::createEnterprisePLWithApiKey('1234567e590706d0a3e7e5a30053e456', 'myexampledomain.com');
+$client = GetresponseClientFactory::createEnterprisePLWithApiKey('my_api_key', 'myexampledomain.com');
 
 ```
 or:
 
 ```php
+<?php
+
 use Getresponse\Sdk\GetresponseClientFactory;
 
-$client = GetresponseClientFactory::createEnterpriseUSWithApiKey('1234567e590706d0a3e7e5a30053e456', 'myexampledomain.com');
+$client = GetresponseClientFactory::createEnterpriseUSWithApiKey('my_api_key', 'myexampledomain.com');
 
 ```
 
@@ -88,20 +92,22 @@ To send a single operation (request), you have to create an operation object (po
 Example:
 
 ```php
+<?php
+
+use Getresponse\Sdk\Operation\Campaigns\GetCampaigns\GetCampaigns;
 
-// create $client first
 $campaignsOperation = new GetCampaigns();
 $response = $client->call($campaignsOperation);
 
 ```
 
 As a result, you will get a response object.
 
-You can send multiple operations with one request. This will speed up operations with parallel processing. Please note that throttling limits will apply ([refer to API limit and throttling documentation](https://apidocs.getresponse.com/v3/limits)).
+You can send multiple operations with one request. This will speed up operations with parallel processing. Please note that throttling limits will apply ([read more in API limits and throttling documentation](https://apidocs.getresponse.com/v3/limits)).
 
 ```php
+<?php
 
-// create $client first
 $operationsArray = array($operation1, $operation2, $operation3);
 $responsesCollection = $client->callMany($operationsArray);
 
@@ -114,8 +120,9 @@ As a result, you will get a collection of responses. The responses are in the sa
 To get a response, call:
 
 ```php
+<?php
 
-$response = $client->call($operation);
+$response = $client->call($campaignsOperation);
 
 ```
 
@@ -124,6 +131,7 @@ $response = $client->call($operation);
 To determine if a response was successful, use:
 
 ```php
+<?php
 
 $response->isSuccess();
 
@@ -132,7 +140,10 @@ $response->isSuccess();
 To get HTTP status of response, use:
 
 ```php
+<?php
+
 $response->getResponse()->getStatusCode();
+
 ```
 
 ### Response data
@@ -142,32 +153,40 @@ The response is compatible with [PSR-7](https://www.php-fig.org/psr/psr-7/).
 
 Examples:
 
-To get the data from response (in array format):
+To get the data from response (as array):
 
 ```php
+<?php
+
 $response->getData();
+
 ```
 
 To get unprocessed data, from a response (in a serialized JSON format):
 
 ```php
+<?php
+
 $response->getResponse()->getBody()->getContents();
+
 ```
 
 To get the response size:
 
 ```php
+<?php
+
 $response->getResponse()->getBody()->getSize();
+
 ```
 
 To get the pagination data:
 
 ```php
+<?php
+
 $response->isPaginated();
 
 $response->getPaginationValues();
-```
-
 
----
-Refer to [GetResponse API documentation](https://apidocs.getresponse.com/v3).
+```

UPGRADING.md

@@ -0,0 +1,22 @@
+# Upgrade Guide
+
+## Upgrading from 1.x to 2.x
+
+Most changes made in 2.x release are effects of fixes and clarifications made to the API specification, the rest is related to some minor refactorings and optimisations.
+
+What to look for:
+ * removed classes, for example:
+    * classes that were never used in data models or operations,
+    * classes that made no sense, like empty `SearchQueries`,
+    * classes related to CRM functionality,
+ * removed methods, for example:
+    * it's not possible to change the `ipAddress` of an existing contact, but there was a method for it in `\Getresponse\Sdk\Operation\Model\UpdateContact` class,
+    * it's not possible to set contact's `note` when creating it, but there was a method for it in `\Getresponse\Sdk\Operation\Model\NewContact` class,
+    * some Operations had methods to set Pagination, Search or Sort params, but don't support them,
+ * added classes - SDK now supports more resources, for example:
+    * FileLibrary
+    * ClickTracks
+    * TransactionalEmails management and statistics
+    * Newsletter Activities
+
+There are no changes to the client, request or response handling.

docs/lib/client.md

@@ -1,53 +1,56 @@
 # Creating API Client and handling requests.
 
-## Before you begin
-This is a general method. Please consider using the dedicated factory functions as described in [Initialization by factory](client.md#initialization-by-factory).
-
-
 ## Initialization
 
+_This is a direct method. Please consider using the dedicated factory functions as described in [Initialization by factory](client.md#initialization-by-factory)._
+
 Example basic initialization with required arguments:
 
-```
+```php
+<?php
+
+use Getresponse\Sdk\Client\GetresponseClient;
+use Getresponse\Sdk\Client\Handler\CurlRequestHandler;
+use Getresponse\Sdk\Environment\GetResponse;
+use Getresponse\Sdk\Authentication\ApiKey;
+
 // $apiKey - your GetResponse API Key
+$apiKey = 'my_api_key';
+
 $client = new GetresponseClient(
     new CurlRequestHandler(),  
     new GetResponse(),
-    new ApiKey($apiKey),
+    new ApiKey($apiKey)
 );
 ```    
 
-Constructor's parameters:
+`GetresponseClient` constructor's parameters are:
 
-```php
- public function __construct(
-     RequestHandler $requestHandler,
-     Environment $environment,
-     AuthenticationProvider $authentication
- )
-```
+ 1. `RequestHandler $requestHandler`,
+ 2. `Environment $environment`,
+ 3. `AuthenticationProvider $authentication`
 
  * `RequestHandler` - implementation of `RequestHandler` interface, we provide two handlers:
    * `CurlRequestHandler` - basic cURL based handler for single requests or sequential multi requests
-   * `CurlMultiRequestHandler` - cURL handler with simultaneous requests support. Use this handler for handling big number of requests to speed up an operation, please note maximum number of concurrent request is limited by throttling limits ([Refer to API limit and throttling documentation](https://apidocs.getresponse.com/v3/limits))
- * `Enviroment` - one of (depending on the API you use):
-   * `GetResponse`
-   * `GetResponseEnterprisePL`
-   * `GetResponseEnterpriseUS`
- * `AuthenticationProvider` - we support:
-   * `ApiKey`
-   * `OAuth`
+   * `CurlMultiRequestHandler` - cURL handler with simultaneous requests support. Use this handler for handling big number of requests to speed up the processing, please note maximum number of concurrent request is limited by throttling limits ([Refer to API limit and throttling documentation](https://apidocs.getresponse.com/v3/limits))
+ * `Enviroment` implementation - one of the following (depending on your account type):
+   * `GetResponse` - for Basic, Plus and Professional package users
+   * `GetResponseEnterprisePL` - for Enterprise users (ask your Account Manager for details)
+   * `GetResponseEnterpriseUS` - for Enterprise users (ask your Account Manager for details)
+ * `AuthenticationProvider` implementation - we provide:
+   * `ApiKey` - API Key based authentication
+   * `OAuth` - OAuth2 access token base authentication
 
 ## Initialization by factory
 
 We strongly suggest you use the dedicated factory methods to initialize the preconfigured client. Depending on your project you can use:
 
-* `GetresponseClientFactory::createWithApiKey($apiKey)` - returns the client configured for GetResponse environment and the ApiKey authorization method
-* `GetresponseClientFactory::createEnterprisePLWithApiKey($apiKey, $domain)` - returns the client configured for the Enterprise PL environment and the ApiKey authorization method
-* `GetresponseClientFactory::createEnterpriseUSWithApiKey($apiKey, $domain)` - returns the client configured for the Enterprise US environment and the ApiKey authorization method
+* `GetresponseClientFactory::createWithApiKey($apiKey)` - returns the client configured for GetResponse environment and the API Key authorization method
+* `GetresponseClientFactory::createEnterprisePLWithApiKey($apiKey, $domain)` - returns the client configured for the Enterprise PL environment and the API Key authorization method
+* `GetresponseClientFactory::createEnterpriseUSWithApiKey($apiKey, $domain)` - returns the client configured for the Enterprise US environment and the API Key authorization method
 * `GetresponseClientFactory::createWithAccessToken($accessToken)` - returns the client configured for the GetResponse environment and the OAuth2 authorization method
 * `GetresponseClientFactory::createEnterprisePLWithAccessToken($accessToken, $domain)` - returns the client configured for the GetResponse Enterprise PL environment and the OAuth2 authorization method
-* `GetresponseClientFactory::createEnterpriseUSWithAccessToken($accessToken, $domain)` - returns the client configured for the GetResponse Enterprise US environment and OAuth2 authorization method
+* `GetresponseClientFactory::createEnterpriseUSWithAccessToken($accessToken, $domain)` - returns the client configured for the GetResponse Enterprise US environment and the OAuth2 authorization method
 
 [Where do I find the API Key?](https://www.getresponse.com/help/integrations-and-api/where-do-i-find-the-api-key.html)
 
@@ -57,7 +60,7 @@ Below is the list of the available functions:
 * `call($operation)` - calls a single operation and returns the response (`ResponseInterface`).
 * `callMany($array)` - calls an array of operations, returns an iterable collection of responses. Note the way the `callMany` behavior depends on your RequestHandler:
   * `CurlRequestHandler` performs requests sequentially, one by one.
-  * `CurlMultiRequestHandler` performs requests simultaneously. Maximum number of concurrent request is limited by throttling limits ( [Refer to API documentation](https://apidocs.getresponse.com/v3/limits) ). Please note the `MAX_CALLS_LIMIT` constant setting - the array of operations can't exceeds this limit. Otherwise, you will get an exception. Both limits apply.
+  * `CurlMultiRequestHandler` performs requests simultaneously. Maximum number of concurrent request is limited by throttling limits ([Read more in API Docs](https://apidocs.getresponse.com/v3/limits)). Please note the `MAX_CALLS_LIMIT` constant setting - the array of operations can't exceeds this limit. Otherwise, you will get an exception. Both limits apply.
 
 
 ## Logging and debugging