Added support for user properties. Automatically split Batch with more than 10k requests to multiple Batch requests. Added cascadeCreate parameter to Set item/user values.

Author: OndraFiedler

README.md

@@ -17,7 +17,7 @@ or
 ```
 {
     "require": {
-        "recombee/php-api-client": ">=1.2.5"
+        "recombee/php-api-client": ">=1.3"
     }
 }
 ```
@@ -30,52 +30,36 @@ use Recombee\RecommApi\Client;
 use Recombee\RecommApi\Requests as Reqs;
 use Recombee\RecommApi\Exceptions as Ex;
 
-const NUM = 100;
-const PROBABILITY_PURCHASED = 0.01;
-
-// Prepare some users and items
-$my_user_ids = array();
-$my_item_ids = array();
-for($i=0; $i < NUM; $i++) {
-    array_push($my_user_ids, "user-{$i}");
-    array_push($my_item_ids, "item-{$i}");
-}
-
-// Generate some random purchases of items by users
-$my_purchases = array();
-foreach ($my_user_ids as $user_id) {
-    foreach ($my_item_ids as $item_id) {
-        if(mt_rand() / mt_getrandmax() < PROBABILITY_PURCHASED)
-            array_push($my_purchases, ['user'=>$user_id, 'item'=>$item_id]);
-    }
-}
-
-// Use Recombee recommender
 $client = new Client('client-test', 'jGGQ6ZKa8rQ1zTAyxTc0EMn55YPF7FJLUtaMLhbsGxmvwxgTwXYqmUk5xVZFw98L');
 
+const NUM = 100;
+const PROBABILITY_PURCHASED = 0.1;
+
 try
 {
-    $client->send(new Reqs\ResetDatabase()); //Clear everything from the database
-
-    //Create requests and send the data to Recombee, use Batch for faster processing
-    echo "Send users\n";
-    $user_requests = array_map(function($userId) {return new Reqs\AddUser($userId);}, $my_user_ids);
-    $client->send(new Reqs\Batch($user_requests));
-
-    echo "Send items\n";
-    $item_requests = array_map(function($itemId) {return new Reqs\AddItem($itemId);}, $my_item_ids);
-    $client->send(new Reqs\Batch($item_requests));
-
+    // Generate some random purchases of items by users
+    $purchase_requests = array();
+    for($i=0; $i < NUM; $i++) {
+        for($j=0; $j < NUM; $j++) {
+            if(mt_rand() / mt_getrandmax() < PROBABILITY_PURCHASED) {
+
+                $request = new Reqs\AddPurchase("user-{$i}", "item-{$j}",
+                    ['cascadeCreate' => true] // Use cascadeCreate to create the
+                                              // yet non-existing users and items
+                );
+                array_push($purchase_requests, $request);
+            }
+        }
+    }
     echo "Send purchases\n";
-    $purchase_requests = array_map(function($tuple)
-                        {return new Reqs\AddPurchase($tuple['user'], $tuple['item']);}, $my_purchases);
-    $client->send(new Reqs\Batch($purchase_requests));
+    $res = $client->send(new Reqs\Batch($purchase_requests)); //Use Batch for faster processing of larger data
 
     // Get 5 recommendations for user 'user-25'
-    $recommended = $client->send(new Reqs\UserBasedRecommendation('user-25', 5, ['rotationRate' => 0]));
+    $recommended = $client->send(new Reqs\UserBasedRecommendation('user-25', 5));
+
     echo 'Recommended items: ' . implode(',',$recommended) . "\n";
 }
-catch(Ex\ApiException $e)
+catch(Ex\ApiTimeoutException $e)
 {
     //use fallback
 }
@@ -105,6 +89,7 @@ Computers have three properties
 $client->send(new Reqs\AddItemProperty('price', 'double'));
 $client->send(new Reqs\AddItemProperty('num-cores', 'int'));
 $client->send(new Reqs\AddItemProperty('description', 'string'));
+$client->send(new Reqs\AddItemProperty('in_stock_from', 'timestamp'));
 
 # Prepare requests for setting a catalog of computers
 $requests = array();
@@ -117,15 +102,18 @@ for($i=0; $i<NUM; $i++)
         'price' => rand(15000, 25000),
         'num-cores' => rand(1, 8),
         'description' => 'Great computer',
-        '!cascadeCreate' => true // Use !cascadeCreate for creating item
-                                 // with given itemId, if it doesn't exist
-      ]
+        'in_stock_from' => new DateTime('NOW')
+      ],
+      //optional parameters:
+      ['cascadeCreate' => true] // Use cascadeCreate for creating item
+                                 // with given itemId, if it doesn't exist]
     );
     array_push($requests, $r);
 }
 
 // Send catalog to the recommender system
