Crankshaft[BU00000277JXGK] Client - PHP @ 2015-10-30 12:57:04 +0000

README.md

@@ -1,57 +1,38 @@
-# PHP Client for GoCardless Pro API
+# GoCardless Pro PHP client library
 
-- [PHP Doc API Doc](http://gocardless.github.io/gocardless-pro-php/)
-- [GoCardless Pro API Docs](https://developer.gocardless.com/pro/)
-- [Composer Package](https://packagist.org/packages/gocardless/gocardless-pro-php)
+A PHP client for interacting with the GoCardless Pro API.
 
-### Installation
-
-The files you need to use the client library are in the `/lib` folder.
+- [API Documentation](https://developer.gocardless.com/pro/2015-07-06)
+- [Composer Package](https://packagist.org/packages/gocardless/gocardless-pro)
 
-To load the library, you only need to require the `lib/loader.php` file. If you're using [Composer](https://getcomposer.org/), you should rely on Composer's autoload functionality.
+### Installation
 
-#### Install from source
+The recommended way to install `gocardless-pro` is using [Composer](https://getcomposer.org/).
 
-```console
-$ git clone git://github.com/gocardless/gocardless-pro-php.git
+```bash
+# Install Composer
+curl -sS https://getcomposer.org/installer | php
 ```
 
-#### Installing from the tarball
-
-```console
-$ curl -L https://github.com/gocardless/gocardless-pro-php/tarball/master | tar xzv
+Next, run the Composer command to install the latest stable version of `gocardless-pro`.
+```bash
+php composer.phar require gocardless/gocardless-pro-php
 ```
 
-#### Installing from the zip
-
-[Click here](https://github.com/gocardless/gocardless-pro-php/zipball/master)
-to download the zip file.
-
-#### Installing with Composer
-
-Add this repository to the contents of your `composer.json`:
-
-```javascript
-{
-    "require": {
-        "gocardless/gocardless-pro-php": "0.3.1"
-    }
-}
+After installing, you need to require Composer's autoloader:
+```php
+require 'vendor/autoload.php';
 ```
 
-## Usage Examples
+### Initialising A Client
 
-- Where a request returns a single resource, the client will return an response object with getters matching the resource's attributes and an attached raw response, retrivable with the `response()` method.
-- Where a request returns multiple resources, the client will return a read-only `ListResponse` object with a method `records()` to return the retrieved records as an array.
-- In case of non-JSON responses (PDFs, etc.), the library will return the raw response.
-- To access data elements, use getter methods (as opposed to properties)
-matching the keys in the JSON response - see the [GoCardless Pro API Docs](https://developer.gocardless.com/pro/) for details.
-
-### Client Initialisation
+Create a `GoCardlessPro\Client` instance, providing your access token and the environment you want to use.
+We strongly advise storing your access token as an environment variable, rather than directly in your code. you can easily load the environment variables from a `.env` file by using something like [phpdotenv](https://github.com/vlucas/phpdotenv), though keep it out of version control!
 
 ```php
+$access_token = getenv('GC_ACCESS_TOKEN');
 $client = new \GoCardlessPro\Client(array(
-  'access_token' => 'YOUR API TOKEN',
+  'access_token' => $access_token,
   'environment'  => \GoCardlessPro\Environment::SANDBOX
 ));
 ```
@@ -60,78 +41,101 @@ Your `access_token` can be found under the "Developer" tab in your GoCardless da
 
 The environment can either be `\GoCardlessPro\Environment::SANDBOX` or `\GoCardlessPro\Environment::PRODUCTION`, depending on whether you want to use the sandbox or production API.
 
-From the client object, resource objects can be accessed for each type of resource which can then be used to fetch or manipulate the resource's members. The available resources can be found in the [PHP library docs](http://gocardless.github.io/gocardless-pro-php/classes/GoCardless.Client.html).
+For full documentation, see our [API docs](https://developer.gocardless.com/pro/2015-07-06).
 
 ### GET requests
 
-Simple requests can be made like this, returning an iterable `ListResponse`:
+You can make a request to get a list of resources using the `list` method.
 
 ```php
-$client->resource()->list();
+$client->customers()->list();
 ```
 
-In the above example, replace `resource()` with the name of a resource (for example `customers()` to fetch a list of your customers) which returns a resource object.
+*Note: This README will use customers throughout but each of the resources in the API is available in this library.*
 
-If you need to pass any options, the last argument (or only argument, whether there are no requried options) to `list()` is an array of options:
+If you need to pass any options, the last (or only, in the absence of URL params) argument to `list()` is an array of URL parameters:
 
+```php
+$customers = $client->customers()->list(['params' => ['limit' => 400]]);
 ```
-$resources = $client->resource()->list(array('limit' => 400));
-echo count($resources->records());
-foreach ($resources->records() as $resource) {
-  echo $resource->property_name();
+
+A call to `list()` returns an instance of `ListResponse`. You can use it's `records` attribute to iterate through the results.
+
+```php
+echo count($customers->records);
+foreach ($customers->records as $resource) {
+  echo $resource->given_name;
 }
 ```
 
-Where URL parameters are required, the method signature will include those required arguments:
+In the case where a URL parameter is needed, the method signature will contain the required arguments:
 
+```php
+$customer = $client->customers()->get($customer_id);
+echo $customer->given_name;
 ```
-$customer = $client->customers()->get('CUXXXX');
-echo $customer->given_name();
 
+As with list, the last argument can be an options array, with any URL parameters given:
+
+```php
+$client->customers.get(customers_id, ['params' => ['some_flag' => true]]);
 ```
 
+Both individual resource and ListResponse instances have an `api_response` attribute, which lets you access the following properties of the request:
+
+- `status`
+- `headers`
+- `body`
+
 ### POST/PUT Requests
 
-Resource objects also have `create()` and `update()` methods for manipulating the resource's members. Provide a body for your request by passing it in as the first argument.
-**You do not need to add the enclosing key.**
+For POST and PUT requests, you need to provide a body for your request by passing it in as the first argument.
 
 ```php
-try {
-    $client->customer()->create(array(
-        "invalid_name" => "Pete",
-    ));
-} catch (\GoCardlessPro\Core\Error\GoCardlessError $e) {
-  // Server validation failed / record couldn't be created.
-  echo $e->documentation_url();
-  echo count($e->errors());
-  // => $e is an ValidationFailedError.
-} catch (\GoCardlessPro\Core\Error\HttpError $e) {
-  echo $e;
-}
+$client->customer()->create([
+  'params' => ["given_name" => "Pete", "family_name" => "Hamilton"]
+]);
 ```
 
-This returns a response object representing the newly-created resource.
-
-As with GET requests, if URL parameters are required, they come first:
+As with GET requests, if any parameters are required, these come first:
 
 ```php
-$client->resource()->update('RSIDXXXXX', array('key' => 'value'));
+$client->customer()->update($customer_id, [...]);
 ```
 
-### Handling failures
+### Handling Failures
+
+When the API returns an error, the library will return a corresponding subclass of `ApiException`, one of:
 
-When the API returns an error, the library will return a `\GoCardlessPro\Core\Error\GoCardlessError`-based error - this may be a `GoCardlessError` or one of its subclasses, `InvalidApiUsageError`, `InvalidStateError`, and `ValidationFailedError` if appropriate.
+- `GoCardlessProException`
+- `InvalidApiUsageException`
+- `InvalidStateException`
+- `ValidationFailedException`
 
-You can access the raw API error (unenveloped) via the `error()` method on the returned error, and a list of all the errors via the `errors()` method. By default the error's message will contain the error message from the API, plus a link to the documentation if available.
+These types of error are all covered in the [API documentation](https://developer.gocardless.com/pro/#overview-errors).
 
-If the error is an HTTP transport layer error (e.g. cannot connect, empty response from server, etc.), the client will throw an `HttpError` based on the Curl error.
+If the error is an HTTP transport layer error (e.g. cannot connect, empty response from server, etc.), the client will throw an `ApiConnectionException`. If it can't parse the response from GoCardless, it will throw a `MalformedResponseException
+
+```php
+try {
+  $client->customer()->create(array(
+    "params" => array("invalid_name" => "Pete")
+  ));
+} catch (\GoCardlessPro\Core\Exception\ApiException $e) {
+  // Api request failed / record couldn't be created.
+} catch (\GoCardlessPro\Core\Exception\MalformedResponseException $e) {
+  // Unexpected non-JSON response
+} catch (\GoCardlessPro\Core\Exception\ApiConnectionException $e) {
+  // Network error
+}
+```
 
 ## Supporting PHP < 5.3.3
 
-This client library only supports PHP >= 5.3.3 out of the box due to its extensive
-use of OOP operators and namespaces.
+This client library only supports PHP >= 5.3.3.
 
 ## Contributing
 
-This client is auto-generated. If there's a bug it's likely with the
-[Crank](https://github.com/gocardless/crank) template or Crank itself. Bugs should be reported on those repositories.
+This client is auto-generated from Crank, a toolchain that we hope to soon open source.
+Issues should for now be reported on this repository.
+**Please do not modify the source code yourself, your changes will be overriden!**

circle.yml

@@ -1,24 +1,6 @@
-dependencies:
-  cache_directories:
-    - vendor/
-
 machine:
   php:
-    version: 5.4.5
-
-deployment:
-  git:
-    branch: dev
-    commands:
-      - make docs
-      - git config user.name "Circle CI"
-      - git config user.email "[email protected]"
-      - rm -rf ./tests ./vendor
-      - rm -f composer.json composer.lock docs/api/.htaccess
-      - git checkout gh-pages
-      - cp -r docs/api/* .
-      - rm -rf docs/
-      - touch .nojekyll
-      - git add .
-      - git commit -m "[ci skip] Generate PHP Doc"
-      - git push origin gh-pages
+    version: 5.5.0
+dependencies:
+  override:
+    - composer install --prefer-source --no-interaction

composer.json

@@ -1,6 +1,7 @@
 {
-  "name": "gocardless/gocardless-pro-php",
+  "name": "gocardless/gocardless-pro",
   "description": "GoCardless Pro PHP Client Library",
+  "version": "0.9.0",
   "keywords": [
     "gocardless",
     "direct debit",
@@ -15,21 +16,21 @@
     }
   ],
   "require": {
-    "php": ">=5.3.3",
+    "php": ">=5.5",
     "ext-curl": "*",
     "ext-json": "*",
-    "ext-mbstring": "*"
+    "ext-mbstring": "*",
+    "guzzlehttp/guzzle": "^6.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "~4.5",
+    "phpunit/phpunit": "~4.8",
     "satooshi/php-coveralls": "~0.6.1",
     "squizlabs/php_codesniffer": "~2.0",
     "phpdocumentor/phpdocumentor": "2.*"
   },
-  "version": "0.3.1",
   "autoload": {
     "psr-4": {
-      "GoCardlessPro\\" : "lib/GoCardlessPro"
+      "GoCardlessPro\\" : "lib/"
     }
   },
   "autoload-dev": {