Release: v6.2.0

- Added recommend-next-item-segments endpoint support
- Added `searchQuery` parameter support for composite recommendations

Author: MichalDemko

README.md

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

src/RecommApi/Client.php

@@ -92,7 +92,7 @@ protected function getBaseUri() {
     }
 
     protected function getUserAgent() {
-        $user_agent = 'recombee-php-api-client/6.1.0';
+        $user_agent = 'recombee-php-api-client/6.2.0';
         if (isset($this->options['serviceName']))
             $user_agent .= ' '.($this->options['serviceName']);
         return $user_agent;

src/RecommApi/Requests/CompositeRecommendation.php

@@ -10,7 +10,7 @@
 use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
 
 /**
- * Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations.html)) and a list of related recommendations in a single response.
+ * Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response.
  * It is ideal for use cases such as personalized homepage sections (*Articles from <category>*), *Because You Watched <movie>*, or *Artists Related to Your Favorite Artist <artist>*.
  * See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).
  * **Structure**
@@ -60,6 +60,10 @@ class CompositeRecommendation extends Request {
      * @var string $segment_id ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
      */
     protected $segment_id;
+    /**
+     * @var string $search_query Search query provided by the user. It is used for the full-text search. Only applicable if the *scenario* corresponds to a search scenario.
+     */
+    protected $search_query;
     /**
      * @var bool $cascade_create If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.
      */
@@ -104,6 +108,9 @@ class CompositeRecommendation extends Request {
      *     - *segmentId*
      *         - Type: string
      *         - Description: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.
+     *     - *searchQuery*
+     *         - Type: string
+     *         - Description: Search query provided by the user. It is used for the full-text search. Only applicable if the *scenario* corresponds to a search scenario.
      *     - *cascadeCreate*
      *         - Type: bool
      *         - Description: If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.
@@ -125,13 +132,14 @@ public function __construct($scenario, $count, $optional = array()) {
         $this->user_id = isset($optional['userId']) ? $optional['userId'] : null;
         $this->logic = isset($optional['logic']) ? $optional['logic'] : null;
         $this->segment_id = isset($optional['segmentId']) ? $optional['segmentId'] : null;
+        $this->search_query = isset($optional['searchQuery']) ? $optional['searchQuery'] : null;
         $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null;
         $this->source_settings = isset($optional['sourceSettings']) ? $optional['sourceSettings'] : null;
         $this->result_settings = isset($optional['resultSettings']) ? $optional['resultSettings'] : null;
         $this->expert_settings = isset($optional['expertSettings']) ? $optional['expertSettings'] : null;
         $this->optional = $optional;
 
-        $existing_optional = array('itemId','userId','logic','segmentId','cascadeCreate','sourceSettings','resultSettings','expertSettings');
+        $existing_optional = array('itemId','userId','logic','segmentId','searchQuery','cascadeCreate','sourceSettings','resultSettings','expertSettings');
         foreach ($this->optional as $key => $value) {
             if (!in_array($key, $existing_optional))
                  throw new UnknownOptionalParameterException($key);
@@ -181,6 +189,8 @@ public function getBodyParameters() {
              $p['logic'] = $this-> optional['logic'];
         if (isset($this->optional['segmentId']))
              $p['segmentId'] = $this-> optional['segmentId'];
+        if (isset($this->optional['searchQuery']))
+             $p['searchQuery'] = $this-> optional['searchQuery'];
         if (isset($this->optional['cascadeCreate']))
              $p['cascadeCreate'] = $this-> optional['cascadeCreate'];
         if (isset($this->optional['sourceSettings']))

src/RecommApi/Requests/RecommendNextItemSegments.php

@@ -0,0 +1,84 @@
+<?php
+/*
+ This file is auto-generated, do not edit
+*/
+
+/**
+ * RecommendNextItemSegments request
+ */
+namespace Recombee\RecommApi\Requests;
+use Recombee\RecommApi\Exceptions\UnknownOptionalParameterException;
+
+/**
+ * Returns Item segments that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to the next page.
+ * It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of segments that shall be returned (`count`).
+ * The base request can be one of:
+ *   - [Recommend Item Segments to Item](https://docs.recombee.com/api#recommend-item-segments-to-item)
+ *   - [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user)
+ *   - [Recommend Item Segments to Item Segment](https://docs.recombee.com/api#recommend-item-segments-to-item-segment)
+ *   - [Search Item Segments](https://docs.recombee.com/api#search-item-segments)
+ * All the other parameters are inherited from the base request.
+ * *Recommend next Item segments* can be called many times for a single `recommId` and each call returns different (previously not recommended) segments.
+ * The number of *Recommend next Item segments* calls performed so far is returned in the `numberNextRecommsCalls` field.
+ * *Recommend next Item segments* can be requested up to 30 minutes after the base request or a previous *Recommend next Item segments* call.
+ * For billing purposes, each call to *Recommend next Item segments* is counted as a separate recommendation request.
+ */
+class RecommendNextItemSegments extends Request {
+
+    /**
+     * @var string $recomm_id ID of the base recommendation request for which next recommendations should be returned
+     */
+    protected $recomm_id;
+    /**
+     * @var int $count Number of item segments to be recommended
+     */
+    protected $count;
+
+    /**
+     * Construct the request
+     * @param string $recomm_id ID of the base recommendation request for which next recommendations should be returned
+     * @param int $count Number of item segments to be recommended
+     */
+    public function __construct($recomm_id, $count) {
+        $this->recomm_id = $recomm_id;
+        $this->count = $count;
+        $this->timeout = 3000;
+        $this->ensure_https = false;
+    }
+
+    /**
+     * Get used HTTP method
+     * @return static Used HTTP method
+     */
+    public function getMethod() {
+        return Request::HTTP_POST;
+    }
+
+    /**
+     * Get URI to the endpoint
+     * @return string URI to the endpoint
+     */
+    public function getPath() {
+        return "/{databaseId}/recomms/next/item-segments/{$this->recomm_id}";
+    }
+
+    /**
+     * 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();
+        $p['count'] = $this->count;
+        return $p;
+    }
+
+}

tests/NextItemSegmentsRecommendationTestCase.php

@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This file is auto-generated, do not edit
+ */
+
+namespace Recombee\RecommApi\Tests;
+
+use Recombee\RecommApi\Exceptions as Exc;
+use Recombee\RecommApi\Requests as Reqs;
+
+abstract class NextItemSegmentsRecommendationTestCase extends RecombeeTestCase {
+
+    abstract protected function createRequest($recomm_id,$count);
+
+    public function testNextItemSegmentsRecommendation() {
+
+         //it rejects request with invalid recommId
+         $req = new Reqs\RecommendNextItemSegments('invalid_recomm_id',5);
+         try {
+
+             $this->client->send($req);
+             throw new \Exception('Exception was not thrown');
+         }
+         catch(Exc\ResponseException $e)
+         {
+            $this->assertEquals(400, $e->status_code);
+         }
+
+         //it rejects request to recommId which does not return item-segments
+         $req = new Reqs\RecommendItemsToUser('entity_id',3);
+         $resp = $this->client->send($req);
+         $req = $this->createRequest($resp['recommId'],5);
+         try {
+
+             $this->client->send($req);
+             throw new \Exception('Exception was not thrown');
+         }
+         catch(Exc\ResponseException $e)
+         {
+            $this->assertEquals(400, $e->status_code);
+         }
+
+    }
+}

tests/RecommendNextItemSegmentsTest.php

@@ -0,0 +1,10 @@
+<?php
+namespace Recombee\RecommApi\Tests;
+use Recombee\RecommApi\Requests\RecommendNextItemSegments;
+
+class RecommendNextItemSegmentsTest extends NextItemSegmentsRecommendationTestCase {
+
+    protected function createRequest($recomm_id, $count) {
+        return new RecommendNextItemSegments($recomm_id, $count);
+    }
+}