-$client->send(new Reqs\Batch($requests));
+$result =  $client->send(new Reqs\Batch($requests));
+var_dump($result);
 
 // Generate some random purchases of items by users
 $requests = array();
@@ -137,23 +125,21 @@ for($i=0; $i<NUM; $i++)
            $r = new Reqs\AddPurchase("user-{$i}", "computer-{$j}", ['cascadeCreate' => true]);
            array_push($requests, $r);
         }
-        
+
 // Send purchases to the recommender system
 $client->send(new Reqs\Batch($requests));
 
-// Get 5 recommendations for user-42, who is currently viewing computer-6
+// Get 5 items related to item computer-6. Personalize them for user-42, who is currently viewing that item.
 $recommended = $client->send(new Reqs\ItemBasedRecommendation('computer-6', 5, ['targetUserId' => 'user-42']));
 echo 'Recommended items: ' . implode(',',$recommended) . "\n";
 
-// Get 5 recommendations for user-42, but recommend only computers that
-// have at least 3 cores
+// Recommend only computers that have at least 3 cores
 $recommended = $client->send(
   new Reqs\ItemBasedRecommendation('computer-6', 5, ['targetUserId' => 'user-42', 'filter' => "'num-cores'>=3"])
   );
 echo 'Recommended items with at least 3 processor cores: ' . implode(',',$recommended) . "\n";
 
