Merge pull request #21 from picqer/v4

Bol Retailer v4 only

README.md

@@ -1,42 +1,77 @@
 # Bol.com Retailer API client for PHP
-This is an open source PHP client for the [Bol.com Retailer API](https://developers.bol.com/newretailerapiv3/) version 3.
+This is an open source PHP client for the [Bol.com Retailer API](https://api.bol.com/retailer/public/Retailer-API/v4/releasenotes.html) version 4.
 
 ## Installation
-This project can easily be installad through Composer:
+This project can easily be installed through Composer:
 
 ```
 composer require picqer/bol-retailer-php-client
 ```
 
 ## Usage
-First configure the client by setting the credentials:
+Create an instance of the client and authenticate
 ```php
-Picqer\BolRetailer\Client::setCredentials('your-client-id', 'your-client-secret');
+$client = new \Picqer\BolRetailer\Client();
+$client->authenticate('your-client-id', 'your-client-secret');
 ```
 
-Then you can get the first page of open orders by using the Order model:
+Then you can get the first page of open orders by calling the getOrders() method on the client
 ```php
-$reducedOrders = Picqer\BolRetailer\Order::all();
+$reducedOrders = $client->getOrders();
 
 foreach ($reducedOrders as $reducedOrder) {
     echo 'hello, I am order ' . $reducedOrder->orderId . PHP_EOL;
 }
 ```
 
-## Reduced orders and full orders
-In the list of orders, Bol only gives you a reduced amount of details per order. That is what we call a "reduced order". If you need all details of the order, retrieve the order by its id:
+## Exceptions
+Methods on the Client may throw Exceptions. All Exceptions have the parent class `Picqer\BolRetailer\Exception\Exception`:
+- `ConnectException` is thrown when a problem occurred in the connection (e.g. API server is down or a network issue). You may retry later.
+- `ServerException` (extends `ConnectException`) is thrown when a problem occurred on the Server (e.g. 500 Internal Server Error). You may retry later.
+- `ResponseException` is thrown when the received response could not be handled (e.g. not of proper format or unexpected type). Retrying will not help, investigation is needed.
+- `UnauthorizedException` is thrown when the server responded with 400 Unauthorized (e.g. invalid credentials).
+- `RateLimitException` is thrown when the throttling limit has been reached for the API user.
+- `Exception` is thrown when an error occurred in the HTTP library that is not covered by the cases above. We aim to map as much as possible to either `ConnectionException` or `ResponseException`.
 
-```php
-$order = Picqer\BolRetailer\Order::get($reducedOrder->orderId);
+## Generated Models and Client
+All the Models and Client are generated by the supplied [API specifications by Bol](https://api.bol.com/retailer/public/apispec/v4). By generating these this ensures no typos are made, not every operation needs a test and future (minor) updates to the specifications can easily be applied.
+
+The generated classes contain all data to properly map method arguments and response data to the models: the specifications are only used to generate them. 
+
+### Client
+The Client contains all operations specified in the specifications. The 'operationId' is converted to camelCase and used as method name for each operation.
+
+The specifications define types for each request and response (if it needs to send data). If a model for such a type encapsulates just one field, that model is abstracted from the operation have a smoother development experience:
+- A method in the Client accepts that field as argument instead of the model
+- A method in the Client returns the field from that model instead of the model itself
+
+To generate the Client, the following composer script may be used:
 ```
+# Generates Picqer\BolRetailer\Client
+composer run-script generate-client
+```
+
+### Models
+The class names for models are equal to the keys of the array 'definitions' in the specifications.
 
-## Supported modules
-At this moment, this client supports:
-- Offer
-- Order
-- ProcessStatus
-- ReturnItem
-- Shipment
+To generate the Models, the following composer script may be used:
+```
+# Generates all Picqer\BolRetailer\Model\* models
+composer run-script generate-models
+```
 
-## Examples
-See more examples in the [examples/](https://github.com/picqer/bol-retailer-php-client/tree/master/examples) directory.
+### Quirks
+- Some type definitions in de specifications are sentences, for example 'Delivery windows for inbound shipments.'. These are converted to CamelCase and dots are removed.
+- Some operations in the specifications have no response type specified, while there is a response. Currently, this is only the case for operations that return CSV.
+- There a type 'Return' defined in the specifications. As this is a reserved keyword in PHP, it can't be used as class name for the model (in PHP <= 7), so for now it's replaced with 'ReturnObject'.
+- If an array field in a response is empty, the field is (sometimes?) omitted from the response. E.g. the raw JSON response for getOrders is
+  ```
+  { }
+  ```
+  where you might expect 
+  ```
+  {
+    "orders": [ ]
+  }
+  ``` 
+- Operation 'Get all invoices' is specified to have a string as response, while there is clearly some data model returned in JSON or XML.

composer.json

@@ -19,7 +19,7 @@
     "require": {
         "php": "~7.1|^8.0",
         "ext-json": "*",
-        "guzzlehttp/guzzle": "^6.3"
+        "guzzlehttp/guzzle": "^6.3|^7.0"
     },
     "require-dev": {
         "phpstan/phpstan": "^0.12",
@@ -40,11 +40,13 @@
     "scripts": {
         "test": "phpunit",
         "check-style": "phpcs src tests",
-        "fix-style": "phpcbf src tests"
+        "fix-style": "phpcbf src tests",
+        "generate-client": "Picqer\\BolRetailer\\OpenApi\\ClientGenerator::run",
+        "generate-models": "Picqer\\BolRetailer\\OpenApi\\ModelGenerator::run"
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.0-dev"
+            "dev-master": "4.0-dev"
         }
     },
     "config": {

phpcs.xml.dist

@@ -11,4 +11,10 @@
 
     <!-- Use the PSR2 Standard-->
     <rule ref="PSR2" />
+    <rule ref="Generic.Files.LineLength">
+        <properties>
+            <property name="lineLimit" value="200"/>
+            <property name="absoluteLineLimit" value="0"/>
+        </properties>
+    </rule>
 </ruleset>

phpunit.xml.dist

@@ -10,7 +10,7 @@
          processIsolation="false"
          stopOnFailure="false">
     <testsuites>
-        <testsuite name="picqer Test Suite">
+        <testsuite name="all">
             <directory>tests</directory>
         </testsuite>
     </testsuites>