Crankshaft Build #BU000000B2WYQD @ 2015-04-09 10:11:36 +0000

README.md

@@ -13,59 +13,70 @@ gem '<no value>'
 
 ## Usage Examples
 
-- In the case of singular responses, Crank will return you an unenveloped hash.
-- In the case of list responses, Crank returns an unenveloped Array of hashes.
-- In the case of non JSON responses, Crank will return the raw response (PDFs etc)
+- In the case of singular responses, Crank will return you an response object with getters matching the json descriptions and an attached response().
+- In the case of list responses, Crank returns an list response object that is read-only. Raw array data can be retrieved from the items() function of the object.
+- In the case of non JSON responses, Crank will return the raw response (PDFs etc.)
+
+### Client Initialisation
+```php
+$client = new \GoCardless\Client(array(
+  'api_key' => 'YOUR API KEY',
+  'api_secret' => 'YOUR API SECRET',
+  'environment' => \GoCardless\Environment::SANDBOX
+));
+```
+The api_key and api_secret can be found under the organisation tab, the environment can either be `\GoCardless\Environment::SANDBOX` or `\GoCardless\Environment::PRODUCTION`.
+
+Given the client object, resource objects can be accessed then methods on each resource can be called to either fetch or manipulate the resource's members.
 
 ### GET requests
 
 Simple requests can be made like this:
 
+```php
+$client->resource()->list()
 ```
-GoCardless.resource.list
-```
+returning an iteratable ListResponse.
 
-If you need to pass any options, the last (or in the absence of URL params, the only) argument is an options hash. You can use this to pass query params and headers like this:
 
+If you need to pass any options, the last (or in the absence of URL params, the only) argument is an options hash. You can use this to pass parameters like this:
 ```
-GoCardless.resource.list(headers: { 'Foo' => 'Baz' }, query: { limit: 400 })
+$client->resource()->list(array(limit => 400))
 ```
 
 In the case where url parameters are needed, the method signature will contain required arguments:
 
 ```
-GoCardless.resource.show(resource_id)
+$client->resource()->show(resource_id)
 ```
 
 As with list, the last argument can be an options hash:
 
 ```
-GoCardless.resource.show(resource_id, query: { limit: 200 }, headers: { 'Foo' => 'Bar' })
+$client->resource()->show(resource_id, array(limit => 200))
 ```
 
 ### POST/PUT Requests
 If your request needs a body, you can add this in the same way you would add query params or headers.
 **However**, you need to add the enveloping key!
 
 ```
-GoCardless.resource.create(body: {
-    resources: {
-        first_name: "Pete",
-        last_name: "Hamilton",
-        ...
-    }
-})
+$client->customer()->create(array(
+    "given_name" => "Pete",
+    "family_name"  => "Hamilton"
+));
 ```
+This returns a response object as the new created resource
 
 As with GET requests, if href params are required they come first
 
 ```
-GoCardless.resource.update(resource_id, body: { ... })
+$client->resource()->update(resource_id, array(...))
 ```
 
 ### Handling failures
 
-When an API returns an error, Crank will return an `ApiError`.
+When an API returns an error, Crank will return an `GoCardlessError`.
 
 Assuming the error response form the server is in JSON format, like:
 
@@ -90,45 +101,12 @@ Assuming the error response form the server is in JSON format, like:
 }
 ```
 