-// Get 5 recommendations for user-42, but recommend only items that
-// are more expensive then currently viewed item (up-sell)
+// Recommend only items that are more expensive then currently viewed item computer-6 (up-sell)
 $recommended = $client->send(
   new Reqs\ItemBasedRecommendation('computer-6', 5,
     ['targetUserId' => 'user-42', 'filter' => "'price' > context_item[\"price\"]"])

composer.json

@@ -11,7 +11,7 @@
     ],
     "require": {
       "php": ">=5.4.0",
-      "rmccue/requests": ">=1.0"
+      "rmccue/requests": ">=1.7"
     },
     "require-dev": {
         "phpunit/phpunit": ">=4",

phpdoc.dist.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<phpdoc>
+<phpdocumentor>
 	<title>Recombee API client</title>
 	<transformations>
 		<template name="responsive-twig"/>
@@ -13,4 +13,4 @@
     <files>
         <directory>src</directory>
     </files>
-</phpdoc>
+</phpdocumentor>

src/RecommApi/Client.php

@@ -27,6 +27,11 @@ class Client{
      */
     const BASE_URI = 'rapi.recombee.com';
 
+    /**
+     * @ignore
+     */
+    const BATCH_MAX_SIZE = 10000; //Maximal number of requests within one batch request
+
     /**
      * Create the client
      * @param string $account Name of your account at Recombee
@@ -49,6 +54,10 @@ public function __construct($account, $token, $protocol = 'http') {
      * @throws Exceptions\ApiTimeoutException ApiTimeoutException if the request takes too long
      */
     public function send(Requests\Request $request) {
+        
+        if($request instanceof Requests\Batch && count($request->requests) > Client::BATCH_MAX_SIZE)
+            return $this->sendMultipartBatch($request);
+
         $this->request = $request;
         $path = Util::sliceDbName($request->getPath());
         $request_url =  $path . $this->paramsToUrl($request->getQueryParameters());
@@ -81,35 +90,35 @@ public function send(Requests\Request $request) {
         catch(\Requests_Exception $e)
         {
             if(strpos($e->getMessage(), 'cURL error 28') !== false) throw new ApiTimeoutException($request);
+            if(strpos($e->getMessage(), 'fsocket timed out') !== false) throw new ApiTimeoutException($request);
             throw $e;
         }
 
         return $result;
     }
 
     /* ----------------------- Send requests -----------------------  */
-    //TODO remove ceils when Requests 1.7 is released as it support timeout in milliseconds
     protected function put($uri, $timeout) {
-        $response = \Requests::put($uri, array(), ['timeout' => ceil($timeout)]);
+        $response = \Requests::put($uri, array(), ['timeout' => $timeout]);
         $this->checkErrors($response);
         return $response->body;
     }
 
     protected function get($uri, $timeout) {
-        $response = \Requests::get($uri, array(), ['timeout' => ceil($timeout)]);
+        $response = \Requests::get($uri, array(), ['timeout' => $timeout]);
         $this->checkErrors($response);
         return json_decode($response->body, true);
     }
 
     protected function delete($uri, $timeout) {
-        $response = \Requests::delete($uri, array(), ['timeout' => ceil($timeout)]);
+        $response = \Requests::delete($uri, array(), ['timeout' => $timeout]);
         $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' => ceil($timeout)]);
+        $response = \Requests::post($uri, $headers, $body, ['timeout' => $timeout]);
         $this->checkErrors($response);
 
         $json = json_decode($response->body, true);
@@ -125,6 +134,15 @@ protected function checkErrors($response) {
         throw new ResponseException($this->request, $status_code, $response->body);
     }
 
+    protected function sendMultipartBatch($request) {
+        $chunks = array_chunk($request->requests, Client::BATCH_MAX_SIZE);
+        $responses = array();
+        foreach ($chunks as $rqs) {
+            array_push($responses, $this->send(new Requests\Batch($rqs)));
+        }
+        return array_reduce($responses, 'array_merge', array());
+    }
+
     /* ----------------------- HMAC -----------------------  */
 
     protected function signUrl($uri) {

src/RecommApi/Requests/AddUserProperty.php

@@ -0,0 +1,74 @@
+<?php
+/*
+ This file is auto-generated, do not edit
+*/
+
+/**
+ * AddUserProperty request
+ */
+namespace Recombee\RecommApi\Requests;
+use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
+
+/**
+ * Adding an user property is somehow equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.
+ */
+class AddUserProperty extends Request {
+
+    /**
+     * @var string $property_name Name of the user property to be created. Currently, the following names are reserved:`id`, `userid`, case insensitively. Also, the length of the property name must not exceed 63 characters.
+     */
+    protected $property_name;
+    /**
+     * @var string $type Value type of the user property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+     */
+    protected $type;
+
+    /**
+     * Construct the request
+     * @param string $property_name Name of the user property to be created. Currently, the following names are reserved:`id`, `userid`, case insensitively. Also, the length of the property name must not exceed 63 characters.
+     * @param string $type Value type of the user property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+     */
+    public function __construct($property_name, $type) {
+        $this->property_name = $property_name;
+        $this->type = $type;
+        $this->timeout = 1000;
+        $this->ensure_https = false;
+    }
+
+    /**
+     * Get used HTTP method
+     * @return static Used HTTP method
+     */
+    public function getMethod() {
+        return Request::HTTP_PUT;
+    }
+
+    /**
+     * Get URI to the endpoint
+     * @return string URI to the endpoint
+     */
+    public function getPath() {
+        return "/{databaseId}/users/properties/{$this->property_name}";
+    }
+
+    /**
+     * Get query parameters
+     * @return array Values of query parameters (name of parameter => value of the parameter)
+     */
+    public function getQueryParameters() {
+        $params = array();
+        $params['type'] = $this->type;
+        return $params;
+    }
+
+    /**
+     * Get body parameters
+     * @return array Values of body parameters (name of parameter => value of the parameter)
+     */
+    public function getBodyParameters() {
+        $p = array();
+        return $p;
+    }
+
+}
+?>

src/RecommApi/Requests/Batch.php

@@ -16,7 +16,6 @@
  * - executing the requests in a batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible,
  * - the status code of the batch request itself is 200 even if the individual requests result in error – you have to inspect the code values in the resulting array,
  * - if the status code of the whole batch is not 200, then there is an error in the batch request itself; in such a case, the error message returned should help you to resolve the problem,
- * - currently, batch size is limited to **10,000** requests; if you wish to execute even larger number of requests, please split the batch into multiple parts.
  */
 class Batch extends Request {
 

src/RecommApi/Requests/DeleteUserProperty.php

@@ -0,0 +1,67 @@
+<?php
+/*
+ This file is auto-generated, do not edit
+*/
+
+/**
+ * DeleteUserProperty request
+ */
+namespace Recombee\RecommApi\Requests;
+use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
+
+/**
+ * Deleting an user property is roughly equivalent to removing a column from the table of users.
+ */
+class DeleteUserProperty extends Request {
+
+    /**
+     * @var string $property_name Name of the property to be deleted.
+     */
+    protected $property_name;
+
+    /**
+     * Construct the request
+     * @param string $property_name Name of the property to be deleted.
+     */
+    public function __construct($property_name) {
+        $this->property_name = $property_name;
+        $this->timeout = 1000;
+        $this->ensure_https = false;
+    }
+
+    /**
+     * Get used HTTP method
+     * @return static Used HTTP method
+     */
+    public function getMethod() {
+        return Request::HTTP_DELETE;
+    }
+
+    /**
+     * Get URI to the endpoint
+     * @return string URI to the endpoint
+     */
+    public function getPath() {
+        return "/{databaseId}/users/properties/{$this->property_name}";
+    }
+
+    /**
+     * Get query parameters
+     * @return array Values of query parameters (name of parameter => value of the parameter)
+     */
+    public function getQueryParameters() {
+        $params = array();
+        return $params;
+    }
+
+    /**
+     * Get body parameters
+     * @return array Values of body parameters (name of parameter => value of the parameter)
+     */
+    public function getBodyParameters() {
+        $p = array();
+        return $p;
+    }
+
+}
+?>