Support image and imageList item property types

Author: OndraFiedler

README.md

@@ -17,7 +17,7 @@ or
 ```
 {
     "require": {
-        "recombee/php-api-client": "^2.0.1"
+        "recombee/php-api-client": "^2.1.0"
     }
 }
 ```
@@ -79,30 +79,35 @@ $client->send(new Reqs\ResetDatabase()); //Clear everything from the database
 
 /*
 We will use computers as items in this example
-Computers have three properties 
+Computers have five properties 
   - price (floating point number)
   - number of processor cores (integer number)
   - description (string)
+  - date from which it is in stock (timestamp)
+  - image (url of computer's photo)
 */
 
 // Add properties of items
 $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'));
+$client->send(new Reqs\AddItemProperty('image', 'image'));
 
 # Prepare requests for setting a catalog of computers
 $requests = array();
 for($i=0; $i<NUM; $i++)
 {
+    $itemId = "computer-{$i}";
     $r = new Reqs\SetItemValues(
-      "computer-{$i}", //itemId
+      $itemId,
       //values:
       [ 
         'price' => rand(15000, 25000),
         'num-cores' => rand(1, 8),
         'description' => 'Great computer',
-        'in_stock_from' => new DateTime('NOW')
+        'in_stock_from' => new DateTime('NOW'),
+        'image' => "http://examplesite.com/products/{$itemId}.jpg"
       ],
       //optional parameters:
       ['cascadeCreate' => true] // Use cascadeCreate for creating item

src/RecommApi/Client.php

@@ -112,7 +112,7 @@ protected function getOptionalHttpHeaders() {
     }
 
     protected function getHttpHeaders() {
-        return array_merge(array('User-Agent' => 'recombee-php-api-client/2.0.1'), $this->getOptionalHttpHeaders()); 
+        return array_merge(array('User-Agent' => 'recombee-php-api-client/2.1.0'), $this->getOptionalHttpHeaders()); 
     }
 
     protected function getOptionalRequestOptions() {

src/RecommApi/Requests/AddItemProperty.php

@@ -19,14 +19,14 @@ class AddItemProperty extends Request {
      */
     protected $property_name;
     /**
-     * @var string $type Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+     * @var string $type Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
      */
     protected $type;
 
     /**
      * Construct the request
      * @param string $property_name Name of the item property to be created. Currently, the following names are reserved:`id`, `itemid`, case insensitively. Also, the length of the property name must not exceed 63 characters.
-     * @param string $type Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`
+     * @param string $type Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.
      */
     public function __construct($property_name, $type) {
         $this->property_name = $property_name;

src/RecommApi/Requests/DeleteViewPortion.php

@@ -10,7 +10,6 @@
 use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
 
 /**
- * The view portions feature is currently experimental.
  * Deletes an existing view portion specified by (`userId`, `itemId`, `sessionId`) from the database.
  */
 class DeleteViewPortion extends Request {

src/RecommApi/Requests/ItemBasedRecommendation.php

@@ -108,11 +108,11 @@ class ItemBasedRecommendation extends Request {
      */
     protected $min_relevance;
     /**
-     * @var float $rotation_rate **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.
+     * @var float $rotation_rate **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. Default: `0.01`.
      */
     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 recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     * @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. Default: `7200.0`.
      */
     protected $rotation_time;
     /**
@@ -204,10 +204,10 @@ class ItemBasedRecommendation extends Request {
      *         - Description: **Expert option** If the *targetUserId* is provided:  Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested qualit, and may return less than *count* items when there is not enough data to fulfill it.
      *     - *rotationRate*
      *         - Type: float
-     *         - 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.
+     *         - 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. Default: `0.01`.
      *     - *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 recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.
+     *         - 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. Default: `7200.0`.
      *     - *expertSettings*
      *         - Type: 
      *         - Description: Dictionary of custom options.

src/RecommApi/Requests/ListItemViewPortions.php

@@ -10,7 +10,6 @@
 use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
 
 /**
- * The view portions feature is currently experimental.
  * List all the view portions of an item ever submitted by different users.
  */
 class ListItemViewPortions extends Request {

src/RecommApi/Requests/ListUserViewPortions.php

@@ -10,7 +10,6 @@
 use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
 
 /**
- * The view portions feature is currently experimental.
  * List all the view portions ever submitted by a given user.
  */
 class ListUserViewPortions extends Request {

src/RecommApi/Requests/RecommendItemsToUser.php

@@ -106,11 +106,11 @@ class RecommendItemsToUser extends Request {
      */
     protected $min_relevance;
     /**
-     * @var float $rotation_rate **Expert option** 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.
+     * @var float $rotation_rate **Expert option** 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. Default: `0.1`.
      */
     protected $rotation_rate;
     /**
-     * @var float $rotation_time **Expert option** 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.
+     * @var float $rotation_time **Expert option** 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. Default: `7200.0`.
      */
     protected $rotation_time;
     /**
@@ -204,10 +204,10 @@ class RecommendItemsToUser extends Request {
      *         - Description: **Expert option** Specifies the threshold of how much relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend number of items equal to *count* at any cost. If there are not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full *count*. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevancy, and may return less than *count* items when there is not enough data to fulfill it.
      *     - *rotationRate*
      *         - Type: float
-     *         - Description: **Expert option** 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.
+     *         - Description: **Expert option** 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. Default: `0.1`.
      *     - *rotationTime*
      *         - Type: float
-     *         - Description: **Expert option** 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.
+     *         - Description: **Expert option** 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. Default: `7200.0`.
      *     - *expertSettings*
      *         - Type: 
      *         - Description: Dictionary of custom options.

src/RecommApi/Requests/SetViewPortion.php

@@ -10,7 +10,6 @@
 use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
 
 /**
- * The view portions feature is currently experimental.
  * Sets viewed portion of an item (for example a video or article) by a user (at a session).
  * If you send new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated.
  */
@@ -25,11 +24,11 @@ class SetViewPortion extends Request {
      */
     protected $item_id;
     /**
-     * @var float $portion Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ).
+     * @var float $portion Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.
      */
     protected $portion;
     /**
-     * @var string $session_id Id of session in which the user viewed the item
+     * @var string $session_id ID of session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc. depending on language).
      */
     protected $session_id;
     /**
@@ -49,12 +48,12 @@ class SetViewPortion extends Request {
      * Construct the request
      * @param string $user_id User who viewed a portion of the item
      * @param string $item_id Viewed item
-     * @param float $portion Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ).
+     * @param float $portion Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the really viewed part of the item, no matter seeking, so for example if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.
      * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value
      * - Allowed parameters:
      *     - *sessionId*
      *         - Type: string
-     *         - Description: Id of session in which the user viewed the item
+     *         - Description: ID of session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc. depending on language).
      *     - *timestamp*
      *         - Type: string|float
      *         - Description: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.