-Crank will return an GoCardless::Core::ApiError error. You can access the raw hash (unenveloped) via a `.errors` method, by default the error message will contain the error's message and a link to the documentation if it exists.
-
-
-
-## Re-Generating the Client
-
-The client has an `.atum.yml` file which defines some defaults, meaning you can re-generate the client really easily by navigating to the client's root and running:
-
-```
-$ atum generate --file PATH_TO_SCHEMA
-```
-
-If for any reason, you need to override the URL or headers, you can do so using cli options. To see the full range of available options, use:
-
-```
-$ atum help
-```
-
-As always, make your changes in a branch and then when satisfied, merge into master and bump the version (don't forget to add tags!
-
-You can do this via:
-
-```
-$ gem bump --version (patch|minor|major) --tag
-```
-
-## Supporting Ruby < 2.0.0
-Crank only supports Ruby >= 2.0.0 out of the box due to our use of
-Enumerable::Lazy for lazy loading of paginated API resources.
-
-However, support for previous ruby versions can be added using a gem such as
-[backports](https://github.com/marcandre/backports).
-
-1. Add backports to your Gemfile
-   ```gem 'backports'```
-2. Require lazy enumerables
-   ```require 'backports/2.0.0/enumerable/lazy.rb'```
+Crank will return an `\GoCardless\Core\Error\GoCardlessError`-based error. The possible errors vary on the exception internally but are `InvalidApiUsageError`, `InvalidStateError`, and `ValidationFailedError`, all other errors use the `GoCardlessError` class. If the error is an http transport layer error (cannot connect, empty response from server, etc.), the client will throw an `HttpError`. You can access the raw hash (unenveloped) via the `->error()` method, and a list of all the errors via the `->allErrors()` method. By default the error message will contain the error's message and a link to the documentation if it exists.
 
 
+## Supporting PHP < 5.3.3
+Crank only supports PHP >= 5.3.3 (possibly 5.0) out of the box due to its extensive
+use of OOP operators and namespaces in PHP for code cleanliness.
 
 ## Contributing
 

circle.yml

@@ -1,3 +1,3 @@
 machine:
   php:
-    version: 5.5.11
+    version: 5.3.3

composer.json

@@ -10,7 +10,7 @@
   "license": "MIT",
   "authors": [
     {
-      "name": "Gocardless and contributors",
+      "name": "GoCardless and contributors",
       "homepage": "https://github.com/gocardless/pro-client-php/contributors"
     }
   ],

demo/cli_creditors.php

@@ -1,6 +1,6 @@
 <?php
 
-require('../gocardless.php');
+require('../loader.php');
 
 error_reporting(E_ALL | E_STRICT);
 
@@ -19,10 +19,10 @@ function get_input()
 $creditors = $client->creditors()->list();
 
 foreach ($creditors as $num => $creditor) {
-    echo $num . ': ' . $creditor->name() . "\n";
+    echo '[' . $num . '] ' . $creditor->name() . "\n";
 }
 
-echo 'Please select a creditor: ';
+echo 'Please select a creditor by number: ';
 
 $num = intval(get_input());
 

demo/demo.php

@@ -1,6 +1,6 @@
 <?php
 
-require('../gocardless.php');
+require('../loader.php');
 
 $client = new GoCardless\Client(array(
   'api_key'     => '<no value>',

lib/GoCardless/Core/Error/GoCardlessError.php

@@ -39,17 +39,17 @@ public static function makeApiError($error, $status)
         return new GoCardlessError($error, $status);
     }
 
-    public function getError()
+    public function error()
     {
         return $this->error;
     }
 
-    public function getErrors()
+    public function allErrors()
     {
         return $this->error->error->errors;
     }
 
-    public function getHttpStatus()
+    public function httpStatus()
     {
         return $this->httpStatus;
     }

lib/GoCardless/Core/ListResponse.php

@@ -7,12 +7,11 @@
 
 namespace GoCardless\Core;
 
-class ListResponse implements \Iterator, \ArrayAccess
+class ListResponse extends \ArrayObject
 {
     private $models = array();
     private $response;
     private $modelClass;
-    private $position = 0;
 
     public function __construct($modelClass, $response)
     {
@@ -21,6 +20,7 @@ public function __construct($modelClass, $response)
         foreach ($response->response() as $item) {
             $this->models[] = new $modelClass($item);
         }
+        parent::__construct($this->models);
     }
 
     public function response()
@@ -42,48 +42,4 @@ public function getItems()
     {
         return $this->models;
     }
-
-    /**
-      * Methods to allow for array access to list response.
-      */
-    public function offsetSet($offset, $value)
-    {
-        throw new \Exception($this->modelClass . ' ListResponse is readonly');
-    }
-    public function offsetUnset($offset)
-    {
-        throw new \Exception($this->modelClass . ' ListResponse is readonly');
-    }
-    public function offsetExists($offset)
-    {
-        return isset($this->models[$offset]);
-    }
-    public function offsetGet($offset)
-    {
-        return $this->models[$offset];
-    }
-
-    /**
-      * Array Iterator methods to allow foreach() on object.
-      */
-    public function rewind()
-    {
-        $this->position = 0;
-    }
-    public function current()
-    {
-        return $this->models[$this->position];
-    }
-    public function key()
-    {
-        return $this->position;
-    }
-    public function next()
-    {
-        ++$this->position;
-    }
-    public function valid()
-    {
-        return isset($this->models[$this->position]);
-    }
 }