Support returnProperties and includedProperties parameters of ListItems and ListUsers. Send User-Agent HTTP header. Use POST for recomm requests.

Author: OndraFiedler

README.md

@@ -17,7 +17,7 @@ or
 ```
 {
     "require": {
-        "recombee/php-api-client": "^1.3.2"
+        "recombee/php-api-client": "^1.4.0"
     }
 }
 ```

composer.json

@@ -10,11 +10,11 @@
         }
     ],
     "require": {
-      "php": ">=5.4.0",
+      "php": ">=5.3.0",
       "rmccue/requests": "^1.7.0"
     },
     "require-dev": {
-        "phpunit/phpunit": ">=4",
+        "phpunit/phpunit": "^6.1.0",
         "phpdocumentor/phpdocumentor": "2.*"
     },
     "autoload": {

src/RecommApi/Client.php

@@ -21,6 +21,7 @@ class Client{
     protected $request;
     protected $protocol;
     protected $base_uri;
+    protected $options;
 
     /**
      * @ignore
@@ -37,14 +38,16 @@ class Client{
      * @param string $account Name of your account at Recombee
      * @param string $token Secret token
      * @param string $protocol Default protocol for sending requests. Possible values: 'http', 'https'.
+     * @param array  $options Other custom options
      */
-    public function __construct($account, $token, $protocol = 'http') {
+    public function __construct($account, $token, $protocol = 'http', $options= array()) {
         $this->account = $account;
         $this->token = $token;
         $this->protocol = $protocol;
         $this->base_uri = Client::BASE_URI;
         if(getenv("RAPI_URI") !== false)
             $this->base_uri = getenv("RAPI_URI");
+        $this->options = $options;
     }
 
     /**
@@ -74,7 +77,8 @@ public function send(Requests\Request $request) {
                     break;
 
                 case Requests\Request::HTTP_PUT:
-                    $result = $this->put($uri, $timeout);
+                    $json = json_encode($request->getBodyParameters(), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+                    $result = $this->put($uri, $timeout, $json);
                     break;
 
                 case Requests\Request::HTTP_DELETE:
@@ -101,27 +105,53 @@ public function send(Requests\Request $request) {
     }
 
     /* ----------------------- Send requests -----------------------  */
-    protected function put($uri, $timeout) {
-        $response = \Requests::put($uri, array(), ['timeout' => $timeout]);
+    protected function getOptionalHttpHeaders() {
+        if (isset($this->options['requestsHeaders']))
+            return $this->options['requestsHeaders'];
+        return array();
+    }
+
+    protected function getHttpHeaders() {
+        return array_merge(array('User-Agent' => 'recombee-php-api-client/1.4.0'), $this->getOptionalHttpHeaders()); 
+    }
+
+    protected function getOptionalRequestOptions() {
+        if (isset($this->options['requestsOptions']))
+            return $this->options['requestsOptions'];
+        return array();
+    }
+
+    protected function put($uri, $timeout, $body) {
+        $options = array_merge(array('timeout' => $timeout), $this->getOptionalRequestOptions());
+        $headers = array_merge(array('Content-Type' => 'application/json'), $this->getHttpHeaders());
+
+        $response = \Requests::put($uri, $headers, $body, $options);
         $this->checkErrors($response);
         return $response->body;
     }
 
     protected function get($uri, $timeout) {
-        $response = \Requests::get($uri, array(), ['timeout' => $timeout]);
+        $options = array_merge(array('timeout' => $timeout), $this->getOptionalRequestOptions());
+        $headers = $this->getHttpHeaders();
+
+        $response = \Requests::get($uri, $headers, $options);
         $this->checkErrors($response);
         return json_decode($response->body, true);
     }
 
     protected function delete($uri, $timeout) {
-        $response = \Requests::delete($uri, array(), ['timeout' => $timeout]);
+        $options = array_merge(array('timeout' => $timeout), $this->getOptionalRequestOptions());
+        $headers = $this->getHttpHeaders();
+
+        $response = \Requests::delete($uri, $headers, $options);
         $this->checkErrors($response);
         return $response->body;
     }
 
     protected function post($uri, $timeout, $body) {
-        $headers = array('Content-Type' => 'application/json');
-        $response = \Requests::post($uri, $headers, $body, ['timeout' => $timeout]);
+        $options = array_merge(array('timeout' => $timeout), $this->getOptionalRequestOptions());
+        $headers = array_merge(array('Content-Type' => 'application/json'), $this->getHttpHeaders());
+        $response = \Requests::post($uri, $headers, $body, $options);
         $this->checkErrors($response);
 
         $json = json_decode($response->body, true);

src/RecommApi/Requests/ItemBasedRecommendation.php

@@ -11,11 +11,12 @@
 
 /**
  * Recommends set of items that are somehow related to one given item, *X*. Typical scenario for using item-based recommendation is when user *A* is viewing *X*. Then you may display items to the user that he might be also interested in. Item-recommendation request gives you Top-N such items, optionally taking the target user *A* into account.
+ *  It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
  */
 class ItemBasedRecommendation extends Request {
 
     /**
-     * @var string $item_id ID of the item recommendations for which are to be generated.
+     * @var string $item_id ID of the item for which the recommendations are to be generated.
      */
     protected $item_id;
     /**
@@ -32,7 +33,7 @@ class ItemBasedRecommendation extends Request {
      */
     protected $target_user_id;
     /**
-     * @var float $user_impact If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0.1`
+     * @var float $user_impact If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`.
      */
     protected $user_impact;
     /**
@@ -110,17 +111,21 @@ class ItemBasedRecommendation extends Request {
      */
     protected $rotation_rate;
     /**
-     * @var float $rotation_time **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. For example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour.
+     * @var float $rotation_time **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
      */
     protected $rotation_time;
+    /**
+     * @var  $expert_settings Dictionary of custom options.
+     */
+    protected $expert_settings;
     /**
      * @var array Array containing values of optional parameters
      */
    protected $optional;
 
     /**
      * Construct the request
-     * @param string $item_id ID of the item recommendations for which are to be generated.
+     * @param string $item_id ID of the item for which the recommendations are to be generated.
      * @param int $count Number of items to be recommended (N for the top-N recommendation).
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
@@ -134,7 +139,7 @@ class ItemBasedRecommendation extends Request {
      * For the above reasons, we encourage you to set the *targetUserId* even for anonymous/unregistered users (i.e. use their session ID).
      *     - *userImpact*
      *         - Type: float
-     *         - Description: If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0.1`
+     *         - Description: If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`.
      *     - *filter*
      *         - Type: string
      *         - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes.
@@ -201,7 +206,10 @@ class ItemBasedRecommendation extends Request {
      *         - Description: **Expert option** If the *targetUserId* is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per-request in backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example `rotationRate=0.2` for only slight rotation of recommended items.
      *     - *rotationTime*
      *         - Type: float
-     *         - Description: **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to fully recover from the penalization. For example, `rotationTime=7200.0` means that items recommended more than 2 hours ago are definitely not penalized anymore. Currently, the penalization is linear, so for `rotationTime=7200.0`, an item is still penalized by `0.5` to the user after 1 hour.
+     *         - Description: **Expert option** If the *targetUserId* is provided: Taking *rotationRate* into account, specifies how long time it takes to an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     *     - *expertSettings*
+     *         - Type: 
+     *         - Description: Dictionary of custom options.
      * @throws Exceptions\UnknownOptionalParameterException UnknownOptionalParameterException if an unknown optional parameter is given in $optional
      */
     public function __construct($item_id, $count, $optional = array()) {
@@ -220,9 +228,10 @@ public function __construct($item_id, $count, $optional = array()) {
         $this->min_relevance = isset($optional['minRelevance']) ? $optional['minRelevance'] : null;
         $this->rotation_rate = isset($optional['rotationRate']) ? $optional['rotationRate'] : null;
         $this->rotation_time = isset($optional['rotationTime']) ? $optional['rotationTime'] : null;
+        $this->expert_settings = isset($optional['expertSettings']) ? $optional['expertSettings'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('targetUserId','userImpact','filter','booster','allowNonexistent','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime');
+        $existing_optional = array('targetUserId','userImpact','filter','booster','allowNonexistent','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -236,7 +245,7 @@ public function __construct($item_id, $count, $optional = array()) {
      * @return static Used HTTP method
      */
     public function getMethod() {
-        return Request::HTTP_GET;
+        return Request::HTTP_POST;
     }
 
     /**
@@ -253,42 +262,44 @@ public function getPath() {
      */
     public function getQueryParameters() {
         $params = array();
-        $params['count'] = $this->count;
+        return $params;
+    }
+
+    /**
+     * Get body parameters
+     * @return array Values of body parameters (name of parameter => value of the parameter)
+     */
+    public function getBodyParameters() {
+        $p = array();
+        $p['count'] = $this->count;
         if (isset($this->optional['targetUserId']))
-            $params['targetUserId'] = $this->optional['targetUserId'];
+             $p['targetUserId'] = $this-> optional['targetUserId'];
         if (isset($this->optional['userImpact']))
-            $params['userImpact'] = $this->optional['userImpact'];
+             $p['userImpact'] = $this-> optional['userImpact'];
         if (isset($this->optional['filter']))
-            $params['filter'] = $this->optional['filter'];
+             $p['filter'] = $this-> optional['filter'];
         if (isset($this->optional['booster']))
-            $params['booster'] = $this->optional['booster'];
+             $p['booster'] = $this-> optional['booster'];
         if (isset($this->optional['allowNonexistent']))
-            $params['allowNonexistent'] = $this->optional['allowNonexistent'];
+             $p['allowNonexistent'] = $this-> optional['allowNonexistent'];
         if (isset($this->optional['cascadeCreate']))
-            $params['cascadeCreate'] = $this->optional['cascadeCreate'];
+             $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         if (isset($this->optional['scenario']))
-            $params['scenario'] = $this->optional['scenario'];
+             $p['scenario'] = $this-> optional['scenario'];
         if (isset($this->optional['returnProperties']))
-            $params['returnProperties'] = $this->optional['returnProperties'];
+             $p['returnProperties'] = $this-> optional['returnProperties'];
         if (isset($this->optional['includedProperties']))
-            $params['includedProperties'] = $this->optional['includedProperties'];
+             $p['includedProperties'] = $this-> optional['includedProperties'];
         if (isset($this->optional['diversity']))
-            $params['diversity'] = $this->optional['diversity'];
+             $p['diversity'] = $this-> optional['diversity'];
         if (isset($this->optional['minRelevance']))
-            $params['minRelevance'] = $this->optional['minRelevance'];
+             $p['minRelevance'] = $this-> optional['minRelevance'];
         if (isset($this->optional['rotationRate']))
-            $params['rotationRate'] = $this->optional['rotationRate'];
+             $p['rotationRate'] = $this-> optional['rotationRate'];
         if (isset($this->optional['rotationTime']))
-            $params['rotationTime'] = $this->optional['rotationTime'];
-        return $params;
-    }
-
-    /**
-     * Get body parameters
-     * @return array Values of body parameters (name of parameter => value of the parameter)
-     */
-    public function getBodyParameters() {
-        $p = array();
+             $p['rotationTime'] = $this-> optional['rotationTime'];
+        if (isset($this->optional['expertSettings']))
+             $p['expertSettings'] = $this-> optional['expertSettings'];
         return $p;
     }
 

src/RecommApi/Requests/ListGroups.php

@@ -19,7 +19,7 @@ class ListGroups extends Request {
      * Construct the request
      */
     public function __construct() {
-        $this->timeout = 30000;
+        $this->timeout = 239000;
         $this->ensure_https = false;
     }
 

src/RecommApi/Requests/ListItemBookmarks.php

@@ -25,7 +25,7 @@ class ListItemBookmarks extends Request {
      */
     public function __construct($item_id) {
         $this->item_id = $item_id;
-        $this->timeout = 1000;
+        $this->timeout = 100000;
         $this->ensure_https = false;
     }
 

src/RecommApi/Requests/ListItemCartAdditions.php

@@ -25,7 +25,7 @@ class ListItemCartAdditions extends Request {
      */
     public function __construct($item_id) {
         $this->item_id = $item_id;
-        $this->timeout = 1000;
+        $this->timeout = 100000;
         $this->ensure_https = false;
     }
 

src/RecommApi/Requests/ListItemDetailViews.php

@@ -25,7 +25,7 @@ class ListItemDetailViews extends Request {
      */
     public function __construct($item_id) {
         $this->item_id = $item_id;
-        $this->timeout = 1000;
+        $this->timeout = 100000;
         $this->ensure_https = false;
     }
 

src/RecommApi/Requests/ListItemPurchases.php

@@ -25,7 +25,7 @@ class ListItemPurchases extends Request {
      */
     public function __construct($item_id) {
         $this->item_id = $item_id;
-        $this->timeout = 1000;
+        $this->timeout = 100000;
         $this->ensure_https = false;
     }
 

src/RecommApi/Requests/ListItemRatings.php

@@ -25,7 +25,7 @@ class ListItemRatings extends Request {
      */
     public function __construct($item_id) {
         $this->item_id = $item_id;
-        $this->timeout = 1000;
+        $this->timeout = 100000;
         $this->ensure_https = false;
     }