Added options parameter to read() method.

Author: judgej

README.md

@@ -30,6 +30,10 @@ Publish `config\odoo-api.php` using the Laravel artisan command:
 
 A sample set of entries for `.env` can be found in `.env.example`.
 
+You can add multiple sets of configuration to `config\odoo-api.php` and
+use them all at once in your application.
+The configuration set name is passed in to `OdooApi::getClient('config-name')`.
+
 # Example
 
 A very simple example:
@@ -71,6 +75,13 @@ $client->searchCount('res.partner', $criteria);
 $client->read('res.partner', [17858, 17852])->value()->me['array']
 ```
 
+If you have specific requirements for the XML-RPC client, such as an SSL
+certificate to add, then yiu can get the client instance using:
+
+    $xmlRpcClient = $client->getXmlRpcClient($type);
+
+where `$type` will typically be 'db', 'common' or 'object'.
+
 # Query methods
 
 The following methods are supported and will return an XML-RPC response:
@@ -87,17 +98,31 @@ The following helper functions return a native PHp type insead:
 * searchCount - integer
 * getResourceId - integer
 
+(I'm torn between this approach and a more fluent approach such as
+`$client->firstOnly()->asArray()->read(...)`)
+
 Note that `searchRead` will emulate the server's `search_read` for
 Odoo versions less than 8.0 (OpenERP) but use the native `search_read`
 for Odoo 8.0 upwards.
 
+# Read Options
+
+The `read()` method takes an options array that varies significantly
+between OpenERP/Odoo versions.
+This package does not attempt to deal with that at this time.
+
+Fpor example, to restrict the read to named attributes, the following
+formats are used:
+
+* OpenERP 7: $client->read('account.invoice', [123], ['type', 'partner_id']);
+* OpenERP 8: $client->read('account.invoice', [123], ['fields' => ['type', 'partner_id']]);
+* OpenERP 10: $client->read('account.invoice', [123], ['attributes' => ['type', 'partner_id']]);
+
+This makes finding help on the API difficult, since many articles
+fail to make the OpenERP/Odoo version number clear.
+
 # TODO
 
-* An elegant way to parse the results, as the `Value` objects can be
-  a little cumbersome.
-  For example, we know the `search()` result will be an array of
-  integer model instance IDs, so a simple array or collection of IDs can
-  be returned, rather than a Value array containing Value integer objects.
 * Docs on config (this package supports multiple clients, so can connect
   to multiple Odoo instances or as multiple users at the same time).
 * Docs on installation (has a auto discovered provider and facade).

src/OdooClient.php

@@ -29,7 +29,7 @@ class OdooClient
     const DEFAULT_LIMIT = 100;
 
     /**
-     *
+     * Later versions of the API include a version number e.g. /xmlrpc/2/
      */
     protected $endpointTemplate = '{uri}/xmlrpc/{type}';
 
@@ -75,16 +75,19 @@ public function __construct(array $config)
     }
 
     /**
-     * Get an XML ROC client singleton of a particular type.
+     * Get an XML RRC client singleton of a particular type.
+     *
+     * @param string $type One of: 'common', 'object', 'db'
+     * @return Client 
      */
     public function getXmlRpcClient(string $type)
     {
+        $type = strtolower($type);
+
         if (array_key_exists($type, $this->xmlRpcClients)) {
             return $this->xmlRpcClients[$type];
         }
 
-        $type = strtolower($type);
-
         $endpoint = str_replace(
             ['{uri}', '{type}'],
             [$this->url, $type],
@@ -343,17 +346,24 @@ public function searchReadArray(
     }
 
     /**
+     * @param string $modelName example res.partner
      * @param array $instanceIds list of model instance IDs to read and return
+     * @param array $options varies with API versions see documentation
      * @return Response
      */
     public function read(
         string $modelName,
-        array $instanceIds = []
+        array $instanceIds = [],
+        array $options = []
     ) {
         $msg = $this->getBaseObjectRequest($modelName, 'read');
 
         $msg->addParam($this->nativeToValue($instanceIds));
 
+        if (! empty($options)) {
+            $msg->addParam($this->nativeToValue($options));
+        }
+
         $response = $this->getXmlRpcClient('object')->send($msg);
 
         return $response;
@@ -364,11 +374,13 @@ public function read(
      */
     public function readArray(
         string $modelName,
-        array $instanceIds = []
+        array $instanceIds = [],
+        array $options = []
     ) {
         $response = $this->read(
             $modelName,
-            $instanceIds
+            $instanceIds,
+            $options
         );
 
         if ($response->value() instanceof Value) {
@@ -405,6 +417,9 @@ public function version()
 
     /**
      * Get the ERP internal resource ID for a given external ID.
+     * This in thoery kind of belongs in a wrapper to the client,
+     * but is used so often in data syncs that it makes sense having
+     * it here.
      *
      * @param string $externalId either "name" or "module.name"
      * @param string $module optional, but recommended